Class CounterCacheBehavior

CounterCache behavior

Enables models to cache the amount of connections in a given relation.

Examples with Post model belonging to User model

Regular counter cache

[
    'Users' => [
        'post_count'
    ]
]

Counter cache with scope

[
    'Users' => [
        'posts_published' => [
            'conditions' => [
                'published' => true
            ]
        ]
    ]
]

Counter cache using custom find

[
    'Users' => [
        'posts_published' => [
            'finder' => 'published' // Will be using findPublished()
        ]
    ]
]

Counter cache using lambda function returning the count This is equivalent to example #2

[
    'Users' => [
        'posts_published' => function (EventInterface $event, EntityInterface $entity, Table $table) {
            $query = $table->find('all')->where([
                'published' => true,
                'user_id' => $entity->get('user_id')
            ]);
            return $query->count();
         }
    ]
]

When using a lambda function you can return false to disable updating the counter value for the current operation.

Ignore updating the field if it is dirty

[
    'Users' => [
        'posts_published' => [
            'ignoreDirty' => true
        ]
    ]
]

You can disable counter updates entirely by sending the ignoreCounterCache option to your save operation:

$this->Articles->save($article, ['ignoreCounterCache' => true]);
Namespace: Cake\ORM\Behavior

Properties summary

  • $_config protected
    array

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Default configuration

  • $_ignoreDirty protected
    array

    Store the fields which should be ignored

  • $_reflectionCache protected static
    array

    Reflection method cache for behaviors.

  • $_table protected
    \Cake\ORM\Table

    Table instance.

Method Summary

Method Detail

__construct() public 

__construct(\Cake\ORM\Table $table, array $config)

Constructor

Merges config with the default and store in the config property

Parameters

\Cake\ORM\Table $table

The table this behavior is attached to.

array $config optional

The config for this behavior.

_configDelete() protected 

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected 

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_getCount() protected 

_getCount(array $config, array $conditions)

Fetches and returns the count for a single field in an association

Parameters

array $config

The counter cache configuration for a single field

array $conditions

Additional conditions given to the query

Returns

int

The number of relations matching the given config and conditions

_processAssociation() protected 

_processAssociation(\Cake\Event\EventInterface $event, \Cake\Datasource\EntityInterface $entity, \Cake\ORM\Association $assoc, array $settings)

Updates counter cache for a single association

Parameters

\Cake\Event\EventInterface $event

Event instance.

\Cake\Datasource\EntityInterface $entity

Entity

\Cake\ORM\Association $assoc

The association object

array $settings

The settings for for counter cache for this association

Throws

RuntimeException
If invalid callable is passed.

_processAssociations() protected 

_processAssociations(\Cake\Event\EventInterface $event, \Cake\Datasource\EntityInterface $entity)

Iterate all associations and update counter caches.

Parameters

\Cake\Event\EventInterface $event

Event instance.

\Cake\Datasource\EntityInterface $entity

Entity.

_reflectionCache() protected 

_reflectionCache()

Gets the methods implemented by this behavior

Uses the implementedEvents() method to exclude callback methods. Methods starting with _ will be ignored, as will methods declared on Cake\ORM\Behavior

Returns

array

Throws

ReflectionException

_resolveMethodAliases() protected 

_resolveMethodAliases(string $key, array $defaults, array $config)

Removes aliased methods that would otherwise be duplicated by userland configuration.

Parameters

string $key

The key to filter.

array $defaults

The default method mappings.

array $config

The customized method mappings.

Returns

array

A de-duped list of config data.

_shouldUpdateCount() protected 

_shouldUpdateCount(array $conditions)

Checks if the count should be updated given a set of conditions.

Parameters

array $conditions

Conditions to update count.

Returns

bool

True if the count update should happen, false otherwise.

afterDelete() public 

afterDelete(\Cake\Event\EventInterface $event, \Cake\Datasource\EntityInterface $entity, \ArrayObject $options)

afterDelete callback.

Makes sure to update counter cache when a record is deleted.

Parameters

\Cake\Event\EventInterface $event

The afterDelete event that was fired.

\Cake\Datasource\EntityInterface $entity

The entity that was deleted.

\ArrayObject $options

The options for the query

afterSave() public 

afterSave(\Cake\Event\EventInterface $event, \Cake\Datasource\EntityInterface $entity, \ArrayObject $options)

afterSave callback.

Makes sure to update counter cache when a new record is created or updated.

Parameters

\Cake\Event\EventInterface $event

The afterSave event that was fired.

\Cake\Datasource\EntityInterface $entity

The entity that was saved.

\ArrayObject $options

The options for the query

beforeSave() public 

beforeSave(\Cake\Event\EventInterface $event, \Cake\Datasource\EntityInterface $entity, \ArrayObject $options)

beforeSave callback.

Check if a field, which should be ignored, is dirty

Parameters

\Cake\Event\EventInterface $event

The beforeSave event that was fired

\Cake\Datasource\EntityInterface $entity

The entity that is going to be saved

\ArrayObject $options

The options for the query

configShallow() public 

configShallow(mixed $key, mixed $value)

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns

$this

getConfig() public 

getConfig(?string $key, mixed $default)

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional

The key to get or null for the whole config.

mixed $default optional

The return value when the key does not exist.

Returns

mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public 

getConfigOrFail(string $key)

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key

The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getTable() public 

getTable()

Get the table instance this behavior is bound to.

Returns

\Cake\ORM\Table

The bound table instance.

implementedEvents() public 

implementedEvents()

Gets the Model callbacks this behavior is interested in.

By defining one of the callback methods a behavior is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want your behavior to listen to non-standard events.

Returns

array

implementedFinders() public 

implementedFinders()

implementedFinders

Provides an alias->methodname map of which finders a behavior implements. Example:

[
   'this' => 'findThis',
   'alias' => 'findMethodName'
 ]

With the above example, a call to $table->find('this') will call $behavior->findThis() and a call to $table->find('alias') will call $behavior->findMethodName()

It is recommended, though not required, to define implementedFinders in the config property of child classes such that it is not necessary to use reflections to derive the available method list. See core behaviors for examples

Returns

array

Throws

ReflectionException

implementedMethods() public 

implementedMethods()

implementedMethods

Provides an alias->methodname map of which methods a behavior implements. Example:

[
   'method' => 'method',
   'aliasedMethod' => 'somethingElse'
 ]

With the above example, a call to $table->method() will call $behavior->method() and a call to $table->aliasedMethod() will call $behavior->somethingElse()

It is recommended, though not required, to define implementedFinders in the config property of child classes such that it is not necessary to use reflections to derive the available method list. See core behaviors for examples

Returns

array

Throws

ReflectionException

initialize() public 

initialize(array $config)

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array $config

The configuration settings provided to this behavior.

setConfig() public 

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

verifyConfig() public 

verifyConfig()

verifyConfig

Checks that implemented keys contain values pointing at callable.

Throws

Cake\Core\Exception\Exception
if config are invalid

Property Detail

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Default configuration

These are merged with user-provided configuration when the behavior is used.

Type

array

$_ignoreDirty protected

Store the fields which should be ignored

Type

array

$_reflectionCache protected static

Reflection method cache for behaviors.

Stores the reflected method + finder methods per class. This prevents reflecting the same class multiple times in a single process.

Type

array

$_table protected

Table instance.

Type

\Cake\ORM\Table

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.ORM.Behavior.CounterCacheBehavior.html