Class Association

An Association is a relationship established between two tables and is used to configure and customize the way interconnected records are retrieved.

Abstract
Namespace: Cake\ORM

Constants summary

string

MANY_TO_MANY

'manyToMany'
string

MANY_TO_ONE

'manyToOne'
string

ONE_TO_MANY

'oneToMany'
string

ONE_TO_ONE

'oneToOne'
string

STRATEGY_JOIN

'join'
string

STRATEGY_SELECT

'select'
string

STRATEGY_SUBQUERY

'subquery'

Properties summary

$_bindingKey protected

string|string[]

The field name in the owning side table that is used to match with the foreignKey
$_cascadeCallbacks protected

bool

Whether or not cascaded deletes should also fire callbacks.
$_className protected

string

The class name of the target table object
$_conditions protected

array|\Closure

A list of conditions to be always included when fetching records from the target association
$_dependent protected

bool

Whether the records on the target table are dependent on the source table, often used to indicate that records should be removed if the owning record in the source table is deleted.
$_finder protected

string|array

The default finder name to use for fetching rows from the target table With array value, finder name and default options are allowed.
$_foreignKey protected

string|string[]

The name of the field representing the foreign key to the table to load
$_joinType protected

string

The type of join to be used when adding the association to a query
$_name protected

string

Name given to the association, it usually represents the alias assigned to the target associated table
$_propertyName protected

string

The property name that should be filled with data from the target table in the source table record.
$_sourceTable protected

\Cake\ORM\Table

Source table instance
$_strategy protected

string

The strategy name to be used to fetch associated records. Some association types might not implement but one strategy to fetch records.
$_tableLocator protected

\Cake\ORM\Locator\LocatorInterface|null

Table locator instance
$_targetTable protected

\Cake\ORM\Table

Target table instance
$_validStrategies protected

string[]

Valid strategies for this association. Subclasses can narrow this down.

Method Summary

__call() public

Proxies method calls to the target table.
__construct() public

Constructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key
__get() public

Proxies property retrieval to the target table. This is handy for getting this association's associations
__isset() public

Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name
_appendFields() protected

Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.
_appendNotMatching() protected

Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.
_bindNewAssociations() protected

Applies all attachable associations to $query out of the containments found in the $surrogate query.
_camelize() protected

Creates a camelized version of $name
_dispatchBeforeFind() protected

Triggers beforeFind on the target table for the query this association is attaching to
_entityName() protected

Creates the proper entity name (singular) for the specified name
_extractFinder() protected

Helper method to infer the requested finder and its options.
_fixtureName() protected

Creates a fixture name
_formatAssociationResults() protected

Adds a formatter function to the passed $query if the $surrogate query declares any other formatter. Since the $surrogate query correspond to the associated target table, the resulting formatter will be the result of applying the surrogate formatters to only the property corresponding to such table.
_joinCondition() protected

Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
_modelKey() protected

Creates the proper underscored model key for associations
_modelNameFromKey() protected

Creates the proper model name from a foreign key
_options() protected

Override this function to initialize any concrete association class, it will get passed the original list of options used in the constructor
_pluginNamespace() protected

Return plugin's namespace
_pluginPath() protected

Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
_pluralHumanName() protected

Creates the plural human name used in views
_propertyName() protected

Returns default property name based on association name.
_singularHumanName() protected

Creates the singular human name used in views
_singularName() protected

Creates the singular name for use in views.
_variableName() protected

Creates the plural variable name for views
attachTo() public

Alters a Query object to include the associated target table data in the final result
canBeJoined() public

Whether this association can be expressed directly in a query join
cascadeDelete() abstract public

Handles cascading a delete from an associated model.
defaultRowValue() public

Returns a modified row after appending a property for this association with the default empty value according to whether the association was joined or fetched externally.
deleteAll() public

Proxies the delete operation to the target table's deleteAll method
eagerLoader() abstract public

Eager loads a list of records in the target table that are related to another set of records in the source table. Source records can specified in two ways: first one is by passing a Query object setup to find on the source table and the other way is by explicitly passing an array of primary key values from the source table.
exists() public

Proxies the operation to the target table's exists method after appending the default conditions for this association
find() public

Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration
getBindingKey() public

Gets the name of the field representing the binding field with the target table.
getCascadeCallbacks() public

Gets whether or not cascaded deletes should also fire callbacks.
getClassName() public

Gets the class name of the target table object.
getConditions() public

Gets a list of conditions to be always included when fetching records from the target association.
getDependent() public

Sets whether the records on the target table are dependent on the source table.
getFinder() public

Gets the default finder to use for fetching rows from the target table.
getForeignKey() public

Gets the name of the field representing the foreign key to the target table.
getJoinType() public

Gets the type of join to be used when adding the association to a query.
getName() public

Gets the name for this association, usually the alias assigned to the target associated table
getProperty() public

Gets the property name that should be filled with data from the target table in the source table record.
getSource() public

Gets the table instance for the source side of the association.
getStrategy() public

Gets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.
getTableLocator() public

Gets the table locator.
getTarget() public

Gets the table instance for the target side of the association.
isOwningSide() abstract public

Returns whether or not the passed table is the owning side for this association. This means that rows in the 'target' table would miss important or required information if the row in 'source' did not exist.
requiresKeys() public

Returns true if the eager loading process will require a set of the owning table's binding keys in order to use them as a filter in the finder query.
saveAssociated() abstract public

Extract the target's association data our from the passed entity and proxies the saving operation to the target table.
setBindingKey() public

Sets the name of the field representing the binding field with the target table.
setCascadeCallbacks() public

Sets whether or not cascaded deletes should also fire callbacks.
setClassName() public

Sets the class name of the target table object.
setConditions() public

Sets a list of conditions to be always included when fetching records from the target association.
setDependent() public

Sets whether the records on the target table are dependent on the source table.
setFinder() public

Sets the default finder to use for fetching rows from the target table.
setForeignKey() public

Sets the name of the field representing the foreign key to the target table.
setJoinType() public

Sets the type of join to be used when adding the association to a query.
setName() public

Sets the name for this association, usually the alias assigned to the target associated table
setProperty() public

Sets the property name that should be filled with data from the target table in the source table record.
setSource() public

Sets the table instance for the source side of the association.
setStrategy() public

Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.
setTableLocator() public

Sets the table locator.
setTarget() public

Sets the table instance for the target side of the association.
transformRow() public

Correctly nests a result row associated values into the correct array keys inside the source results.
type() abstract public

Get the relationship type.
updateAll() public

Proxies the update operation to the target table's updateAll method

Method Detail

__call() public

__call(mixed $method, mixed $argument)

Proxies method calls to the target table.

Parameters

string $method: name of the method to be invoked
array $argument: List of arguments passed to the function

Returns

mixed

Throws

BadMethodCallException

__construct() public

__construct(string $alias, array $options)

Constructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key

Parameters

string $alias: The name given to the association
array $options optional: A list of properties to be set on this object

__get() public

__get(mixed $property)

Proxies property retrieval to the target table. This is handy for getting this association's associations

Parameters

string $property: the property name

Returns

\Cake\ORM\Association

Throws

RuntimeException
if no association with such name exists

__isset() public

__isset(mixed $property)

Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name

Parameters

string $property: the property name

Returns

bool

true if the property exists

_appendFields() protected

_appendFields(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $options)

Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.

Parameters

\Cake\ORM\Query $query: the query that will get the fields appended to
\Cake\ORM\Query $surrogate: the query having the fields to be copied from
array $options: options passed to the method attachTo

_appendNotMatching() protected

_appendNotMatching(\Cake\ORM\Query $query, array $options)

Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.

Parameters

\Cake\ORM\Query $query: The query to modify
array $options: Options array containing the negateMatch key.

_bindNewAssociations() protected

_bindNewAssociations(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $options)

Applies all attachable associations to $query out of the containments found in the $surrogate query.

Copies all contained associations from the $surrogate query into the passed $query. Containments are altered so that they respect the associations chain from which they originated.

Parameters

\Cake\ORM\Query $query: the query that will get the associations attached to
\Cake\ORM\Query $surrogate: the query having the containments to be attached
array $options: options passed to the method attachTo

_camelize() protected

_camelize(string $name)

Creates a camelized version of $name

Parameters

string $name: name

Returns

string

Camelized name

_dispatchBeforeFind() protected

_dispatchBeforeFind(\Cake\ORM\Query $query)

Triggers beforeFind on the target table for the query this association is attaching to

Parameters

\Cake\ORM\Query $query: the query this association is attaching itself to

_entityName() protected

_entityName(string $name)

Creates the proper entity name (singular) for the specified name

Parameters

string $name: Name

Returns

string

Camelized and plural model name

_extractFinder() protected

_extractFinder(mixed $finderData)

Helper method to infer the requested finder and its options.

Returns the inferred options from the finder $type.

Examples:

The following will call the finder 'translations' with the value of the finder as its options: $query->contain(['Comments' => ['finder' => ['translations']]]); $query->contain(['Comments' => ['finder' => ['translations' => []]]]); $query->contain(['Comments' => ['finder' => ['translations' => ['locales' => ['en_US']]]]]);

Parameters

string|array $finderData: The finder name or an array having the name as key and options as value.

Returns

array

_fixtureName() protected

_fixtureName(string $name)

Creates a fixture name

Parameters

string $name: Model class name

Returns

string

Singular model key

_formatAssociationResults() protected

_formatAssociationResults(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $options)

Adds a formatter function to the passed $query if the $surrogate query declares any other formatter. Since the $surrogate query correspond to the associated target table, the resulting formatter will be the result of applying the surrogate formatters to only the property corresponding to such table.

Parameters

\Cake\ORM\Query $query: the query that will get the formatter applied to
\Cake\ORM\Query $surrogate: the query having formatters for the associated target table.
array $options: options passed to the method attachTo

_joinCondition() protected

_joinCondition(array $options)

Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.

Parameters

array $options: list of options passed to attachTo method

Returns

array

Throws

RuntimeException
if the number of columns in the foreignKey do not match the number of columns in the source table primaryKey

_modelKey() protected

_modelKey(string $name)

Creates the proper underscored model key for associations

If the input contains a dot, assume that the right side is the real table name.

Parameters

string $name: Model class name

Returns

string

Singular model key

_modelNameFromKey() protected

_modelNameFromKey(string $key)

Creates the proper model name from a foreign key

Parameters

string $key: Foreign key

Returns

string

Model name

_options() protected

_options(array $options)

Override this function to initialize any concrete association class, it will get passed the original list of options used in the constructor

Parameters

array $options: List of options used for initialization

_pluginNamespace() protected

_pluginNamespace(string $pluginName)

Return plugin's namespace

Parameters

string $pluginName: Plugin name

Returns

string

Plugin's namespace

_pluginPath() protected

_pluginPath(string $pluginName)

Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.

Parameters

string $pluginName: Name of the plugin you want ie. DebugKit

Returns

string

path path to the correct plugin.

_pluralHumanName() protected

_pluralHumanName(string $name)

Creates the plural human name used in views

Parameters

string $name: Controller name

Returns

string

Plural human name

_propertyName() protected

_propertyName()

Returns default property name based on association name.

Returns

string

_singularHumanName() protected

_singularHumanName(string $name)

Creates the singular human name used in views

Parameters

string $name: Controller name

Returns

string

Singular human name

_singularName() protected

_singularName(string $name)

Creates the singular name for use in views.

Parameters

string $name: Name to use

Returns

string

Variable name

_variableName() protected

_variableName(string $name)

Creates the plural variable name for views

Parameters

string $name: Name to use

Returns

string

Plural name for views

attachTo() public

attachTo(\Cake\ORM\Query $query, array $options)

Alters a Query object to include the associated target table data in the final result

The options array accept the following keys:

includeFields: Whether to include target model fields in the result or not
foreignKey: The name of the field to use as foreign key, if false none will be used
conditions: array with a list of conditions to filter the join with, this will be merged with any conditions originally configured for this association
fields: a list of fields in the target table to include in the result
type: The type of join to be used (e.g. INNER) the records found on this association
aliasPath: A dot separated string representing the path of association names followed from the passed query main table to this association.
propertyPath: A dot separated string representing the path of association properties to be followed from the passed query main entity to this association
joinType: The SQL join type to use in the query.
negateMatch: Will append a condition to the passed query for excluding matches. with this association.

Parameters

\Cake\ORM\Query $query: the query to be altered to include the target table data
array $options optional: Any extra options or overrides to be taken in account

Throws

RuntimeException
if the query builder passed does not return a query object

canBeJoined() public

canBeJoined(array $options)

Whether this association can be expressed directly in a query join

Parameters

array $options optional: custom options key that could alter the return value

Returns

bool

cascadeDelete() abstract public

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

Handles cascading a delete from an associated model.

Each implementing class should handle the cascaded delete as required.

Parameters

\Cake\Datasource\EntityInterface $entity: The entity that started the cascaded delete.
array $options optional: The options for the original delete.

Returns

bool

Success

defaultRowValue() public

defaultRowValue(array $row, bool $joined)

Returns a modified row after appending a property for this association with the default empty value according to whether the association was joined or fetched externally.

Parameters

array $row: The row to set a default on.
bool $joined: Whether or not the row is a result of a direct join with this association

Returns

array

deleteAll() public

deleteAll(mixed $conditions)

Proxies the delete operation to the target table's deleteAll method

Parameters

mixed $conditions: Conditions to be used, accepts anything Query::where() can take.

Returns

int

Returns the number of affected rows.

eagerLoader() abstract public

eagerLoader(array $options)

Eager loads a list of records in the target table that are related to another set of records in the source table. Source records can specified in two ways: first one is by passing a Query object setup to find on the source table and the other way is by explicitly passing an array of primary key values from the source table.

The required way of passing related source records is controlled by "strategy" When the subquery strategy is used it will require a query on the source table. When using the select strategy, the list of primary keys will be used.

Returns a closure that should be run for each record returned in a specific Query. This callable will be responsible for injecting the fields that are related to each specific passed row.

Options array accepts the following keys:

query: Query object setup to find the source table records
keys: List of primary key values from the source table
foreignKey: The name of the field used to relate both tables
conditions: List of conditions to be passed to the query where() method
sort: The direction in which the records should be returned
fields: List of fields to select from the target table
contain: List of related tables to eager load associated to the target table
strategy: The name of strategy to use for finding target table records
nestKey: The array key under which results will be found when transforming the row

Parameters

array $options: The options for eager loading.

Returns

\Closure

exists() public

exists(mixed $conditions)

Proxies the operation to the target table's exists method after appending the default conditions for this association

Parameters

array|\Closure|\Cake\Database\ExpressionInterface $conditions: The conditions to use for checking if any record matches.

Returns

bool

find() public

find(mixed $type, array $options)

Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration

Parameters

string|array|null $type optional: the type of query to perform, if an array is passed, it will be interpreted as the $options parameter
array $options optional: The options to for the find

Returns

\Cake\ORM\Query

getBindingKey() public

getBindingKey()

getDependent()

isOwningSide(\Cake\ORM\Table $side)

Returns whether or not the passed table is the owning side for this association. This means that rows in the 'target' table would miss important or required information if the row in 'source' did not exist.

Parameters

\Cake\ORM\Table $side: The potential Table with ownership

Returns

bool

requiresKeys() public

requiresKeys(array $options)

Returns true if the eager loading process will require a set of the owning table's binding keys in order to use them as a filter in the finder query.

Parameters

array $options optional: The options containing the strategy to be used.

Returns

bool

true if a list of keys will be required

saveAssociated() abstract public

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

Extract the target's association data our from the passed entity and proxies the saving operation to the target table.

Parameters

\Cake\Datasource\EntityInterface $entity: the data to be saved
array $options optional: The options for saving associated data.

Returns

\Cake\Datasource\EntityInterface|false

false if $entity could not be saved, otherwise it returns the saved entity

setBindingKey() public

setBindingKey(mixed $key)

Sets the name of the field representing the binding field with the target table.

When not manually specified the primary key of the owning side table is used.

Parameters

string|string[] $key: the table field or fields to be used to link both tables together

Returns

$this

setCascadeCallbacks() public

setCascadeCallbacks(bool $cascadeCallbacks)

Sets whether or not cascaded deletes should also fire callbacks.

Parameters

bool $cascadeCallbacks: cascade callbacks switch value

Returns

$this

setClassName() public

setClassName(string $className)

Sets the class name of the target table object.

Parameters

string $className: Class name to set.

Returns

$this

Throws

InvalidArgumentException
In case the class name is set after the target table has been resolved, and it doesn't match the target table's class name.

setConditions() public

setConditions(mixed $conditions)

Sets a list of conditions to be always included when fetching records from the target association.

Parameters

array|\Closure $conditions: list of conditions to be used

Returns

\Cake\ORM\Association

setDependent() public

setDependent(bool $dependent)

Sets whether the records on the target table are dependent on the source table.

This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.

If no parameters are passed the current setting is returned.

Parameters

bool $dependent: Set the dependent mode. Use null to read the current state.

Returns

$this

setFinder() public

setFinder(mixed $finder)

Sets the default finder to use for fetching rows from the target table.

Parameters

string|array $finder: the finder name to use or array of finder name and option.

Returns

$this

setForeignKey() public

setForeignKey(mixed $key)

Sets the name of the field representing the foreign key to the target table.

Parameters

string|string[] $key: the key or keys to be used to link both tables together

Returns

$this

setJoinType() public

setJoinType(string $type)

Sets the type of join to be used when adding the association to a query.

Parameters

string $type: the join type to be used (e.g. INNER)

Returns

$this

setName() public

setName(string $name)

Sets the name for this association, usually the alias assigned to the target associated table

Parameters

string $name: Name to be assigned

Returns

$this

setProperty() public

setProperty(string $name)

Sets the property name that should be filled with data from the target table in the source table record.

Parameters

string $name: The name of the association property. Use null to read the current value.

Returns

$this

setSource() public

setSource(\Cake\ORM\Table $table)

Sets the table instance for the source side of the association.

Parameters

\Cake\ORM\Table $table: the instance to be assigned as source side

Returns

$this

setStrategy() public

setStrategy(string $name)

Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.

Parameters

string $name: The strategy type. Use null to read the current value.

Returns

$this

Throws

InvalidArgumentException
When an invalid strategy is provided.

setTableLocator() public

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

Sets the table locator.

Parameters

\Cake\ORM\Locator\LocatorInterface $tableLocator: LocatorInterface instance.

Returns

$this

setTarget() public

setTarget(\Cake\ORM\Table $table)

Sets the table instance for the target side of the association.

Parameters

\Cake\ORM\Table $table: the instance to be assigned as target side

Returns

$this

transformRow() public

transformRow(array $row, string $nestKey, bool $joined, ?string $targetProperty)

Correctly nests a result row associated values into the correct array keys inside the source results.

Parameters

array $row: The row to transform
string $nestKey: The array key under which the results for this association should be found
bool $joined: Whether or not the row is a result of a direct join with this association
string|null $targetProperty optional: The property name in the source results where the association data shuld be nested in. Will use the default one if not provided.

Returns

array

type() abstract public

type()

Get the relationship type.

Returns

string

Constant of either ONE_TO_ONE, MANY_TO_ONE, ONE_TO_MANY or MANY_TO_MANY.

updateAll() public

updateAll(array $fields, mixed $conditions)

Proxies the update operation to the target table's updateAll method

Parameters

array $fields: A hash of field => new value.
mixed $conditions: Conditions to be used, accepts anything Query::where() can take.

Returns

int

Count Returns the affected rows.

string[]

© 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.1/class-Cake.ORM.Association.html