CakeDC Blog

Have you ever wondered how to make one database table relate to multiple other tables? Imagine a comments table that needs to store comments for both articles and videos. How do you manage that without creating separate tables or complicated joins?

The answer is a polymorphic relationship. It sounds fancy, but the idea is simple and super powerful.

What's a Polymorphic Relationship?

Think of it this way: instead of a single foreign key pointing to one specific table, a polymorphic relationship uses two columns to define the connection.

Let's stick with our comments example. To link a comment to either an article or a video, your comments table would have these two special columns:

1. foreign_id: This holds the ID of the related record (e.g., the id of an article or the id of a video).
2. model_name: This stores the name of the model the comment belongs to (e.g., 'Articles' or 'Videos').

This flexible setup allows a single comment record to "morph" its relationship, pointing to different types of parent models. It's clean, efficient, and saves you from a lot of redundant code.

It's not necessary for them to be called "foreign_id" and "model_name"; they could have other names (table, model, reference_key, model_id, etc.) as long as you maintain the intended function of each.

Now, let's see how you can set this up in CakePHP 5 without breaking a sweat.

Making It Work in CakePHP 5

While some frameworks have built-in support for polymorphic relationships, CakePHP lets you create them just as easily using its powerful ORM (Object-Relational Mapper) associations. We'll use the conditions key to define the polymorphic link.

Step 1: Set Up Your Database

We'll use a simple schema with three tables: articles, videos, and comments.

-- articles table
CREATE TABLE articles (
    id INT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255)
);

-- videos table
CREATE TABLE videos (
    id INT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255)
);

-- comments table
CREATE TABLE comments (
    id INT AUTO_INCREMENT PRIMARY KEY,
    content TEXT,
    foreign_id INT NOT NULL,
    model_name VARCHAR(50) NOT NULL
);

Notice how the comments table has our special foreign_id and model_name columns.

Step 2: Configure Your Models in CakePHP

Now for the magic! We'll define the associations in our Table classes.

ArticlesTable.php

In this file, you'll tell the Articles model that it has many Comments, but with a specific condition.

// src/Model/Table/ArticlesTable.php

namespace App\Model\Table;

use Cake\ORM\Table;

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        // ...
        $this->hasMany('Comments', [
            'foreignKey' => 'foreign_id',
            'conditions' => ['Comments.model_name' => self::class], // or 'Articles'
            'dependent' => true, // Deletes comments if an article is deleted
        ]);
    }
}

Use self::class is a best practice in modern PHP, as it prevents bugs if you ever decide to rename your classes, and your IDE can auto-complete and check it for you

VideosTable.php

You'll do the same thing for the Videos model, but change the model_name condition.

// src/Model/Table/VideosTable.php

namespace App\Model\Table;

use Cake\ORM\Table;

class VideosTable extends Table
{
    public function initialize(array $config): void
    {
        // ...
        $this->hasMany('Comments', [
            'foreignKey' => 'foreign_id',
            'conditions' => ['Comments.model_name' => self::class], // or 'Videos'
            'dependent' => true,
        ]);
    }
}

CommentsTable.php

This table is the owner of the polymorphic association. You can add associations here to easily access the related Article or Video from a Comment entity.

// src/Model/Table/CommentsTable.php

namespace App\Model\Table;

use Cake\ORM\Table;

class CommentsTable extends Table
{
    public function initialize(array $config): void
    {
        // ...
        $this->belongsTo('Articles', [
            'foreignKey' => 'foreign_id',
            'conditions' => ['Comments.model_name' => \App\Model\Table\ArticlesTable::class], // or 'Articles'
        ]);

        $this->belongsTo('Videos', [
            'foreignKey' => 'foreign_id',
            'conditions' => ['Comments.model_name' => \App\Model\Table\VideosTable::class], // or 'Videos'
        ]);
    }
}

Step 3: Using the Relationship

Now that everything is set up, you can fetch data as if it were a normal association.

Fetching Comments for an Article:

$article = $this->Articles->get(1, ['contain' => 'Comments']);

// $article->comments will contain a list of comments for that article

Creating a new Comment for a Video:

$video = $this->Videos->get(2);
$comment = $this->Comments->newEmptyEntity();

$comment->content = 'This is an awesome video!';
$comment->foreign_id = $video->id;
$comment->model_name = \App\Model\Table\VideosTable::class; // or 'Videos'

$this->Comments->save($comment);

As you can see, the model_name and foreign_id fields are the secret sauce that makes this pattern work.

What About the Future? The Power of This Solution

Now that you've got comments working for both articles and videos, what if your app grows and you want to add comments to a new model, like Photos?

With this polymorphic setup, the change is incredibly simple. You don't need to alter your comments table at all. All you have to do is:

Create your photos table in the database.

Add a new PhotosTable.php model.

In the new PhotosTable's initialize() method, add the hasMany association, just like you did for Articles and Videos.

// src/Model/Table/PhotosTable.php

namespace App\Model\Table;

use Cake\ORM\Table;

class PhotosTable extends Table
{
    public function initialize(array $config): void
    {
        // ...
        $this->hasMany('Comments', [
            'foreignKey' => 'foreign_id',
            'conditions' => ['Comments.model_name' => self::class],
            'dependent' => true,
        ]);
    }
}

That's it! You've just extended your application's functionality with minimal effort. This demonstrates the true power of polymorphic relationships: a single, scalable solution that can easily adapt to your application's evolving needs. It's a key pattern for building flexible and maintainable software.

Conclusion

This approach is flexible, scalable, and a great way to keep your database schema simple. Now that you know the basics, you can start applying this pattern to more complex problems in your own CakePHP applications!