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<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.
-
_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.
-
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.
_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
Parameters
-
array|string$associations The array of included associations.
Returns
array_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
bool_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
boolThrows
InvalidArgumentExceptionWhen an unknown alias is used.
add() ¶ public
add(string $alias, Cake\ORM\Association $association): Cake\ORM\AssociationAdd 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.
Parameters
-
string$alias The association alias
-
Cake\ORM\Association$association The association to add.
Returns
Cake\ORM\AssociationcascadeDelete() ¶ 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(string|null $alias = null, array<string, mixed> $options = []): Cake\ORM\TableConvenience method to get a table instance.
Parameters
-
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
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|nullgetByProperty() ¶ 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|nullgetByType() ¶ 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>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
boolkeys() ¶ public
keys(): array<string>Get the names of all the associations in the collection.
Returns
array<string>load() ¶ public
load(string $className, string $associated, array<string, mixed> $options = []): Cake\ORM\AssociationCreates and adds the Association object to this collection.
Parameters
-
string$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
Cake\ORM\AssociationThrows
InvalidArgumentExceptionnormalizeKeys() ¶ public
normalizeKeys(array|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|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
boolsaveParents() ¶ 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
boolsetTableLocator() ¶ public
setTableLocator(Cake\ORM\Locator\LocatorInterface $tableLocator): $thisSets the table locator.
Parameters
-
Cake\ORM\Locator\LocatorInterface$tableLocator LocatorInterface instance.
Returns
$this