Class AssociationCollection

A container/collection for association classes.

Contains methods for managing associations, and ordering operations around saving and deleting.

Namespace: Cake\ORM

Properties summary

  • $_items protected
    \Cake\ORM\Association[]

    Stored associations

  • $_tableLocator protected
    \Cake\ORM\Locator\LocatorInterface

    Table locator instance

Method Summary

  • __construct() public

    Constructor.

  • _getNoCascadeItems() protected

    Returns items that have no cascade callback.

  • _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.

  • 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.

  • tableLocator() public

    Sets the table locator.

  • type() public

    Get an array of associations matching a specific type.

Method Detail

__construct() public 

__construct(\Cake\ORM\Locator\LocatorInterface $tableLocator)

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.

_getNoCascadeItems() protected 

_getNoCascadeItems(mixed $entity, mixed $options)

Returns items that have no cascade callback.

Parameters

\Cake\Datasource\EntityInterface $entity

The entity to delete associations for.

array $options

The options used in the delete operation.

Returns

\Cake\ORM\Association[]

_normalizeAssociations() protected 

_normalizeAssociations(mixed $associations)

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

Parameters

array|string $associations

The array of included associations.

Returns

array

An array having dot notation transformed into nested arrays

_save() protected 

_save(mixed $association, mixed $entity, mixed $nested, mixed $options)

Helper 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 $nested

Options for deeper associations

array $options

Original options

Returns

bool

Success

_saveAssociations() protected 

_saveAssociations(mixed $table, mixed $entity, mixed $associations, mixed $options, mixed $owningSide)

Helper 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 $options

Original options

bool $owningSide

Compared with association classes' isOwningSide method.

Returns

bool

Success

Throws

InvalidArgumentException
When an unknown alias is used.

add() public 

add(mixed $alias, \Cake\ORM\Association $association)

Add 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\Association

The association object being added.

cascadeDelete() public 

cascadeDelete(\Cake\Datasource\EntityInterface $entity, array $options)

Cascade 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 $options

The options used in the delete operation.

get() public 

get(mixed $alias)

Fetch an attached association by name.

Parameters

string $alias

The association alias to get.

Returns

\Cake\ORM\Association|null

Either the association or null.

getByProperty() public 

getByProperty(mixed $prop)

Fetch an association by property name.

Parameters

string $prop

The property to find an association by.

Returns

\Cake\ORM\Association|null

Either the association or null.

getByType() public 

getByType(mixed $class)

Get an array of associations matching a specific type.

Parameters

string|string[] $class

The type of associations you want. For example 'BelongsTo' or array like ['BelongsTo', 'HasOne']

Returns

array

An array of Association objects.

getIterator() public 

getIterator()

Allow looping through the associations

Returns

\ArrayIterator

getTableLocator() public 

getTableLocator()

Gets the table locator.

Returns

\Cake\ORM\Locator\LocatorInterface

has() public 

has(mixed $alias)

Check for an attached association by name.

Parameters

string $alias

The association alias to get.

Returns

bool

Whether or not the association exists.

keys() public 

keys()

Get the names of all the associations in the collection.

Returns

string[]

load() public 

load(mixed $className, mixed $associated, array $options)

Creates 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 $options optional

List of options to configure the association definition.

Returns

\Cake\ORM\Association

Throws

InvalidArgumentException

normalizeKeys() public 

normalizeKeys(mixed $keys)

Returns an associative array of association names out a mixed array. If true is passed, then it returns all association names in this collection.

Parameters

bool|array $keys

the list of association names to normalize

Returns

array

remove() public 

remove(mixed $alias)

Drop/remove an association.

Once removed the association will not longer be reachable

Parameters

string $alias

The alias name.

removeAll() public 

removeAll()

Remove all registered associations.

Once removed associations will not longer be reachable

saveChildren() public 

saveChildren(\Cake\ORM\Table $table, \Cake\Datasource\EntityInterface $entity, array $associations, array $options)

Save 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 $options

The options for the save operation.

Returns

bool

Success

saveParents() public 

saveParents(\Cake\ORM\Table $table, \Cake\Datasource\EntityInterface $entity, mixed $associations, array $options)

Save 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 $options optional

The options for the save operation.

Returns

bool

Success

setTableLocator() public 

setTableLocator(\Cake\ORM\Locator\LocatorInterface $tableLocator)

Sets the table locator.

Parameters

\Cake\ORM\Locator\LocatorInterface $tableLocator

LocatorInterface instance.

Returns

$this

tableLocator() public 

tableLocator(\Cake\ORM\Locator\LocatorInterface $tableLocator)

Sets the table locator.

If no parameters are passed, it will return the currently used locator.

Parameters

\Cake\ORM\Locator\LocatorInterface|null $tableLocator optional

LocatorInterface instance.

Returns

\Cake\ORM\Locator\LocatorInterface

type() public 

type(mixed $class)

Get an array of associations matching a specific type.

Parameters

string|array $class

The type of associations you want. For example 'BelongsTo' or array like ['BelongsTo', 'HasOne']

Returns

array

An array of Association objects.

Property Detail

$_items protected

Stored associations

Type

\Cake\ORM\Association[]

$_tableLocator protected

Table locator instance

Type

\Cake\ORM\Locator\LocatorInterface

© 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/3.9/class-Cake.ORM.AssociationCollection.html