An Association is a relationship established between two tables and is used to configure and customize the way interconnected records are retrieved.
string
'manyToMany' string
'manyToOne' string
'oneToMany' string
'oneToOne' string
'join' string
'select' string
'subquery' $_bindingKey protected string|array$_cascadeCallbacks protected boolean$_className protected string$_conditions protected arrayA list of conditions to be always included when fetching records from the target association
$_dependent protected booleanWhether 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$_foreignKey protected string|array$_joinType protected string$_name protected stringName given to the association, it usually represents the alias assigned to the target associated table
$_propertyName protected stringThe property name that should be filled with data from the target table in the source table record.
$_sourceTable protected $_strategy protected stringThe strategy name to be used to fetch associated records. Some association types might not implement but one strategy to fetch records.
$_targetTable protected $_validStrategies protected arrayConstructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key
Proxies property retrieval to the target table. This is handy for getting this association's associations
Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name
Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.
Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.
Applies all attachable associations to $query out of the containments found in the $surrogate query.
Triggers beforeFind on the target table for the query this association is attaching to
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.
Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
Override this function to initialize any concrete association class, it will get passed the original list of options used in the constructor
Alters a Query object to include the associated target table data in the final result
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.
Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned
Sets a list of conditions to be always included when fetching records from the target association. If no parameters are passed the current list is returned
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.
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.
Proxies the operation to the target table's exists method after appending the default conditions for this association
Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration
Sets the default finder to use for fetching rows from the target table. If no parameters are passed, it will return the currently configured finder name.
Sets the name of the field representing the foreign key to the target table. If no parameters are passed the current field is returned
Gets 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.
Gets a list of conditions to be always included when fetching records from the target association.
Gets the property name that should be filled with data from the target table in the source table record.
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.
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.
Sets the type of join to be used when adding the association to a query. If no arguments are passed, the currently configured type is returned.
Sets the property name that should be filled with data from the target table in the source table record. If no arguments are passed, the currently configured type is returned.
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.
Extract the target's association data our from the passed entity and proxies the saving operation to the target table.
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.
Sets a list of conditions to be always included when fetching records from the target association.
Sets the property name that should be filled with data from the target table in the source table record.
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.
Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned
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. If no arguments are passed, the currently configured strategy is returned.
Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned
Correctly nests a result row associated values into the correct array keys inside the source results.
__call( string $method , array $argument )
Proxies method calls to the target table.
$method $argument __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
$alias $options optional [] __get( string $property )
Proxies property retrieval to the target table. This is handy for getting this association's associations
$property Cake\ORM\Association__isset( string $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
$property _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.
Cake\ORM\Query $query Cake\ORM\Query $surrogate $options attachTo
_appendNotMatching( Cake\Datasource\QueryInterface $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.
Cake\Datasource\QueryInterface $query $options negateMatch key._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.
Cake\ORM\Query $query Cake\ORM\Query $surrogate $options attachTo
_dispatchBeforeFind( Cake\ORM\Query $query )
Triggers beforeFind on the target table for the query this association is attaching to
Cake\ORM\Query $query _extractFinder( string|array $finderData )
Helper method to infer the requested finder and its options.
Returns the inferred options from the finder $type.
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']]]]]);
$finderData The finder name or an array having the name as key and options as value.
_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.
Cake\ORM\Query $query Cake\ORM\Query $surrogate the query having formatters for the associated target table.
$options attachTo
_getClassName( string $alias , array $options [] )
Gets the table class name.
$alias $options optional [] _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.
$options if the number of columns in the foreignKey do not match the number of columns in the source table primaryKey
_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
$options _propertyName( )
Returns default property name based on association name.
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:
Cake\ORM\Query $query $options optional [] if the query builder passed does not return a query object
bindingKey( string|null $key null )
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.
If no parameters are passed the current field is returned
$key optional null canBeJoined( array $options [] )
Whether this association can be expressed directly in a query join
$options optional [] cascadeCallbacks( boolean|null $cascadeCallbacks null )
Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned
$cascadeCallbacks optional null 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.
Cake\Datasource\EntityInterface $entity $options optional [] conditions( array|null $conditions null )
Sets a list of conditions to be always included when fetching records from the target association. If no parameters are passed the current list is returned
$conditions optional null defaultRowValue( array $row , boolean $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.
$row $joined Whether or not the row is a result of a direct join with this association
deleteAll( mixed $conditions )
Proxies the delete operation to the target table's deleteAll method
$conditions Conditions to be used, accepts anything Query::where() can take.
dependent( boolean|null $dependent null )
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.
$dependent optional null 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:
$options exists( array|callable|Cake\Database\ExpressionInterface $conditions )
Proxies the operation to the target table's exists method after appending the default conditions for this association
Cake\Database\ExpressionInterface $conditions The conditions to use for checking if any record matches.
find( string|array|null $type null , array $options [] )
Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration
$type optional null the type of query to perform, if an array is passed, it will be interpreted as the $options parameter
$options optional [] Cake\ORM\Queryfinder( string|null $finder null )
Sets the default finder to use for fetching rows from the target table. If no parameters are passed, it will return the currently configured finder name.
$finder optional null foreignKey( string|null $key null )
Sets the name of the field representing the foreign key to the target table. If no parameters are passed the current field is returned
$key optional null getBindingKey( )
Gets 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.
getCascadeCallbacks( )
Gets whether or not cascaded deletes should also fire callbacks.
getConditions( )
Gets a list of conditions to be always included when fetching records from the target association.
getDependent( )
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.
getFinder( )
Gets the default finder to use for fetching rows from the target table.
getForeignKey( )
Gets the name of the field representing the foreign key to the target table.
getJoinType( )
Gets the type of join to be used when adding the association to a query.
getProperty( )
Gets the property name that should be filled with data from the target table in the source table record.
getSource( )
Gets the table instance for the source side of the association.
Cake\ORM\TablegetStrategy( )
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.
getTarget( )
Gets the table instance for the target side of the association.
Cake\ORM\TableisOwningSide( 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.
Cake\ORM\Table $side joinType( string|null $type null )
Sets the type of join to be used when adding the association to a query. If no arguments are passed, the currently configured type is returned.
$type optional null name( string|null $name null )
Sets the name for this association.
$name optional null property( string|null $name null )
Sets the property name that should be filled with data from the target table in the source table record. If no arguments are passed, the currently configured type is returned.
$name optional null 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.
$options optional [] 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.
Cake\Datasource\EntityInterface $entity $options optional [] Cake\Datasource\EntityInterfacefalse if $entity could not be saved, otherwise it returns the saved entity
setBindingKey( string $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.
$key setCascadeCallbacks( boolean $cascadeCallbacks )
Sets whether or not cascaded deletes should also fire callbacks.
$cascadeCallbacks setConditions( array $conditions )
Sets a list of conditions to be always included when fetching records from the target association.
$conditions setDependent( boolean $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.
$dependent setFinder( string $finder )
Sets the default finder to use for fetching rows from the target table.
$finder setForeignKey( string $key )
Sets the name of the field representing the foreign key to the target table.
$key setJoinType( string $type )
Sets the type of join to be used when adding the association to a query.
$type setName( string $name )
Sets the name for this association.
$name setProperty( string $name )
Sets the property name that should be filled with data from the target table in the source table record.
$name setSource( Cake\ORM\Table $table )
Sets the table instance for the source side of the association.
Cake\ORM\Table $table 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.
$name setTarget( Cake\ORM\Table $table )
Sets the table instance for the target side of the association.
Cake\ORM\Table $table source( Cake\ORM\Table $table null )
Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned
Cake\ORM\Table $table optional null Cake\ORM\Tablestrategy( string|null $name null )
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. If no arguments are passed, the currently configured strategy is returned.
$name optional null target( Cake\ORM\Table $table null )
Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned
Cake\ORM\Table $table optional null Cake\ORM\TabletransformRow( array $row , string $nestKey , boolean $joined , string|null $targetProperty null )
Correctly nests a result row associated values into the correct array keys inside the source results.
$row $nestKey The array key under which the results for this association should be found
$joined Whether or not the row is a result of a direct join with this association
$targetProperty optional null The property name in the source results where the association data shuld be nested in. Will use the default one if not provided.
type( )
Get the relationship type.
updateAll( array $fields , mixed $conditions )
Proxies the update operation to the target table's updateAll method
$fields $conditions Conditions to be used, accepts anything Query::where() can take.
_camelize( string $name )
Creates a camelized version of $name
$name _entityName( string $name )
Creates the proper entity name (singular) for the specified name
$name _fixtureName( string $name )
Creates a fixture name
$name _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.
$name _modelNameFromKey( string $key )
Creates the proper model name from a foreign key
$key _pluginNamespace( string $pluginName )
Return plugin's namespace
$pluginName _pluginPath( string $pluginName )
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
$pluginName _pluralHumanName( string $name )
Creates the plural human name used in views
$name _singularHumanName( string $name )
Creates the singular human name used in views
$name _singularName( string $name )
Creates the singular name for use in views.
$name _variableName( string $name )
Creates the plural variable name for views
$name tableLocator( Cake\ORM\Locator\LocatorInterface $tableLocator null )
Sets the table locator. If no parameters are passed, it will return the currently used locator.
Cake\ORM\Locator\LocatorInterface $tableLocator optional null Cake\ORM\Locator\LocatorInterfaceprotected string|array
The field name in the owning side table that is used to match with the foreignKey
protected boolean
Whether or not cascaded deletes should also fire callbacks.
false
protected array
A list of conditions to be always included when fetching records from the target association
[]
protected boolean
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.
false
protected string
The default finder name to use for fetching rows from the target table
'all'
protected string|array
The name of the field representing the foreign key to the table to load
protected string
The type of join to be used when adding the association to a query
'LEFT'
protected string
Name given to the association, it usually represents the alias assigned to the target associated table
protected string
The property name that should be filled with data from the target table in the source table record.
protected string
The strategy name to be used to fetch associated records. Some association types might not implement but one strategy to fetch records.
self::STRATEGY_JOIN
protected array
Valid strategies for this association. Subclasses can narrow this down.
[
self::STRATEGY_JOIN,
self::STRATEGY_SELECT,
self::STRATEGY_SUBQUERY
]
© 2005–2017 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.4/class-Cake.ORM.Association.html