Class AssociationCollection
A container/collection for association classes.
Contains methods for managing associations, and ordering operations around saving and deleting.
Property Summary
-
$_items protected
array<string, \Cake\ORM\Association>Stored associations
-
$_tableLocator protected
Cake\ORM\Locator\LocatorInterface|nullTable locator instance
-
$defaultTable protected
string|nullThis object's default table alias.
Method Summary
-
__construct() public
Constructor.
-
_extractAssociations() protected
Extracts association names from options array, separating them from actual options.
-
_normalizeAssociations() protected
Returns an array out of the original passed associations list where dot notation is transformed into nested arrays so that they can be parsed by other routines.
-
_save() protected
Helper method for saving an association's data.
-
_saveAssociations() protected
Helper method for saving an association's data.
-
_shouldExtractAssociations() protected
Determines if an array should have associations extracted from it.
-
add() public
Add an association to the collection
-
cascadeDelete() public
Cascade a delete across the various associations. Cascade first across associations for which cascadeCallbacks is true.
-
fetchTable() public
Convenience method to get a table instance.
-
get() public
Fetch an attached association by name.
-
getByProperty() public
Fetch an association by property name.
-
getByType() public
Get an array of associations matching a specific type.
-
getIterator() public
Allow looping through the associations
-
getTableLocator() public
Gets the table locator.
-
has() public
Check for an attached association by name.
-
keys() public
Get the names of all the associations in the collection.
-
load() public
Creates and adds the Association object to this collection.
-
normalizeKeys() public
Returns an associative array of association names out a mixed array. If true is passed, then it returns all association names in this collection.
-
remove() public
Drop/remove an association.
-
removeAll() public
Remove all registered associations.
-
saveChildren() public
Save all the associations that are children of the given entity.
-
saveParents() public
Save all the associations that are parents of the given entity.
-
setTableLocator() public
Sets the table locator.
Method Detail
__construct() ¶ public
__construct(Cake\ORM\Locator\LocatorInterface|null $tableLocator = null)Constructor.
Sets the default table locator for associations. If no locator is provided, the global one will be used.
Parameters
-
Cake\ORM\Locator\LocatorInterface|null$tableLocator optional Table locator instance.
_extractAssociations() ¶ protected
_extractAssociations(array $options): arrayExtracts association names from options array, separating them from actual options.
Uses CakePHP naming conventions to distinguish associations from options:
- Association names start with uppercase (CamelCase): Users, Articles
- Special data keys start with underscore: _joinData, _ids (treated as associations)
- Option keys start with lowercase (camelCase): onlyIds, conditions
This allows the same nested array format as contain():
- ['Users', 'Comments'] → associations
- ['Users' => [...], 'Comments'] → associations
- ['onlyIds' => true, 'validate' => false] → options only
- ['Users', 'onlyIds' => true] → mixed
Parameters
-
array$options The options array that may contain nested associations.
Returns
arrayAn array with two elements: [associations, options]
_normalizeAssociations() ¶ protected
_normalizeAssociations(array|string $associations): arrayReturns an array out of the original passed associations list where dot notation is transformed into nested arrays so that they can be parsed by other routines.
This method now supports the same nested array format as contain(), allowing:
- Dot notation: ['First.Second']
- Nested arrays: ['First' => ['Second', 'Third']]
- Mixed with options: ['First' => ['Second', 'onlyIds' => true]]
Parameters
-
array|string$associations The array of included associations.
Returns
arrayAn array having dot notation transformed into nested arrays
_save() ¶ protected
_save(Cake\ORM\Association $association, Cake\Datasource\EntityInterface $entity, array<string, mixed> $nested, array<string, mixed> $options): boolHelper method for saving an association's data.
Parameters
-
Cake\ORM\Association$association The association object to save with.
-
Cake\Datasource\EntityInterface$entity The entity to save
-
array<string, mixed>$nested Options for deeper associations
-
array<string, mixed>$options Original options
Returns
boolSuccess
_saveAssociations() ¶ protected
_saveAssociations(Cake\ORM\Table $table, Cake\Datasource\EntityInterface $entity, array $associations, array<string, mixed> $options, bool $owningSide): boolHelper method for saving an association's data.
Parameters
-
Cake\ORM\Table$table The table the save is currently operating on
-
Cake\Datasource\EntityInterface$entity The entity to save
-
array$associations Array of associations to save.
-
array<string, mixed>$options Original options
-
bool$owningSide Compared with association classes' isOwningSide method.
Returns
boolSuccess
Throws
InvalidArgumentExceptionWhen an unknown alias is used.
_shouldExtractAssociations() ¶ protected
_shouldExtractAssociations(array $options): boolDetermines if an array should have associations extracted from it.
Returns true if the array appears to be mixing association names with options, or if it contains nested association structures (like contain() format). Returns false for simple arrays that should be kept as-is.
Uses CakePHP naming conventions to detect associations vs options:
- Association names start with uppercase (CamelCase): Users, Articles
- Option keys start with lowercase (camelCase): onlyIds, conditions
- Special data keys start with underscore: _joinData, _ids
Parameters
-
array$options The options array to check.
Returns
booladd() ¶ public
add(string $alias, T $association): TAdd an association to the collection
If the alias added contains a . the part preceding the . will be dropped.
This makes using plugins simpler as the Plugin.Class syntax is frequently used.
Templates
T
of \Cake\ORM\Association Parameters
-
string$alias The association alias
-
T$association The association to add.
Returns
TThe association object being added.
Throws
Cake\Core\Exception\CakeExceptionIf the alias is already added.
cascadeDelete() ¶ public
cascadeDelete(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options): boolCascade a delete across the various associations. Cascade first across associations for which cascadeCallbacks is true.
Parameters
-
Cake\Datasource\EntityInterface$entity The entity to delete associations for.
-
array<string, mixed>$options The options used in the delete operation.
Returns
boolfetchTable() ¶ public
fetchTable(class-string<T>|string|null $alias = null, array<string, mixed> $options = []): $alias is class-string<T> ? T : \Cake\ORM\TableConvenience method to get a table instance.
Templates
T
of \Cake\ORM\Table Parameters
-
class-string<T>|string|null$alias optional The alias name you want to get. Should be in CamelCase format. If
nullthen the value of $defaultTable property is used.-
array<string, mixed>$options optional The options you want to build the table with. If a table has already been loaded the registry options will be ignored.
Returns
$alias is class-string<T> ? T : \Cake\ORM\TableThrows
Cake\Core\Exception\CakeExceptionIf `$alias` argument and `$defaultTable` property both are `null`.
See Also
get() ¶ public
get(string $alias): Cake\ORM\Association|nullFetch an attached association by name.
Parameters
-
string$alias The association alias to get.
Returns
Cake\ORM\Association|nullEither the association or null.
getByProperty() ¶ public
getByProperty(string $prop): Cake\ORM\Association|nullFetch an association by property name.
Parameters
-
string$prop The property to find an association by.
Returns
Cake\ORM\Association|nullEither the association or null.
getByType() ¶ public
getByType(array<string>|string $class): array<Cake\ORM\Association>Get an array of associations matching a specific type.
Parameters
-
array<string>|string$class The type of associations you want. For example 'BelongsTo' or array like ['BelongsTo', 'HasOne']
Returns
array<Cake\ORM\Association>An array of Association objects.
getIterator() ¶ public
getIterator(): Traversable<string, \Cake\ORM\Association>Allow looping through the associations
Returns
Traversable<string, \Cake\ORM\Association>getTableLocator() ¶ public
getTableLocator(): Cake\ORM\Locator\LocatorInterfaceGets the table locator.
Returns
Cake\ORM\Locator\LocatorInterfacehas() ¶ public
has(string $alias): boolCheck for an attached association by name.
Parameters
-
string$alias The association alias to get.
Returns
boolWhether the association exists.
keys() ¶ public
keys(): array<string>Get the names of all the associations in the collection.
Returns
array<string>load() ¶ public
load(class-string<T> $className, string $associated, array<string, mixed> $options = []): TCreates and adds the Association object to this collection.
Templates
T
of \Cake\ORM\Association Parameters
-
class-string<T>$className The name of association class.
-
string$associated The alias for the target table.
-
array<string, mixed>$options optional List of options to configure the association definition.
Returns
TThrows
InvalidArgumentExceptionnormalizeKeys() ¶ public
normalizeKeys(array|string|bool $keys): arrayReturns an associative array of association names out a mixed array. If true is passed, then it returns all association names in this collection.
Parameters
-
array|string|bool$keys the list of association names to normalize
Returns
arrayremove() ¶ public
remove(string $alias): voidDrop/remove an association.
Once removed the association will no longer be reachable
Parameters
-
string$alias The alias name.
Returns
voidremoveAll() ¶ public
removeAll(): voidRemove all registered associations.
Once removed associations will no longer be reachable
Returns
voidsaveChildren() ¶ public
saveChildren(Cake\ORM\Table $table, Cake\Datasource\EntityInterface $entity, array $associations, array<string, mixed> $options): boolSave all the associations that are children of the given entity.
Child associations include any association where the given table is not the owning side.
Parameters
-
Cake\ORM\Table$table The table entity is for.
-
Cake\Datasource\EntityInterface$entity The entity to save associated data for.
-
array$associations The list of associations to save children from. associations not in this list will not be saved.
-
array<string, mixed>$options The options for the save operation.
Returns
boolSuccess
saveParents() ¶ public
saveParents(Cake\ORM\Table $table, Cake\Datasource\EntityInterface $entity, array $associations, array<string, mixed> $options = []): boolSave all the associations that are parents of the given entity.
Parent associations include any association where the given table is the owning side.
Parameters
-
Cake\ORM\Table$table The table entity is for.
-
Cake\Datasource\EntityInterface$entity The entity to save associated data for.
-
array$associations The list of associations to save parents from. associations not in this list will not be saved.
-
array<string, mixed>$options optional The options for the save operation.
Returns
boolSuccess
setTableLocator() ¶ public
setTableLocator(Cake\ORM\Locator\LocatorInterface $tableLocator): $thisSets the table locator.
Parameters
-
Cake\ORM\Locator\LocatorInterface$tableLocator LocatorInterface instance.
Returns
$this