README

This plugin implements Single Table Inheritance (and hopefully will implement Class Table Inheritance in the future) patterns for CakePHP ORM.

Installation

CakePHP 4.x

Using composer:

composer require robotusers/cakephp-table-inheritance

For CakePHP 3.x use version 0.4 of the plugin

composer require robotusers/cakephp-table-inheritance:^0.4

StiBehavior

For now only STI is supported. Just add a behavior to your tables:

//in ClientsTable:
public function initialize(array $config)
{
    $this->addBehavior('Robotusers/TableInheritance.Sti', [
        'table' => 'users',
        'discriminator' => 'client'
    ]);
}

//alternative config in AdministratorsTable:
public function initialize(array $config)
{
    $this->table('users');
    $this->addBehavior('Robotusers/TableInheritance.Sti');
    $this->setDiscriminator('admin');
}

Now both the ClientsTable and AdministratorsTable will share users db table. A table has to have a discriminator field which will be used to determine which model's record is stored in a row.

Multiple discriminators

You can also configure a list of allowed discriminators. It's useful for example when working with the files. For example:

//in ImagesTable:
public function initialize(array $config)
{
    $this->addBehavior('Robotusers/TableInheritance.Sti', [
        'table' => 'files',
        'discriminatorField' => 'mime',
        'acceptedDiscriminators' => [
            'image/jpeg',
            'image/gif',
            'image/png',
            'image/tiff'
        ]
    ]);
}

//or using wildcards:

public function initialize(array $config)
{
    $this->addBehavior('Robotusers/TableInheritance.Sti', [
        'table' => 'files',
        'discriminatorField' => 'mime',
        'acceptedDiscriminators' => [
            'image/*'
        ]
    ]);
}

An ImagesTable will share files db table and match only specified mime types.

You can also add accepted discriminators on runtime:

$table->addAcceptedDiscriminator('image/bmp');

Configuration

StiBehavior supports following options:

• discriminatorField - db table field used to discriminate models, 'discriminator' by default
• discriminator - default discriminator value, $table->alias() by default
• table - db table to share, use this option or $table->table() method.
• checkRules - true by default. Allows to enable/disable build-in rule check for a discriminator value.
• acceptedDiscriminators - a list of accepted discriminators.

StiParentBehavior

This plugin also allows to configure parent Table in order to create and hydrate entities based on child tables.

//in UsersTable:
public function initialize(array $config)
{
    $this->addBehavior('Robotusers/TableInheritance.StiParent', [
        'tableMap' => [
            'Administrators' => [
                'admin',
                'administrator'
            ],
            'Clients' => 'client'
        ]
    ]);
}

tableMap option accepts an array mapping table registry aliases to discriminator field values.

You can also map discriminator values to specified table objects using discriminatorMap option:

//in UsersTable:
public function initialize(array $config)
{
    $this->addBehavior('Robotusers/TableInheritance.StiParent', [
        'discriminatorMap' => [
            'admin' => $this->tableLocator()->get('Administrators'),
            'client' => $this->tableLocator()->get('Clients')
        ]
    ]);
}

This behavior also provides newStiEntity() method which will proxy newEntity() to one of the configured tables based on a discriminator value.

$data = [
    'name' => 'super-admin',
    'discriminator' => 'admin'
];

$admin = $this->Users->newStiEntity($data); //will call AdministratorsTable::newEntity() and return an Administrator entity instance.

Afterwards you can get a STI table using stiTable() method and handle entity using its source Table object.

$table = $this->Users->stiTable($admin); 
$table->save($admin); //it will save an entity using AdministratorsTable

You can also directly detect STI table from data array:

$data = [
    'name' => 'super-admin',
    'discriminator' => 'admin'
];

$table = $this->Users->stiTable($data);
$admin = $table->newEntity($data);
$table->save($admin);