Behaviors

Behaviors

Behaviors are a way to organize and enable horizontal re-use of Model layerlogic. Conceptually they are similar to traits. However, behaviors areimplemented as separate classes. This allows them to hook into thelife-cycle callbacks that models emit, while providing trait-like features.

Behaviors provide a convenient way to package up behavior that is common acrossmany models. For example, CakePHP includes a TimestampBehavior. Manymodels will want timestamp fields, and the logic to manage these fields isnot specific to any one model. It is these kinds of scenarios that behaviors area perfect fit for.

Using Behaviors

Behaviors provide an easy way to create horizontally re-usable pieces of logicrelated to table classes. You may be wondering why behaviors are regular classesand not traits. The primary reason for this is event listeners. While traitswould allow for re-usable pieces of logic, they would complicate binding events.

To add a behavior to your table you can call the addBehavior() method.Generally the best place to do this is in the initialize() method:

namespace App\Model\Table;
 
use Cake\ORM\Table;
 
class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->addBehavior('Timestamp');
    }
}

As with associations, you can use plugin syntax and provide additionalconfiguration options:

namespace App\Model\Table;
 
use Cake\ORM\Table;
 
class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->addBehavior('Timestamp', [
            'events' => [
                'Model.beforeSave' => [
                    'created_at' => 'new',
                    'modified_at' => 'always'
                ]
            ]
        ]);
    }
}

Core Behaviors

Creating a Behavior

In the following examples we will create a very simple SluggableBehavior.This behavior will allow us to populate a slug field with the results ofText::slug() based on another field.

Before we create our behavior we should understand the conventions forbehaviors:

Behavior files are located in src/Model/Behavior, orMyPlugin\Model\Behavior.
Behavior classes should be in the App\Model\Behavior namespace, orMyPlugin\Model\Behavior namespace.
Behavior class names end in Behavior.
Behaviors extend Cake\ORM\Behavior.

To create our sluggable behavior. Put the following intosrc/Model/Behavior/SluggableBehavior.php:

namespace App\Model\Behavior;
 
use Cake\ORM\Behavior;
 
class SluggableBehavior extends Behavior
{
}

Similar to tables, behaviors also have an initialize() hook where you canput your behavior’s initialization code, if required:

public function initialize(array $config): void
{
    // Some initialization code here
}

We can now add this behavior to one of our table classes. In this example we’lluse an ArticlesTable, as articles often have slug properties for creatingfriendly URLs:

namespace App\Model\Table;
 
use Cake\ORM\Table;
 
class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        $this->addBehavior('Sluggable');
    }
}

Our new behavior doesn’t do much of anything right now. Next, we’ll add a mixinmethod and an event listener so that when we save entities we can automaticallyslug a field.

Defining Mixin Methods

Any public method defined on a behavior will be added as a ‘mixin’ method on thetable object it is attached to. If you attach two behaviors that provide thesame methods an exception will be raised. If a behavior provides the same methodas a table class, the behavior method will not be callable from the table.Behavior mixin methods will receive the exact same arguments that are providedto the table. For example, if our SluggableBehavior defined the followingmethod:

public function slug($value)
{
    return Text::slug($value, $this->_config['replacement']);
}

It could be invoked using:

$slug = $articles->slug('My article name');

Limiting or Renaming Exposed Mixin Methods

When creating behaviors, there may be situations where you don’t want to exposepublic methods as mixin methods. In these cases you can use theimplementedMethods configuration key to rename or exclude mixin methods. Forexample if we wanted to prefix our slug() method we could do the following:

protected $_defaultConfig = [
    'implementedMethods' => [
        'superSlug' => 'slug',
    ]
];

Applying this configuration will make slug() not callable, however it willadd a superSlug() mixin method to the table. Notably if our behaviorimplemented other public methods they would not be available as mixinmethods with the above configuration.

Since the exposed methods are decided by configuration you can alsorename/remove mixin methods when adding a behavior to a table. For example:

// In a table's initialize() method.
$this->addBehavior('Sluggable', [
    'implementedMethods' => [
        'superSlug' => 'slug',
    ]
]);

Defining Event Listeners

Now that our behavior has a mixin method to slug fields, we can implementa callback listener to automatically slug a field when entities are saved. We’llalso modify our slug method to accept an entity instead of just a plain value. Ourbehavior should now look like:

namespace App\Model\Behavior;
 
use ArrayObject;
use Cake\Datasource\EntityInterface;
use Cake\Event\EventInterface;
use Cake\ORM\Behavior;
use Cake\ORM\Entity;
use Cake\ORM\Query;
use Cake\Utility\Text;
 
class SluggableBehavior extends Behavior
{
    protected $_defaultConfig = [
        'field' => 'title',
        'slug' => 'slug',
        'replacement' => '-',
    ];
 
    public function slug(EntityInterface $entity)
    {
        $config = $this->getConfig();
        $value = $entity->get($config['field']);
        $entity->set($config['slug'], Text::slug($value, $config['replacement']));
    }
 
    public function beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)
    {
        $this->slug($entity);
    }
 
}

The above code shows a few interesting features of behaviors:

Behaviors can define callback methods by defining methods that follow theLifecycle Callbacks conventions.
Behaviors can define a default configuration property. This property is mergedwith the overrides when a behavior is attached to the table.

To prevent the save from continuing, simply stop event propagation in your callback:

public function beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)
{
    if (...) {
        $event->stopPropagation();
        $event->setResult(false);
        return;
    }
    $this->slug($entity);
}

Alternatively, you can return false from the callback. This has the same effect as stopping event propagation.

Defining Finders

Now that we are able to save articles with slug values, we should implementa finder method so we can fetch articles by their slug. Behavior findermethods, use the same conventions as Custom Finder Methods do. Ourfind('slug') method would look like:

public function findSlug(Query $query, array $options)
{
    return $query->where(['slug' => $options['slug']]);
}

Once our behavior has the above method we can call it:

$article = $articles->find('slug', ['slug' => $value])->first();

Limiting or Renaming Exposed Finder Methods

When creating behaviors, there may be situations where you don’t want to exposefinder methods, or you need to rename finders to avoid duplicated methods. Inthese cases you can use the implementedFinders configuration key to renameor exclude finder methods. For example if we wanted to rename our find(slug)method we could do the following:

protected $_defaultConfig = [
    'implementedFinders' => [
        'slugged' => 'findSlug',
    ]
];

Applying this configuration will make find('slug') trigger an error. Howeverit will make find('slugged') available. Notably if our behavior implementedother finder methods they would not be available, as they are not includedin the configuration.

Since the exposed methods are decided by configuration you can alsorename/remove finder methods when adding a behavior to a table. For example:

// In a table's initialize() method.
$this->addBehavior('Sluggable', [
    'implementedFinders' => [
        'slugged' => 'findSlug',
    ]
]);

Transforming Request Data into Entity Properties

Behaviors can define logic for how the custom fields they provide aremarshalled by implementing the Cake\ORM\PropertyMarshalInterface. Thisinterface requires a single method to be implemented:

public function buildMarshalMap($marshaller, $map, $options)
{
    return [
        'custom_behavior_field' => function ($value, $entity) {
            // Transform the value as necessary
            return $value . '123';
        }
    ];
}

The TranslateBehavior has a non-trivial implementation of this interfacethat you might want to refer to.

Removing Loaded Behaviors

To remove a behavior from your table you can call the removeBehavior() method:

// Remove the loaded behavior
$this->removeBehavior('Sluggable');

Accessing Loaded Behaviors

Once you’ve attached behaviors to your Table instance you can introspect theloaded behaviors, or access specific behaviors using the BehaviorRegistry:

// See which behaviors are loaded
$table->behaviors()->loaded();
 
// Check if a specific behavior is loaded.
// Remember to omit plugin prefixes.
$table->behaviors()->has('CounterCache');
 
// Get a loaded behavior
// Remember to omit plugin prefixes
$table->behaviors()->get('CounterCache');

Re-configuring Loaded Behaviors

To modify the configuration of an already loaded behavior you can combine theBehaviorRegistry::get command with config command provided by theInstanceConfigTrait trait.

For example if a parent (e.g. an AppTable) class loaded the Timestampbehavior you could do the following to add, modify or remove the configurationsfor the behavior. In this case, we will add an event we want Timestamp torespond to:

namespace App\Model\Table;
 
use App\Model\Table\AppTable; // similar to AppController
 
class UsersTable extends AppTable
{
    public function initialize(array $options): void
    {
        parent::initialize($options);
 
        // e.g. if our parent calls $this->addBehavior('Timestamp');
        // and we want to add an additional event
        if ($this->behaviors()->has('Timestamp')) {
            $this->behaviors()->get('Timestamp')->setConfig([
                'events' => [
                    'Users.login' => [
                        'last_login' => 'always'
                    ],
                ],
            ]);
        }
    }
}