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]);Property Summary
-
$_config protected
array<string, mixed>Runtime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_defaultConfig protected
array<string, mixed>Default configuration
-
$_ignoreDirty protected
array<string, array<string, bool>>Store the fields which should be ignored
-
$_reflectionCache protected static
array<string, array>Reflection method cache for behaviors.
-
$_table protected
Cake\ORM\TableTable instance.
Method Summary
-
__construct() public
Constructor
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
_getCount() protected
Fetches and returns the count for a single field in an association
-
_processAssociation() protected
Updates counter cache for a single association
-
_processAssociations() protected
Iterate all associations and update counter caches.
-
_reflectionCache() protected
Gets the methods implemented by this behavior
-
_resolveMethodAliases() protected
Removes aliased methods that would otherwise be duplicated by userland configuration.
-
_shouldUpdateCount() protected
Checks if the count should be updated given a set of conditions.
-
afterDelete() public
afterDelete callback.
-
afterSave() public
afterSave callback.
-
beforeSave() public
beforeSave callback.
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
getTable() public deprecated
Get the table instance this behavior is bound to.
-
implementedEvents() public
Gets the Model callbacks this behavior is interested in.
-
implementedFinders() public
implementedFinders
-
implementedMethods() public
implementedMethods
-
initialize() public
Constructor hook method.
-
setConfig() public
Sets the config.
-
table() public
Get the table instance this behavior is bound to.
-
verifyConfig() public
verifyConfig
Method Detail
__construct() ¶ public
__construct(Cake\ORM\Table $table, array<string, mixed> $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<string, mixed>$config optional The config for this behavior.
_configDelete() ¶ protected
_configDelete(string $key): voidDeletes a single config key.
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixedReads a config key.
Parameters
-
string|null$key Key to read.
Returns
mixed_configWrite() ¶ protected
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): voidWrites a config key.
Parameters
-
array<string, mixed>|string$key Key to write to.
-
mixed$value Value to write.
-
string|bool$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_getCount() ¶ protected
_getCount(array<string, mixed> $config, array $conditions): intFetches and returns the count for a single field in an association
Parameters
-
array<string, mixed>$config The counter cache configuration for a single field
-
array$conditions Additional conditions given to the query
Returns
int_processAssociation() ¶ protected
_processAssociation(Cake\Event\EventInterface $event, Cake\Datasource\EntityInterface $entity, Cake\ORM\Association $assoc, array $settings): voidUpdates 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 counter cache for this association
Returns
voidThrows
RuntimeExceptionIf invalid callable is passed.
_processAssociations() ¶ protected
_processAssociations(Cake\Event\EventInterface $event, Cake\Datasource\EntityInterface $entity): voidIterate all associations and update counter caches.
Parameters
-
Cake\Event\EventInterface$event Event instance.
-
Cake\Datasource\EntityInterface$entity Entity.
Returns
void_reflectionCache() ¶ protected
_reflectionCache(): arrayGets 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
arrayThrows
ReflectionException_resolveMethodAliases() ¶ protected
_resolveMethodAliases(string $key, array<string, mixed> $defaults, array<string, mixed> $config): arrayRemoves aliased methods that would otherwise be duplicated by userland configuration.
Parameters
-
string$key The key to filter.
-
array<string, mixed>$defaults The default method mappings.
-
array<string, mixed>$config The customized method mappings.
Returns
array_shouldUpdateCount() ¶ protected
_shouldUpdateCount(array $conditions): boolChecks if the count should be updated given a set of conditions.
Parameters
-
array$conditions Conditions to update count.
Returns
boolafterDelete() ¶ public
afterDelete(Cake\Event\EventInterface $event, Cake\Datasource\EntityInterface $entity, ArrayObject $options): voidafterDelete 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
Returns
voidafterSave() ¶ public
afterSave(Cake\Event\EventInterface $event, Cake\Datasource\EntityInterface $entity, ArrayObject $options): voidafterSave 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
Returns
voidbeforeSave() ¶ public
beforeSave(Cake\Event\EventInterface $event, Cake\Datasource\EntityInterface $entity, ArrayObject $options): voidbeforeSave 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
Returns
voidconfigShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $thisMerge 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
-
array<string, mixed>|string$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
Returns
$thisgetConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): mixedReturns 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
mixedgetConfigOrFail() ¶ public
getConfigOrFail(string $key): mixedReturns 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
mixedThrows
InvalidArgumentExceptiongetTable() ¶ public
getTable(): Cake\ORM\TableGet the table instance this behavior is bound to.
Returns
Cake\ORM\TableimplementedEvents() ¶ public
implementedEvents(): array<string, mixed>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<string, mixed>implementedFinders() ¶ public
implementedFinders(): arrayimplementedFinders
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
arrayThrows
ReflectionExceptionimplementedMethods() ¶ public
implementedMethods(): arrayimplementedMethods
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
arrayThrows
ReflectionExceptioninitialize() ¶ public
initialize(array<string, mixed> $config): voidConstructor hook method.
Implement this method to avoid having to overwrite the constructor and call parent.
Parameters
-
array<string, mixed>$config The configuration settings provided to this behavior.
Returns
voidsetConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $thisSets 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
-
array<string, mixed>|string$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
$thisThrows
Cake\Core\Exception\CakeExceptionWhen trying to set a key that is invalid.
table() ¶ public
table(): Cake\ORM\TableGet the table instance this behavior is bound to.
Returns
Cake\ORM\TableverifyConfig() ¶ public
verifyConfig(): voidverifyConfig
Checks that implemented keys contain values pointing at callable.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif config are invalid
Property Detail
$_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<string, mixed>$_ignoreDirty ¶ protected
Store the fields which should be ignored
Type
array<string, array<string, bool>>$_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<string, array>