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'
string|string[]
The field name in the owning side table that is used to match with the foreignKey
bool
Whether or not cascaded deletes should also fire callbacks.
string
The class name of the target table object
array|\Closure
A list of conditions to be always included when fetching records from the target association
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.
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.
string|string[]
The name of the field representing the foreign key to the table to load
string
The type of join to be used when adding the association to a query
string
Name given to the association, it usually represents the alias assigned to the target associated table
string
The property name that should be filled with data from the target table in the source table record.
\Cake\ORM\Table
Source table instance
string
The strategy name to be used to fetch associated records. Some association types might not implement but one strategy to fetch records.
\Cake\ORM\Locator\LocatorInterface|null
Table locator instance
\Cake\ORM\Table
Target table instance
string[]
Valid strategies for this association. Subclasses can narrow this down.
Constructor. 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
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
Alters a Query object to include the associated target table data in the final result
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
Gets the name of the field representing the binding field with the target table.
Gets a list of conditions to be always included when fetching records from the target association.
Sets whether the records on the target table are dependent on the source table.
Gets the name for this association, usually the alias assigned to the target associated table
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.
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.
Sets a list of conditions to be always included when fetching records from the target association.
Sets whether the records on the target table are dependent on the source table.
Sets the name for this association, usually the alias assigned to the target associated table
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.
Correctly nests a result row associated values into the correct array keys inside the source results.
__call(mixed $method, mixed $argument)
Proxies method calls to the target table.
string
$method name of the method to be invoked
array
$argument List of arguments passed to the function
mixed
BadMethodCallException
__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
string
$alias The name given to the association
array
$options optional A list of properties to be set on this object
__get(mixed $property)
Proxies property retrieval to the target table. This is handy for getting this association's associations
string
$property the property name
\Cake\ORM\Association
RuntimeException
__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
string
$property the property name
bool
true if the property exists
_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 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(\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.
\Cake\ORM\Query
$query The query to modify
array
$options Options array containing the 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 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(string $name)
Creates a camelized version of $name
string
$name name
string
Camelized name
_dispatchBeforeFind(\Cake\ORM\Query $query)
Triggers beforeFind on the target table for the query this association is attaching to
\Cake\ORM\Query
$query the query this association is attaching itself to
_entityName(string $name)
Creates the proper entity name (singular) for the specified name
string
$name Name
string
Camelized and plural model name
_extractFinder(mixed $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']]]]]);
string|array
$finderData The finder name or an array having the name as key and options as value.
array
_fixtureName(string $name)
Creates a fixture name
string
$name Model class name
string
Singular model key
_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 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(array $options)
Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
array
$options list of options passed to attachTo method
array
RuntimeException
_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.
string
$name Model class name
string
Singular model key
_modelNameFromKey(string $key)
Creates the proper model name from a foreign key
string
$key Foreign key
string
Model name
_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
array
$options List of options used for initialization
_pluginNamespace(string $pluginName)
Return plugin's namespace
string
$pluginName Plugin name
string
Plugin's namespace
_pluginPath(string $pluginName)
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
string
$pluginName Name of the plugin you want ie. DebugKit
string
path path to the correct plugin.
_pluralHumanName(string $name)
Creates the plural human name used in views
string
$name Controller name
string
Plural human name
_propertyName()
Returns default property name based on association name.
string
_singularHumanName(string $name)
Creates the singular human name used in views
string
$name Controller name
string
Singular human name
_singularName(string $name)
Creates the singular name for use in views.
string
$name Name to use
string
Variable name
_variableName(string $name)
Creates the plural variable name for views
string
$name Name to use
string
Plural name for views
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 the query to be altered to include the target table data
array
$options optional Any extra options or overrides to be taken in account
RuntimeException
canBeJoined(array $options)
Whether this association can be expressed directly in a query join
array
$options optional custom options key that could alter the return value
bool
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 The entity that started the cascaded delete.
array
$options optional The options for the original delete.
bool
Success
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.
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
array
deleteAll(mixed $conditions)
Proxies the delete operation to the target table's deleteAll method
mixed
$conditions Conditions to be used, accepts anything Query::where() can take.
int
Returns the number of affected rows.
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:
array
$options The options for eager loading.
\Closure
exists(mixed $conditions)
Proxies the operation to the target table's exists method after appending the default conditions for this association
array|\Closure|\Cake\Database\ExpressionInterface
$conditions The conditions to use for checking if any record matches.
bool
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
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
\Cake\ORM\Query
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.
string|string[]
getCascadeCallbacks()
Gets whether or not cascaded deletes should also fire callbacks.
bool
getClassName()
Gets the class name of the target table object.
string
getConditions()
Gets a list of conditions to be always included when fetching records from the target association.
array|\Closure
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.
bool
getFinder()
Gets the default finder to use for fetching rows from the target table.
string|array
getForeignKey()
Gets the name of the field representing the foreign key to the target table.
string|string[]
getJoinType()
Gets the type of join to be used when adding the association to a query.
string
getName()
Gets the name for this association, usually the alias assigned to the target associated table
string
getProperty()
Gets the property name that should be filled with data from the target table in the source table record.
string
getSource()
Gets the table instance for the source side of the association.
\Cake\ORM\Table
getStrategy()
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.
string
getTableLocator()
Gets the table locator.
\Cake\ORM\Locator\LocatorInterface
getTarget()
Gets the table instance for the target side of the association.
\Cake\ORM\Table
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.
\Cake\ORM\Table
$side The potential Table with ownership
bool
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.
array
$options optional The options containing the strategy to be used.
bool
true if a list of keys will be required
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 the data to be saved
array
$options optional The options for saving associated data.
\Cake\Datasource\EntityInterface|false
false if $entity could not be saved, otherwise it returns the saved entity
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.
string|string[]
$key the table field or fields to be used to link both tables together
$this
setCascadeCallbacks(bool $cascadeCallbacks)
Sets whether or not cascaded deletes should also fire callbacks.
bool
$cascadeCallbacks cascade callbacks switch value
$this
setClassName(string $className)
Sets the class name of the target table object.
string
$className Class name to set.
$this
InvalidArgumentException
setConditions(mixed $conditions)
Sets a list of conditions to be always included when fetching records from the target association.
array|\Closure
$conditions list of conditions to be used
\Cake\ORM\Association
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.
bool
$dependent Set the dependent mode. Use null to read the current state.
$this
setFinder(mixed $finder)
Sets the default finder to use for fetching rows from the target table.
string|array
$finder the finder name to use or array of finder name and option.
$this
setForeignKey(mixed $key)
Sets the name of the field representing the foreign key to the target table.
string|string[]
$key the key or keys to be used to link both tables together
$this
setJoinType(string $type)
Sets the type of join to be used when adding the association to a query.
string
$type the join type to be used (e.g. INNER)
$this
setName(string $name)
Sets the name for this association, usually the alias assigned to the target associated table
string
$name Name to be assigned
$this
setProperty(string $name)
Sets the property name that should be filled with data from the target table in the source table record.
string
$name The name of the association property. Use null to read the current value.
$this
setSource(\Cake\ORM\Table $table)
Sets the table instance for the source side of the association.
\Cake\ORM\Table
$table the instance to be assigned as source side
$this
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.
string
$name The strategy type. Use null to read the current value.
$this
InvalidArgumentException
setTableLocator(\Cake\ORM\Locator\LocatorInterface $tableLocator)
Sets the table locator.
\Cake\ORM\Locator\LocatorInterface
$tableLocator LocatorInterface instance.
$this
setTarget(\Cake\ORM\Table $table)
Sets the table instance for the target side of the association.
\Cake\ORM\Table
$table the instance to be assigned as target side
$this
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.
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.
array
type()
Get the relationship type.
string
Constant of either ONE_TO_ONE, MANY_TO_ONE, ONE_TO_MANY or MANY_TO_MANY.
updateAll(array $fields, mixed $conditions)
Proxies the update operation to the target table's updateAll method
array
$fields A hash of field => new value.
mixed
$conditions Conditions to be used, accepts anything Query::where() can take.
int
Count Returns the affected rows.
The field name in the owning side table that is used to match with the foreignKey
string|string[]
Whether or not cascaded deletes should also fire callbacks.
bool
The class name of the target table object
string
A list of conditions to be always included when fetching records from the target association
array|\Closure
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.
bool
The default finder name to use for fetching rows from the target table With array value, finder name and default options are allowed.
string|array
The name of the field representing the foreign key to the table to load
string|string[]
The type of join to be used when adding the association to a query
string
Name given to the association, it usually represents the alias assigned to the target associated table
string
The property name that should be filled with data from the target table in the source table record.
string
Source table instance
\Cake\ORM\Table
The strategy name to be used to fetch associated records. Some association types might not implement but one strategy to fetch records.
string
Table locator instance
\Cake\ORM\Locator\LocatorInterface|null
Target table instance
\Cake\ORM\Table
Valid strategies for this association. Subclasses can narrow this down.
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