W3cubDocs

/CakePHP 4.4

Class AssociationCollection

A container/collection for association classes.

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

Namespace: Cake\ORM

Property Summary

  • $_items protected
    arrayCake\ORM\Association>

    Stored associations

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

    Table locator instance

  • $defaultTable protected
    string|null

    This 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): array

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

_save() protected 

_save(Cake\ORM\Association $association, Cake\Datasource\EntityInterface $entity, array<string, mixed> $nested, array<string, mixed> $options): bool

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<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): bool

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<string, mixed> $options

Original options

bool $owningSide

Compared with association classes' isOwningSide method.

Returns

bool

Throws

InvalidArgumentException
When an unknown alias is used.

add() public 

add(string $alias, Cake\ORM\Association $association): Cake\ORM\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

cascadeDelete() public 

cascadeDelete(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options): bool

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<string, mixed> $options

The options used in the delete operation.

Returns

bool

fetchTable() public 

fetchTable(string|null $alias = null, array<string, mixed> $options = []): Cake\ORM\Table

Convenience method to get a table instance.

Parameters

string|null $alias optional

The alias name you want to get. Should be in CamelCase format. If null then 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\Table

Throws

Cake\Core\Exception\CakeException
If `$alias` argument and `$defaultTable` property both are `null`.

See Also

\Cake\ORM\TableLocator::get()

get() public 

get(string $alias): Cake\ORM\Association|null

Fetch an attached association by name.

Parameters

string $alias

The association alias to get.

Returns

Cake\ORM\Association|null

getByProperty() public 

getByProperty(string $prop): Cake\ORM\Association|null

Fetch an association by property name.

Parameters

string $prop

The property to find an association by.

Returns

Cake\ORM\Association|null

getByType() public 

getByType(array<string>|string $class): arrayCake\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

arrayCake\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\LocatorInterface

Gets the table locator.

Returns

Cake\ORM\Locator\LocatorInterface

has() public 

has(string $alias): bool

Check for an attached association by name.

Parameters

string $alias

The association alias to get.

Returns

bool

keys() 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\Association

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<string, mixed> $options optional

List of options to configure the association definition.

Returns

Cake\ORM\Association

Throws

InvalidArgumentException

normalizeKeys() public 

normalizeKeys(array|bool $keys): array

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

array|bool $keys

the list of association names to normalize

Returns

array

remove() public 

remove(string $alias): void

Drop/remove an association.

Once removed the association will no longer be reachable

Parameters

string $alias

The alias name.

Returns

void

removeAll() public 

removeAll(): void

Remove all registered associations.

Once removed associations will no longer be reachable

Returns

void

saveChildren() public 

saveChildren(Cake\ORM\Table $table, Cake\Datasource\EntityInterface $entity, array $associations, array<string, mixed> $options): bool

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<string, mixed> $options

The options for the save operation.

Returns

bool

saveParents() public 

saveParents(Cake\ORM\Table $table, Cake\Datasource\EntityInterface $entity, array $associations, array<string, mixed> $options = []): bool

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<string, mixed> $options optional

The options for the save operation.

Returns

bool

setTableLocator() public 

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

Sets the table locator.

Parameters

Cake\ORM\Locator\LocatorInterface $tableLocator

LocatorInterface instance.

Returns

$this

Property Detail

$_items protected

Stored associations

Type

arrayCake\ORM\Association>

$_tableLocator protected

Table locator instance

Type

Cake\ORM\Locator\LocatorInterface|null

$defaultTable protected

This object's default table alias.

Type

string|null

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