Class BelongsToMany
Represents an M - N relationship where there exists a junction - or join - table that contains the association fields between the source and the target table.
An example of a BelongsToMany association would be Article belongs to many Tags. In this example 'Article' is the source table and 'Tags' is the target table.
Constants
-
string
MANY_TO_MANY ¶'manyToMany'
Association type for many to many associations.
-
string
MANY_TO_ONE ¶'manyToOne'
Association type for many to one associations.
-
string
ONE_TO_MANY ¶'oneToMany'
Association type for one to many associations.
-
string
ONE_TO_ONE ¶'oneToOne'
Association type for one to one associations.
-
string
SAVE_APPEND ¶'append'
Saving strategy that will only append to the links set
-
string
SAVE_REPLACE ¶'replace'
Saving strategy that will replace the links with the provided set
-
string
STRATEGY_JOIN ¶'join'
Strategy name to use joins for fetching associated records
-
string
STRATEGY_SELECT ¶'select'
Strategy name to use a select for fetching associated records
-
string
STRATEGY_SUBQUERY ¶'subquery'
Strategy name to use a subquery for fetching associated records
Property Summary
-
$_bindingKey protected
array<string>|string|null
The field name in the owning side table that is used to match with the foreignKey
-
$_cascadeCallbacks protected
bool
Whether cascaded deletes should also fire callbacks.
-
$_className protected
string
The class name of the target table object
-
$_conditions protected
Closure|array
A list of conditions to be always included when fetching records from the target association
-
$_dependent protected
bool
Whether the records on the joint table should be removed when a record on the source table is deleted.
-
$_finder protected
array|string
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
array<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
-
$_junctionAssociationName protected
string
The name of the hasMany association from the target table to the junction table
-
$_junctionConditions protected
array|null
Filtered conditions that reference the junction table.
-
$_junctionProperty protected
string
The name of the property to be set containing data from the junction table once a record from the target table is hydrated
-
$_junctionTable protected
Cake\ORM\Table
Junction table instance
-
$_junctionTableName protected
string
Junction table name
-
$_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.
-
$_saveStrategy protected
string
Saving strategy to be used by this association
-
$_sort protected
mixed
Order in which target records should be returned
-
$_sourceTable protected
Cake\ORM\Table
Source table instance
-
$_strategy protected
string
The strategy name to be used to fetch associated records.
-
$_tableLocator protected
Cake\ORM\Locator\LocatorInterface|null
Table locator instance
-
$_targetConditions protected
array|null
Filtered conditions that reference the target table.
-
$_targetForeignKey protected
array<string>|string|null
The name of the field representing the foreign key to the target table
-
$_targetTable protected
Cake\ORM\Table
Target table instance
-
$_through protected
Cake\ORM\Table|string
The table instance for the junction relation.
-
$_validStrategies protected
array<string>
Valid strategies for this type of association
-
$defaultTable protected
string|null
This object's default table alias.
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.
-
_appendJunctionJoin() protected
Append a join to the junction table.
-
_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
-
_checkPersistenceStatus() protected
Throws an exception should any of the passed entities is not persisted.
-
_collectJointEntities() protected
Returns the list of joint entities that exist between the source entity and each of the passed target entities
-
_diffLinks() protected
Helper method used to delete the difference between the links passed in
$existing
and$jointEntities
. This method will return the values from$targetEntities
that were not deleted from calculating the difference. -
_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. -
_generateJunctionAssociations() protected
Generate associations on the junction table as necessary
-
_generateSourceAssociations() protected
Generate additional source table associations as necessary.
-
_generateTargetAssociations() protected
Generate reciprocal associations as necessary.
-
_joinCondition() protected
Return false as join conditions are defined in the junction table
-
_junctionAssociationName() protected
Returns the name of the association from the target table to the junction table, this name is used to generate alias in the query and to later on retrieve the results.
-
_junctionTableName() protected
Sets the name of the junction table. If no arguments are passed the current configured name is returned. A default name based of the associated tables will be generated if none found.
-
_modelKey() protected
Creates the proper underscored model key for associations
-
_modelNameFromKey() protected
Creates the proper model name from a foreign key
-
_options() protected
Parse extra options passed 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.
-
_saveLinks() protected
Creates links between the source entity and each of the passed target entities
-
_saveTarget() protected
Persists each of the entities into the target table and creates links between the parent entity and each one of the saved target entities.
-
_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() public
Clear out the data in the junction table for a given entity.
-
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() 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 be 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
-
fetchTable() public
Convenience method to get a table instance.
-
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. When not manually specified the primary key of the owning side table is used.
-
getCascadeCallbacks() public
Gets whether 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 source 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.
-
getSaveStrategy() public
Gets the strategy that should be used for saving.
-
getSort() public
Gets the sort order in which target records should be returned.
-
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.
-
getTargetForeignKey() public
Gets the name of the field representing the foreign key to the target table.
-
getThrough() public
Gets the current join table, either the name of the Table instance or the instance itself.
-
isOwningSide() public
Returns boolean true, as both of the tables 'own' rows in the other side of the association via the joint table.
-
junction() public
Sets the table instance for the junction relation. If no arguments are passed, the current configured table instance is returned
-
junctionConditions() protected
Returns filtered conditions that specifically reference the junction table.
-
link() public
Associates the source entity to each of the target entities provided by creating links in the junction table. Both the source entity and each of the target entities are assumed to be already persisted, if they are marked as new or their status is unknown then an exception will be thrown.
-
replaceLinks() public
Replaces existing association links between the source entity and the target with the ones passed. This method does a smart cleanup, links that are already persisted and present in
$targetEntities
will not be deleted, new links will be created for the passed target entities that are not already in the database and the rest will be removed. -
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() public
Takes an entity from the source table and looks if there is a field matching the property name for this association. The found entity will be saved on the target table for this association by passing supplied
$options
-
setBindingKey() public
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.
-
setCascadeCallbacks() public
Sets whether 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 deprecated
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.
-
setSaveStrategy() public
Sets the strategy that should be used for saving.
-
setSort() public
Sets the sort order in which target records should be returned.
-
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.
-
setTargetForeignKey() public
Sets the name of the field representing the foreign key to the target table.
-
setThrough() public
Sets the current join table, either the name of the Table instance or the instance itself.
-
targetConditions() protected
Returns filtered conditions that reference the target table.
-
transformRow() public
Correctly nests a result row associated values into the correct array keys inside the source results.
-
type() public
Get the relationship type.
-
unlink() public
Removes all links between the passed source entity and each of the provided target entities. This method assumes that all passed objects are already persisted in the database and that each of them contain a primary key value.
-
updateAll() public
Proxies the update operation to the target table's updateAll method
Method Detail
__call() ¶ public
__call(string $method, array $argument): mixed
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<string, mixed> $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<string, mixed>
$options optional A list of properties to be set on this object
__get() ¶ public
__get(string $property): Cake\ORM\Association
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(string $property): bool
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
_appendFields() ¶ protected
_appendFields(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array<string, mixed> $options): void
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<string, mixed>
$options options passed to the method
attachTo
Returns
void
_appendJunctionJoin() ¶ protected
_appendJunctionJoin(Cake\ORM\Query $query, array|null $conditions = null): Cake\ORM\Query
Append a join to the junction table.
Parameters
-
Cake\ORM\Query
$query The query to append.
-
array|null
$conditions optional The query conditions to use.
Returns
Cake\ORM\Query
_appendNotMatching() ¶ protected
_appendNotMatching(Cake\ORM\Query $query, array<string, mixed> $options): void
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 -
array<string, mixed>
$options
Returns
void
_bindNewAssociations() ¶ protected
_bindNewAssociations(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array<string, mixed> $options): void
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<string, mixed>
$options options passed to the method
attachTo
Returns
void
_camelize() ¶ protected
_camelize(string $name): string
Creates a camelized version of $name
Parameters
-
string
$name name
Returns
string
_checkPersistenceStatus() ¶ protected
_checkPersistenceStatus(Cake\Datasource\EntityInterface $sourceEntity, array<Cake\Datasource\EntityInterface> $targetEntities): bool
Throws an exception should any of the passed entities is not persisted.
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity the row belonging to the
source
side of this association-
array<Cake\Datasource\EntityInterface>
$targetEntities list of entities belonging to the
target
side of this association
Returns
bool
Throws
InvalidArgumentException
_collectJointEntities() ¶ protected
_collectJointEntities(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities): array<Cake\Datasource\EntityInterface>
Returns the list of joint entities that exist between the source entity and each of the passed target entities
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity The row belonging to the source side of this association.
-
array
$targetEntities The rows belonging to the target side of this association.
Returns
array<Cake\Datasource\EntityInterface>
Throws
InvalidArgumentException
if any of the entities is lacking a primary key value
_diffLinks() ¶ protected
_diffLinks(Cake\ORM\Query $existing, array<Cake\Datasource\EntityInterface> $jointEntities, array $targetEntities, array<string, mixed> $options = []): array|false
Helper method used to delete the difference between the links passed in
$existing
and $jointEntities
. This method will return the values from
$targetEntities
that were not deleted from calculating the difference.
Parameters
-
Cake\ORM\Query
$existing a query for getting existing links
-
array<Cake\Datasource\EntityInterface>
$jointEntities link entities that should be persisted
-
array
$targetEntities entities in target table that are related to the
$jointEntities
-
array<string, mixed>
$options optional list of options accepted by
Table::delete()
Returns
array|false
_dispatchBeforeFind() ¶ protected
_dispatchBeforeFind(Cake\ORM\Query $query): void
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
Returns
void
_entityName() ¶ protected
_entityName(string $name): string
Creates the proper entity name (singular) for the specified name
Parameters
-
string
$name Name
Returns
string
_extractFinder() ¶ protected
_extractFinder(array|string $finderData): array
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
-
array|string
$finderData The finder name or an array having the name as key and options as value.
Returns
array
_fixtureName() ¶ protected
_fixtureName(string $name): string
Creates a fixture name
Parameters
-
string
$name Model class name
Returns
string
_formatAssociationResults() ¶ protected
_formatAssociationResults(Cake\ORM\Query $query, Cake\ORM\Query $surrogate, array<string, mixed> $options): void
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<string, mixed>
$options options passed to the method
attachTo
Returns
void
_generateJunctionAssociations() ¶ protected
_generateJunctionAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source, Cake\ORM\Table $target): void
Generate associations on the junction table as necessary
Generates the following associations:
- junction belongsTo source e.g. ArticlesTags belongsTo Tags
- junction belongsTo target e.g. ArticlesTags belongsTo Articles
You can override these generated associations by defining associations with the correct aliases.
Parameters
-
Cake\ORM\Table
$junction The junction table.
-
Cake\ORM\Table
$source The source table.
-
Cake\ORM\Table
$target The target table.
Returns
void
Throws
InvalidArgumentException
If the expected associations are incompatible with existing associations.
_generateSourceAssociations() ¶ protected
_generateSourceAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source): void
Generate additional source table associations as necessary.
Generates the following associations:
- source hasMany junction e.g. Tags hasMany ArticlesTags
You can override these generated associations by defining associations with the correct aliases.
Parameters
-
Cake\ORM\Table
$junction The junction table.
-
Cake\ORM\Table
$source The source table.
Returns
void
_generateTargetAssociations() ¶ protected
_generateTargetAssociations(Cake\ORM\Table $junction, Cake\ORM\Table $source, Cake\ORM\Table $target): void
Generate reciprocal associations as necessary.
Generates the following associations:
- target hasMany junction e.g. Articles hasMany ArticlesTags
- target belongsToMany source e.g Articles belongsToMany Tags.
You can override these generated associations by defining associations with the correct aliases.
Parameters
-
Cake\ORM\Table
$junction The junction table.
-
Cake\ORM\Table
$source The source table.
-
Cake\ORM\Table
$target The target table.
Returns
void
_joinCondition() ¶ protected
_joinCondition(array<string, mixed> $options): array
Return false as join conditions are defined in the junction table
Parameters
-
array<string, mixed>
$options list of options passed to attachTo method
Returns
array
_junctionAssociationName() ¶ protected
_junctionAssociationName(): string
Returns the name of the association from the target table to the junction table, this name is used to generate alias in the query and to later on retrieve the results.
Returns
string
_junctionTableName() ¶ protected
_junctionTableName(string|null $name = null): string
Sets the name of the junction table. If no arguments are passed the current configured name is returned. A default name based of the associated tables will be generated if none found.
Parameters
-
string|null
$name optional The name of the junction table.
Returns
string
_modelKey() ¶ protected
_modelKey(string $name): string
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
_modelNameFromKey() ¶ protected
_modelNameFromKey(string $key): string
Creates the proper model name from a foreign key
Parameters
-
string
$key Foreign key
Returns
string
_options() ¶ protected
_options(array<string, mixed> $options): void
Parse extra options passed in the constructor.
Parameters
-
array<string, mixed>
$options original list of options passed in constructor
Returns
void
_pluginNamespace() ¶ protected
_pluginNamespace(string $pluginName): string
Return plugin's namespace
Parameters
-
string
$pluginName Plugin name
Returns
string
_pluginPath() ¶ protected
_pluginPath(string $pluginName): string
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
_pluralHumanName() ¶ protected
_pluralHumanName(string $name): string
Creates the plural human name used in views
Parameters
-
string
$name Controller name
Returns
string
_propertyName() ¶ protected
_propertyName(): string
Returns default property name based on association name.
Returns
string
_saveLinks() ¶ protected
_saveLinks(Cake\Datasource\EntityInterface $sourceEntity, array<Cake\Datasource\EntityInterface> $targetEntities, array<string, mixed> $options): bool
Creates links between the source entity and each of the passed target entities
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity the entity from source table in this association
-
array<Cake\Datasource\EntityInterface>
$targetEntities list of entities to link to link to the source entity using the junction table
-
array<string, mixed>
$options list of options accepted by
Table::save()
Returns
bool
_saveTarget() ¶ protected
_saveTarget(Cake\Datasource\EntityInterface $parentEntity, array $entities, array<string, mixed> $options): Cake\Datasource\EntityInterface|false
Persists each of the entities into the target table and creates links between the parent entity and each one of the saved target entities.
Parameters
-
Cake\Datasource\EntityInterface
$parentEntity the source entity containing the target entities to be saved.
-
array
$entities list of entities to persist in target table and to link to the parent entity
-
array<string, mixed>
$options list of options accepted by
Table::save()
Returns
Cake\Datasource\EntityInterface|false
Throws
InvalidArgumentException
if the property representing the association in the parent entity cannot be traversed
_singularHumanName() ¶ protected
_singularHumanName(string $name): string
Creates the singular human name used in views
Parameters
-
string
$name Controller name
Returns
string
_singularName() ¶ protected
_singularName(string $name): string
Creates the singular name for use in views.
Parameters
-
string
$name Name to use
Returns
string
_variableName() ¶ protected
_variableName(string $name): string
Creates the plural variable name for views
Parameters
-
string
$name Name to use
Returns
string
attachTo() ¶ public
attachTo(Cake\ORM\Query $query, array<string, mixed> $options = []): void
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
- 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)
Parameters
-
Cake\ORM\Query
$query the query to be altered to include the target table data
-
array<string, mixed>
$options optional Any extra options or overrides to be taken in account
Returns
void
canBeJoined() ¶ public
canBeJoined(array<string, mixed> $options = []): bool
Whether this association can be expressed directly in a query join
Parameters
-
array<string, mixed>
$options optional custom options key that could alter the return value
Returns
bool
cascadeDelete() ¶ public
cascadeDelete(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): bool
Clear out the data in the junction table for a given entity.
Each implementing class should handle the cascaded delete as required.
Parameters
-
Cake\Datasource\EntityInterface
$entity The entity that started the cascading delete.
-
array<string, mixed>
$options optional The options for the original delete.
Returns
bool
defaultRowValue() ¶ public
defaultRowValue(array<string, mixed> $row, bool $joined): array<string, mixed>
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<string, mixed>
$row -
bool
$joined
Returns
array<string, mixed>
deleteAll() ¶ public
deleteAll(Cake\Database\ExpressionInterface|Closure|array|string|null $conditions): int
Proxies the delete operation to the target table's deleteAll method
Parameters
-
Cake\Database\ExpressionInterface|Closure|array|string|null
$conditions Conditions to be used, accepts anything Query::where() can take.
Returns
int
See Also
eagerLoader() ¶ public
eagerLoader(array<string, mixed> $options): Closure
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 be 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<string, mixed>
$options
Returns
Closure
exists() ¶ public
exists(Cake\Database\ExpressionInterface|Closure|array|string|null $conditions): bool
Proxies the operation to the target table's exists method after appending the default conditions for this association
Parameters
-
Cake\Database\ExpressionInterface|Closure|array|string|null
$conditions The conditions to use for checking if any record matches.
Returns
bool
See Also
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
find() ¶ public
find(array<string, mixed>|string|null $type = null, array<string, mixed> $options = []): Cake\ORM\Query
Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration.
If your association includes conditions or a finder, the junction table will be included in the query's contained associations.
Parameters
-
array<string, mixed>|string|null
$type optional the type of query to perform, if an array is passed, it will be interpreted as the
$options
parameter-
array<string, mixed>
$options optional The options to for the find
Returns
Cake\ORM\Query
See Also
getBindingKey() ¶ public
getBindingKey(): array<string>|string
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.
Returns
array<string>|string
getCascadeCallbacks() ¶ public
getCascadeCallbacks(): bool
Gets whether cascaded deletes should also fire callbacks.
Returns
bool
getClassName() ¶ public
getClassName(): string
Gets the class name of the target table object.
Returns
string
getConditions() ¶ public
getConditions(): Closure|array
Gets a list of conditions to be always included when fetching records from the target association.
Returns
Closure|array
See Also
getDependent() ¶ public
getDependent(): bool
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.
Returns
bool
getFinder() ¶ public
getFinder(): array|string
Gets the default finder to use for fetching rows from the target table.
Returns
array|string
getForeignKey() ¶ public
getForeignKey(): array<string>|string
Gets the name of the field representing the foreign key to the source table.
Returns
array<string>|string
getJoinType() ¶ public
getJoinType(): string
Gets the type of join to be used when adding the association to a query.
Returns
string
getName() ¶ public
getName(): string
Gets the name for this association, usually the alias assigned to the target associated table
Returns
string
getProperty() ¶ public
getProperty(): string
Gets the property name that should be filled with data from the target table in the source table record.
Returns
string
getSaveStrategy() ¶ public
getSaveStrategy(): string
Gets the strategy that should be used for saving.
Returns
string
getSort() ¶ public
getSort(): mixed
Gets the sort order in which target records should be returned.
Returns
mixed
getSource() ¶ public
getSource(): Cake\ORM\Table
Gets the table instance for the source side of the association.
Returns
Cake\ORM\Table
getStrategy() ¶ public
getStrategy(): string
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
string
getTableLocator() ¶ public
getTableLocator(): Cake\ORM\Locator\LocatorInterface
Gets the table locator.
Returns
Cake\ORM\Locator\LocatorInterface
getTarget() ¶ public
getTarget(): Cake\ORM\Table
Gets the table instance for the target side of the association.
Returns
Cake\ORM\Table
getTargetForeignKey() ¶ public
getTargetForeignKey(): array<string>|string
Gets the name of the field representing the foreign key to the target table.
Returns
array<string>|string
getThrough() ¶ public
getThrough(): Cake\ORM\Table|string
Gets the current join table, either the name of the Table instance or the instance itself.
Returns
Cake\ORM\Table|string
isOwningSide() ¶ public
isOwningSide(Cake\ORM\Table $side): bool
Returns boolean true, as both of the tables 'own' rows in the other side of the association via the joint table.
Parameters
-
Cake\ORM\Table
$side The potential Table with ownership
Returns
bool
junction() ¶ public
junction(Cake\ORM\Table|string|null $table = null): Cake\ORM\Table
Sets the table instance for the junction relation. If no arguments are passed, the current configured table instance is returned
Parameters
-
Cake\ORM\Table|string|null
$table optional Name or instance for the join table
Returns
Cake\ORM\Table
Throws
InvalidArgumentException
If the expected associations are incompatible with existing associations.
junctionConditions() ¶ protected
junctionConditions(): array
Returns filtered conditions that specifically reference the junction table.
Returns
array
link() ¶ public
link(Cake\Datasource\EntityInterface $sourceEntity, array<Cake\Datasource\EntityInterface> $targetEntities, array<string, mixed> $options = []): bool
Associates the source entity to each of the target entities provided by creating links in the junction table. Both the source entity and each of the target entities are assumed to be already persisted, if they are marked as new or their status is unknown then an exception will be thrown.
When using this method, all entities in $targetEntities
will be appended to
the source entity's property corresponding to this association object.
This method does not check link uniqueness.
Example:
$newTags = $tags->find('relevant')->toArray();
$articles->getAssociation('tags')->link($article, $newTags);
$article->get('tags')
will contain all tags in $newTags
after liking
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity the row belonging to the
source
side of this association-
array<Cake\Datasource\EntityInterface>
$targetEntities list of entities belonging to the
target
side of this association-
array<string, mixed>
$options optional list of options to be passed to the internal
save
call
Returns
bool
Throws
InvalidArgumentException
when any of the values in $targetEntities is detected to not be already persisted
replaceLinks() ¶ public
replaceLinks(Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array<string, mixed> $options = []): bool
Replaces existing association links between the source entity and the target
with the ones passed. This method does a smart cleanup, links that are already
persisted and present in $targetEntities
will not be deleted, new links will
be created for the passed target entities that are not already in the database
and the rest will be removed.
For example, if an article is linked to tags 'cake' and 'framework' and you pass to this method an array containing the entities for tags 'cake', 'php' and 'awesome', only the link for cake will be kept in database, the link for 'framework' will be deleted and the links for 'php' and 'awesome' will be created.
Existing links are not deleted and created again, they are either left untouched or updated so that potential extra information stored in the joint row is not lost. Updating the link row can be done by making sure the corresponding passed target entity contains the joint property with its primary key and any extra information to be stored.
On success, the passed $sourceEntity
will contain $targetEntities
as value
in the corresponding property for this association.
This method assumes that links between both the source entity and each of the target entities are unique. That is, for any given row in the source table there can only be one link in the junction table pointing to any other given row in the target table.
Additional options for new links to be saved can be passed in the third argument,
check Table::save()
for information on the accepted options.
Example:
$article->tags = [$tag1, $tag2, $tag3, $tag4];
$articles->save($article);
$tags = [$tag1, $tag3];
$articles->getAssociation('tags')->replaceLinks($article, $tags);
$article->get('tags')
will contain only [$tag1, $tag3]
at the end
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity an entity persisted in the source table for this association
-
array
$targetEntities list of entities from the target table to be linked
-
array<string, mixed>
$options optional list of options to be passed to the internal
save
/delete
calls when persisting/updating new links, or deleting existing ones
Returns
bool
Throws
InvalidArgumentException
if non persisted entities are passed or if any of them is lacking a primary key value
requiresKeys() ¶ public
requiresKeys(array<string, mixed> $options = []): bool
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<string, mixed>
$options optional The options containing the strategy to be used.
Returns
bool
saveAssociated() ¶ public
saveAssociated(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): Cake\Datasource\EntityInterface|false
Takes an entity from the source table and looks if there is a field
matching the property name for this association. The found entity will be
saved on the target table for this association by passing supplied
$options
When using the 'append' strategy, this function will only create new links between each side of this association. It will not destroy existing ones even though they may not be present in the array of entities to be saved.
When using the 'replace' strategy, existing links will be removed and new links will be created in the joint table. If there exists links in the database to some of the entities intended to be saved by this method, they will be updated, not deleted.
Parameters
-
Cake\Datasource\EntityInterface
$entity an entity from the source table
-
array<string, mixed>
$options optional options to be passed to the save method in the target table
Returns
Cake\Datasource\EntityInterface|false
Throws
InvalidArgumentException
if the property representing the association in the parent entity cannot be traversed
See Also
\Cake\ORM\Association\BelongsToMany::replaceLinks()
setBindingKey() ¶ public
setBindingKey(array<string>|string $key): $this
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
-
array<string>|string
$key the table field or fields to be used to link both tables together
Returns
$this
setCascadeCallbacks() ¶ public
setCascadeCallbacks(bool $cascadeCallbacks): $this
Sets whether cascaded deletes should also fire callbacks.
Parameters
-
bool
$cascadeCallbacks cascade callbacks switch value
Returns
$this
setClassName() ¶ public
setClassName(string $className): $this
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(Closure|array $conditions): $this
Sets a list of conditions to be always included when fetching records from the target association.
Parameters
-
Closure|array
$conditions
Returns
$this
setDependent() ¶ public
setDependent(bool $dependent): $this
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(array|string $finder): $this
Sets the default finder to use for fetching rows from the target table.
Parameters
-
array|string
$finder the finder name to use or array of finder name and option.
Returns
$this
setForeignKey() ¶ public
setForeignKey(array<string>|string $key): $this
Sets the name of the field representing the foreign key to the target table.
Parameters
-
array<string>|string
$key the key or keys to be used to link both tables together
Returns
$this
setJoinType() ¶ public
setJoinType(string $type): $this
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): $this
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): $this
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
setSaveStrategy() ¶ public
setSaveStrategy(string $strategy): $this
Sets the strategy that should be used for saving.
Parameters
-
string
$strategy the strategy name to be used
Returns
$this
Throws
InvalidArgumentException
if an invalid strategy name is passed
setSort() ¶ public
setSort(mixed $sort): $this
Sets the sort order in which target records should be returned.
Parameters
-
mixed
$sort A find() compatible order clause
Returns
$this
setSource() ¶ public
setSource(Cake\ORM\Table $table): $this
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): $this
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): $this
Sets the table locator.
Parameters
-
Cake\ORM\Locator\LocatorInterface
$tableLocator LocatorInterface instance.
Returns
$this
setTarget() ¶ public
setTarget(Cake\ORM\Table $table): $this
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
setTargetForeignKey() ¶ public
setTargetForeignKey(array<string>|string $key): $this
Sets the name of the field representing the foreign key to the target table.
Parameters
-
array<string>|string
$key the key to be used to link both tables together
Returns
$this
setThrough() ¶ public
setThrough(Cake\ORM\Table|string $through): $this
Sets the current join table, either the name of the Table instance or the instance itself.
Parameters
-
Cake\ORM\Table|string
$through Name of the Table instance or the instance itself
Returns
$this
targetConditions() ¶ protected
targetConditions(): array|Closure|null
Returns filtered conditions that reference the target table.
Any string expressions, or expression objects will also be returned in this list.
Returns
array|Closure|null
transformRow() ¶ public
transformRow(array $row, string $nestKey, bool $joined, string|null $targetProperty = null): array
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 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
unlink() ¶ public
unlink(Cake\Datasource\EntityInterface $sourceEntity, array<Cake\Datasource\EntityInterface> $targetEntities, array<string>|bool $options = []): bool
Removes all links between the passed source entity and each of the provided target entities. This method assumes that all passed objects are already persisted in the database and that each of them contain a primary key value.
Options
Additionally to the default options accepted by Table::delete()
, the following
keys are supported:
- cleanProperty: Whether to remove all the objects in
$targetEntities
that are stored in$sourceEntity
(default: true)
By default this method will unset each of the entity objects stored inside the source entity.
Example:
$article->tags = [$tag1, $tag2, $tag3, $tag4];
$tags = [$tag1, $tag2, $tag3];
$articles->getAssociation('tags')->unlink($article, $tags);
$article->get('tags')
will contain only [$tag4]
after deleting in the database
Parameters
-
Cake\Datasource\EntityInterface
$sourceEntity An entity persisted in the source table for this association.
-
array<Cake\Datasource\EntityInterface>
$targetEntities List of entities persisted in the target table for this association.
-
array<string>|bool
$options optional List of options to be passed to the internal
delete
call, or aboolean
ascleanProperty
key shortcut.
Returns
bool
Throws
InvalidArgumentException
If non persisted entities are passed or if any of them is lacking a primary key value.
updateAll() ¶ public
updateAll(array $fields, Cake\Database\ExpressionInterface|Closure|array|string|null $conditions): int
Proxies the update operation to the target table's updateAll method
Parameters
-
array
$fields A hash of field => new value.
-
Cake\Database\ExpressionInterface|Closure|array|string|null
$conditions Conditions to be used, accepts anything Query::where() can take.
Returns
int
See Also
Property Detail
$_bindingKey ¶ protected
The field name in the owning side table that is used to match with the foreignKey
Type
array<string>|string|null
$_conditions ¶ protected
A list of conditions to be always included when fetching records from the target association
Type
Closure|array
$_dependent ¶ protected
Whether the records on the joint table should be removed when a record on the source table is deleted.
Defaults to true for backwards compatibility.
Type
bool
$_finder ¶ protected
The default finder name to use for fetching rows from the target table With array value, finder name and default options are allowed.
Type
array|string
$_foreignKey ¶ protected
The name of the field representing the foreign key to the table to load
Type
array<string>|string
$_joinType ¶ protected
The type of join to be used when adding the association to a query
Type
string
$_junctionAssociationName ¶ protected
The name of the hasMany association from the target table to the junction table
Type
string
$_junctionConditions ¶ protected
Filtered conditions that reference the junction table.
Type
array|null
$_junctionProperty ¶ protected
The name of the property to be set containing data from the junction table once a record from the target table is hydrated
Type
string
$_name ¶ protected
Name given to the association, it usually represents the alias assigned to the target associated table
Type
string
$_propertyName ¶ protected
The property name that should be filled with data from the target table in the source table record.
Type
string
$_targetForeignKey ¶ protected
The name of the field representing the foreign key to the target table
Type
array<string>|string|null