STRATEGY_JOIN
STRATEGY_JOIN = 'join' : string
Strategy name to use joins for fetching associated records
Represents an N - 1 relationship where the target side of the relationship will have one or multiple records per each one in the source side.
An example of a HasMany association would be Author has many Articles.
$_sourceTable : \Cake\ORM\Table
Source table instance
$_targetTable : \Cake\ORM\Table
Target table instance
$_tableLocator : \Cake\ORM\Locator\LocatorInterface
Table locator instance
__construct(string $alias, array $options = array())
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 | A list of properties to be set on this object |
cascadeCallbacks(boolean|null $cascadeCallbacks = null) : boolean
Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned
| boolean|null | $cascadeCallbacks | cascade callbacks switch value |
setClassName(string $className) : $this
Sets the class name of the target table object.
| string | $className | Class name to set. |
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.
setSource(\Cake\ORM\Table $table) : $this
Sets the table instance for the source side of the association.
| \Cake\ORM\Table | $table | the instance to be assigned as source side |
getSource() : \Cake\ORM\Table
Gets the table instance for the source side of the association.
source(\Cake\ORM\Table|null $table = null) : \Cake\ORM\Table
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|null | $table | the instance to be assigned as source side |
setTarget(\Cake\ORM\Table $table) : $this
Sets the table instance for the target side of the association.
| \Cake\ORM\Table | $table | the instance to be assigned as target side |
getTarget() : \Cake\ORM\Table
Gets the table instance for the target side of the association.
target(\Cake\ORM\Table|null $table = null) : \Cake\ORM\Table
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|null | $table | the instance to be assigned as target side |
conditions(array|null $conditions = null) : array|callable
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
| array|null | $conditions | list of conditions to be used |
setBindingKey(string|array $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.
| string|array | $key | the table field or fields to be used to link both tables together |
bindingKey(string|null $key = null) : string|array
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
| string|null | $key | the table field to be used to link both tables together |
setDependent(boolean $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.
| boolean | $dependent | Set the dependent mode. Use null to read the current state. |
dependent(boolean|null $dependent = null) : boolean
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.
| boolean|null | $dependent | Set the dependent mode. Use null to read the current state. |
canBeJoined(array $options = array()) : boolean
Whether this association can be expressed directly in a query join
| array | $options | custom options key that could alter the return value |
if the 'matching' key in $option is true then this function will return true, false otherwise
property(string|null $name = null) : string
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.
| string|null | $name | The name of the association property. Use null to read the current value. |
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.
| string | $name | The strategy type. Use null to read the current value. |
When an invalid strategy is provided.
strategy(string|null $name = null) : string
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.
| string|null | $name | The strategy type. Use null to read the current value. |
When an invalid strategy is provided.
attachTo(\Cake\ORM\Query $query, array $options = array()) : void
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 | Any extra options or overrides to be taken in account |
if the query builder passed does not return a query object
transformRow(array $row, string $nestKey, boolean $joined, string|null $targetProperty = null) : array
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 |
| boolean | $joined | Whether or not the row is a result of a direct join with this association |
| string|null | $targetProperty | The property name in the source results where the association data shuld be nested in. Will use the default one if not provided. |
defaultRowValue(array $row, boolean $joined) : array
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. |
| boolean | $joined | Whether or not the row is a result of a direct join with this association |
find(string|array|null $type = null, array $options = array()) : \Cake\ORM\Query
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 | the type of query to perform, if an array is passed,
it will be interpreted as the |
| array | $options | The options to for the find |
exists(array|callable|\Cake\Database\ExpressionInterface $conditions) : boolean
Proxies the operation to the target table's exists method after appending the default conditions for this association
| array|callable|\Cake\Database\ExpressionInterface | $conditions | The conditions to use for checking if any record matches. |
updateAll(array $fields, mixed $conditions) : integer
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. |
Count Returns the affected rows.
requiresKeys(array $options = array()) : boolean
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 | The options containing the strategy to be used. |
true if a list of keys will be required
__get(string $property) : \Cake\ORM\Association
Proxies property retrieval to the target table. This is handy for getting this association's associations
| string | $property | the property name |
if no association with such name exists
eagerLoader(array $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 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. |
cascadeDelete(\Cake\Datasource\EntityInterface $entity, array $options = array()) : boolean
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 | The options for the original delete. |
Success
isOwningSide(\Cake\ORM\Table $side) : boolean
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 |
saveAssociated(\Cake\Datasource\EntityInterface $entity, array $options = array()) : boolean|\Cake\Datasource\EntityInterface
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`
| \Cake\Datasource\EntityInterface | $entity | an entity from the source table |
| array | $options | options to be passed to the save method in the target table |
when the association data cannot be traversed.
false if $entity could not be saved, otherwise it returns the saved entity
tableLocator(\Cake\ORM\Locator\LocatorInterface|null $tableLocator = null) : \Cake\ORM\Locator\LocatorInterface
Sets the table locator.
If no parameters are passed, it will return the currently used locator.
| \Cake\ORM\Locator\LocatorInterface|null | $tableLocator | LocatorInterface instance. |
setTableLocator(\Cake\ORM\Locator\LocatorInterface $tableLocator) : $this
Sets the table locator.
| \Cake\ORM\Locator\LocatorInterface | $tableLocator | LocatorInterface instance. |
getTableLocator() : \Cake\ORM\Locator\LocatorInterface
Gets the table locator.
saveStrategy(string|null $strategy = null) : string
Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy
| string|null | $strategy | the strategy name to be used |
if an invalid strategy name is passed
the strategy to be used for saving
link(\Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = array()) : boolean
Associates the source entity to each of the target entities provided.
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. Changes are persisted in the database and also in the source entity.
$user = $users->get(1);
$allArticles = $articles->find('all')->toArray();
$users->Articles->link($user, $allArticles);$user->get('articles') will contain all articles in $allArticles after linking
| \Cake\Datasource\EntityInterface | $sourceEntity | the row belonging to the |
| array | $targetEntities | list of entities belonging to the |
| array | $options | list of options to be passed to the internal |
true on success, false otherwise
unlink(\Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = array()) : void
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.
Additionally to the default options accepted by Table::delete(), the following
keys are supported:
$targetEntities that
are stored in $sourceEntity (default: true)By default this method will unset each of the entity objects stored inside the source entity.
Changes are persisted in the database and also in the source entity.
$user = $users->get(1);
$user->articles = [$article1, $article2, $article3, $article4];
$users->save($user, ['Associated' => ['Articles']]);
$allArticles = [$article1, $article2, $article3];
$users->Articles->unlink($user, $allArticles);$article->get('articles') will contain only [$article4] after deleting in the database
| \Cake\Datasource\EntityInterface | $sourceEntity | an entity persisted in the source table for this association |
| array | $targetEntities | list of entities persisted in the target table for this association |
| array | $options | list of options to be passed to the internal |
if non persisted entities are passed or if any of them is lacking a primary key value
replace(\Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = array()) : boolean
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 author has many articles, such as 'article1','article 2' and 'article 3' and you pass to this method an array containing the entities for articles 'article 1' and 'article 4', only the link for 'article 1' will be kept in database, the links for 'article 2' and 'article 3' will be deleted and the link for 'article 4' will be created.
Existing links are not deleted and created again, they are either left untouched or updated.
This method does not check link uniqueness.
On success, the passed $sourceEntity will contain $targetEntities as value
in the corresponding property for this association.
Additional options for new links to be saved can be passed in the third argument,
check Table::save() for information on the accepted options.
$author->articles = [$article1, $article2, $article3, $article4];
$authors->save($author);
$articles = [$article1, $article3];
$authors->getAssociation('articles')->replace($author, $articles);$author->get('articles') will contain only [$article1, $article3] at the end
| \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 | $options | list of options to be passed to the internal |
if non persisted entities are passed or if any of them is lacking a primary key value
success
_appendNotMatching(\Cake\Datasource\QueryInterface $query, array $options) : void
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 | The query to modify |
| array | $options | Options array containing the |
_dispatchBeforeFind(\Cake\ORM\Query $query) : void
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 |
_appendFields(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $options) : void
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 |
_formatAssociationResults(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $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.
| \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 |
_bindNewAssociations(\Cake\ORM\Query $query, \Cake\ORM\Query $surrogate, array $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.
| \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 |
_joinCondition(array $options) : array
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 |
if the number of columns in the foreignKey do not match the number of columns in the source table primaryKey
_extractFinder(string|array $finderData) : array
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. |
_saveTarget(array $foreignKeyReference, \Cake\Datasource\EntityInterface $parentEntity, array|\Traversable $entities, array $options) : boolean
Persists each of the entities into the target table and creates links between the parent entity and each one of the saved target entities.
| array | $foreignKeyReference | The foreign key reference defining the link between the target entity, and the parent entity. |
| \Cake\Datasource\EntityInterface | $parentEntity | The source entity containing the target entities to be saved. |
| array|\Traversable | $entities | list of entities to persist in target table and to link to the parent entity |
| array | $options | list of options accepted by |
true on success, false otherwise.
_unlinkAssociated(array $foreignKeyReference, \Cake\Datasource\EntityInterface $entity, \Cake\ORM\Table $target, array $remainingEntities = array(), array $options = array()) : boolean
Deletes/sets null the related objects according to the dependency between source and targets and foreign key nullability Skips deleting records present in $remainingEntities
| array | $foreignKeyReference | The foreign key reference defining the link between the target entity, and the parent entity. |
| \Cake\Datasource\EntityInterface | $entity | the entity which should have its associated entities unassigned |
| \Cake\ORM\Table | $target | The associated table |
| array | $remainingEntities | Entities that should not be deleted |
| array | $options | list of options accepted by |
success
_unlink(array $foreignKey, \Cake\ORM\Table $target, array $conditions = array(), array $options = array()) : boolean
Deletes/sets null the related objects matching $conditions.
The action which is taken depends on the dependency between source and targets and also on foreign key nullability
| array | $foreignKey | array of foreign key properties |
| \Cake\ORM\Table | $target | The associated table |
| array | $conditions | The conditions that specifies what are the objects to be unlinked |
| array | $options | list of options accepted by |
success
_foreignKeyAcceptsNull(\Cake\ORM\Table $table, array $properties) : boolean
Checks the nullable flag of the foreign key
| \Cake\ORM\Table | $table | the table containing the foreign key |
| array | $properties | the list of fields that compose the foreign key |