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.
string
'append'
string
'replace'
MANY_TO_MANY
, MANY_TO_ONE
, ONE_TO_MANY
, ONE_TO_ONE
, STRATEGY_JOIN
, STRATEGY_SELECT
, STRATEGY_SUBQUERY
$_joinType
protected string
$_saveStrategy
protected string
$_sort
protected mixed
$_strategy
protected string
$_validStrategies
protected array
_bindingKey
, _cascadeCallbacks
, _className
, _conditions
, _dependent
, _finder
, _foreignKey
, _name
, _propertyName
, _sourceTable
, _targetTable
_tableLocator
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
Deletes/sets null the related objects according to the dependency between source and targets and foreign key nullability Skips deleting records present in $remainingEntities
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.
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.
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.
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.
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
Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy
Sets the sort order in which target records should be returned. If no arguments are passed the currently configured value is returned
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.
_foreignKeyAcceptsNull( Cake\ORM\Table $table , array $properties )
Checks the nullable flag of the foreign key
Cake\ORM\Table
$table
$properties
_options( array $opts )
Parse extra options passed in the constructor.
$opts
Cake\ORM\Association::_options()
_unlink( array $foreignKey , Cake\ORM\Table $target , array $conditions [] , array $options [] )
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
$foreignKey
Cake\ORM\Table
$target
$conditions
optional [] $options
optional [] Table::delete()
_unlinkAssociated( array $properties , Cake\Datasource\EntityInterface $entity , Cake\ORM\Table $target , array $remainingEntities [] , array $options [] )
Deletes/sets null the related objects according to the dependency between source and targets and foreign key nullability Skips deleting records present in $remainingEntities
$properties
Cake\Datasource\EntityInterface
$entity
Cake\ORM\Table
$target
$remainingEntities
optional [] $options
optional [] Table::delete()
canBeJoined( array $options [] )
Whether this association can be expressed directly in a query join
$options
optional [] if the 'matching' key in $option is true then this function will return true, false otherwise
Cake\ORM\Association::canBeJoined()
defaultRowValue( array $row , boolean $joined )
Returns a modified row after appending a property for this association with the default empty value according to whether the association was joined or fetched externally.
$row
$joined
Whether or not the row is a result of a direct join with this association
Cake\ORM\Association::defaultRowValue()
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.
$options
getForeignKey( )
Gets the name of the field representing the foreign key to the source table.
Cake\ORM\Association::getForeignKey()
getSaveStrategy( )
Gets the strategy that should be used for saving.
getSort( )
Gets the sort order in which target records should be returned.
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
link( Cake\Datasource\EntityInterface $sourceEntity , array $targetEntities , array $options [] )
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 source
side of this association
$targetEntities
list of entities belonging to the target
side of this association
$options
optional [] save
callreplace( Cake\Datasource\EntityInterface $sourceEntity , array $targetEntities , array $options [] )
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->association('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
$targetEntities
$options
optional [] list of options to be passed to the internal save
/delete
calls when persisting/updating new links, or deleting existing ones
if non persisted entities are passed or if any of them is lacking a primary key value
saveAssociated( Cake\Datasource\EntityInterface $entity , array $options [] )
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
$options
optional [] options to be passed to the save method in the target table
Cake\Datasource\EntityInterface
false if $entity could not be saved, otherwise it returns the saved entity
saveStrategy( string|null $strategy null )
Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy
$strategy
optional null setSaveStrategy( string $strategy )
Sets the strategy that should be used for saving.
$strategy
setSort( mixed $sort )
Sets the sort order in which target records should be returned.
$sort
sort( mixed $sort null )
Sets the sort order in which target records should be returned. If no arguments are passed the currently configured value is returned
$sort
optional null unlink( Cake\Datasource\EntityInterface $sourceEntity , array $targetEntities , array $options [] )
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
$targetEntities
list of entities persisted in the target table for this association
$options
optional [] delete
callif non persisted entities are passed or if any of them is lacking a primary key value
__call( string $method , array $argument )
Proxies method calls to the target table.
$method
$argument
__construct( string $alias , array $options [] )
Constructor. Subclasses can override _options function to get the original list of passed options if expecting any other special key
$alias
$options
optional [] __get( string $property )
Proxies property retrieval to the target table. This is handy for getting this association's associations
$property
Cake\ORM\Association
__isset( string $property )
Proxies the isset call to the target table. This is handy to check if the target table has another association with the passed name
$property
_appendFields( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Helper function used to conditionally append fields to the select clause of a query from the fields found in another query object.
Cake\ORM\Query
$query
Cake\ORM\Query
$surrogate
$options
attachTo
_appendNotMatching( Cake\Datasource\QueryInterface $query , array $options )
Conditionally adds a condition to the passed Query that will make it find records where there is no match with this association.
Cake\Datasource\QueryInterface
$query
$options
negateMatch
key._bindNewAssociations( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Applies all attachable associations to $query
out of the containments found in the $surrogate
query.
Copies all contained associations from the $surrogate
query into the passed $query
. Containments are altered so that they respect the associations chain from which they originated.
Cake\ORM\Query
$query
Cake\ORM\Query
$surrogate
$options
attachTo
_dispatchBeforeFind( Cake\ORM\Query $query )
Triggers beforeFind on the target table for the query this association is attaching to
Cake\ORM\Query
$query
_extractFinder( string|array $finderData )
Helper method to infer the requested finder and its options.
Returns the inferred options from the finder $type.
The following will call the finder 'translations' with the value of the finder as its options: $query->contain(['Comments' => ['finder' => ['translations']]]); $query->contain(['Comments' => ['finder' => ['translations' => []]]]); $query->contain(['Comments' => ['finder' => ['translations' => ['locales' => ['en_US']]]]]);
$finderData
The finder name or an array having the name as key and options as value.
_formatAssociationResults( Cake\ORM\Query $query , Cake\ORM\Query $surrogate , array $options )
Adds a formatter function to the passed $query
if the $surrogate
query declares any other formatter. Since the $surrogate
query correspond to the associated target table, the resulting formatter will be the result of applying the surrogate formatters to only the property corresponding to such table.
Cake\ORM\Query
$query
Cake\ORM\Query
$surrogate
the query having formatters for the associated target table.
$options
attachTo
_getClassName( string $alias , array $options [] )
Gets the table class name.
$alias
$options
optional [] _joinCondition( array $options )
Returns a single or multiple conditions to be appended to the generated join clause for getting the results on the target table.
$options
if the number of columns in the foreignKey do not match the number of columns in the source table primaryKey
_propertyName( )
Returns default property name based on association name.
attachTo( Cake\ORM\Query $query , array $options [] )
Alters a Query object to include the associated target table data in the final result
The options array accept the following keys:
Cake\ORM\Query
$query
$options
optional [] if the query builder passed does not return a query object
bindingKey( string|null $key null )
Sets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
If no parameters are passed the current field is returned
$key
optional null cascadeCallbacks( boolean|null $cascadeCallbacks null )
Sets whether or not cascaded deletes should also fire callbacks. If no arguments are passed, the current configured value is returned
$cascadeCallbacks
optional null cascadeDelete( Cake\Datasource\EntityInterface $entity , array $options [] )
Handles cascading a delete from an associated model.
Each implementing class should handle the cascaded delete as required.
Cake\Datasource\EntityInterface
$entity
$options
optional [] conditions( array|null $conditions null )
Sets a list of conditions to be always included when fetching records from the target association. If no parameters are passed the current list is returned
$conditions
optional null deleteAll( mixed $conditions )
Proxies the delete operation to the target table's deleteAll method
$conditions
Conditions to be used, accepts anything Query::where() can take.
dependent( boolean|null $dependent null )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
If no parameters are passed the current setting is returned.
$dependent
optional null exists( array|callable|Cake\Database\ExpressionInterface $conditions )
Proxies the operation to the target table's exists method after appending the default conditions for this association
Cake\Database\ExpressionInterface
$conditions
The conditions to use for checking if any record matches.
find( string|array|null $type null , array $options [] )
Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration
$type
optional null the type of query to perform, if an array is passed, it will be interpreted as the $options
parameter
$options
optional [] Cake\ORM\Query
finder( string|null $finder null )
Sets the default finder to use for fetching rows from the target table. If no parameters are passed, it will return the currently configured finder name.
$finder
optional null foreignKey( string|null $key null )
Sets the name of the field representing the foreign key to the target table. If no parameters are passed the current field is returned
$key
optional null getBindingKey( )
Gets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
getCascadeCallbacks( )
Gets whether or not cascaded deletes should also fire callbacks.
getConditions( )
Gets a list of conditions to be always included when fetching records from the target association.
getDependent( )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
getFinder( )
Gets the default finder to use for fetching rows from the target table.
getJoinType( )
Gets the type of join to be used when adding the association to a query.
getProperty( )
Gets the property name that should be filled with data from the target table in the source table record.
getSource( )
Gets the table instance for the source side of the association.
Cake\ORM\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.
getTarget( )
Gets the table instance for the target side of the association.
Cake\ORM\Table
joinType( string|null $type null )
Sets the type of join to be used when adding the association to a query. If no arguments are passed, the currently configured type is returned.
$type
optional null name( string|null $name null )
Sets the name for this association.
$name
optional null property( string|null $name null )
Sets the property name that should be filled with data from the target table in the source table record. If no arguments are passed, the currently configured type is returned.
$name
optional null requiresKeys( array $options [] )
Returns true if the eager loading process will require a set of the owning table's binding keys in order to use them as a filter in the finder query.
$options
optional [] setBindingKey( string $key )
Sets the name of the field representing the binding field with the target table. When not manually specified the primary key of the owning side table is used.
$key
setCascadeCallbacks( boolean $cascadeCallbacks )
Sets whether or not cascaded deletes should also fire callbacks.
$cascadeCallbacks
setConditions( array $conditions )
Sets a list of conditions to be always included when fetching records from the target association.
$conditions
setDependent( boolean $dependent )
Sets whether the records on the target table are dependent on the source table.
This is primarily used to indicate that records should be removed if the owning record in the source table is deleted.
If no parameters are passed the current setting is returned.
$dependent
setFinder( string $finder )
Sets the default finder to use for fetching rows from the target table.
$finder
setForeignKey( string $key )
Sets the name of the field representing the foreign key to the target table.
$key
setJoinType( string $type )
Sets the type of join to be used when adding the association to a query.
$type
setName( string $name )
Sets the name for this association.
$name
setProperty( string $name )
Sets the property name that should be filled with data from the target table in the source table record.
$name
setSource( Cake\ORM\Table $table )
Sets the table instance for the source side of the association.
Cake\ORM\Table
$table
setStrategy( string $name )
Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void.
$name
setTarget( Cake\ORM\Table $table )
Sets the table instance for the target side of the association.
Cake\ORM\Table
$table
source( Cake\ORM\Table $table null )
Sets the table instance for the source side of the association. If no arguments are passed, the current configured table instance is returned
Cake\ORM\Table
$table
optional null Cake\ORM\Table
strategy( string|null $name null )
Sets the strategy name to be used to fetch associated records. Keep in mind that some association types might not implement but a default strategy, rendering any changes to this setting void. If no arguments are passed, the currently configured strategy is returned.
$name
optional null target( Cake\ORM\Table $table null )
Sets the table instance for the target side of the association. If no arguments are passed, the current configured table instance is returned
Cake\ORM\Table
$table
optional null Cake\ORM\Table
transformRow( array $row , string $nestKey , boolean $joined , string|null $targetProperty null )
Correctly nests a result row associated values into the correct array keys inside the source results.
$row
$nestKey
The array key under which the results for this association should be found
$joined
Whether or not the row is a result of a direct join with this association
$targetProperty
optional null The property name in the source results where the association data shuld be nested in. Will use the default one if not provided.
updateAll( array $fields , mixed $conditions )
Proxies the update operation to the target table's updateAll method
$fields
$conditions
Conditions to be used, accepts anything Query::where() can take.
cascadeDelete( Cake\Datasource\EntityInterface $entity , array $options [] )
Cascade a delete to remove dependent records.
This method does nothing if the association is not dependent.
Cake\Datasource\EntityInterface
$entity
$options
optional [] _camelize( string $name )
Creates a camelized version of $name
$name
_entityName( string $name )
Creates the proper entity name (singular) for the specified name
$name
_fixtureName( string $name )
Creates a fixture name
$name
_modelKey( string $name )
Creates the proper underscored model key for associations
If the input contains a dot, assume that the right side is the real table name.
$name
_modelNameFromKey( string $key )
Creates the proper model name from a foreign key
$key
_pluginNamespace( string $pluginName )
Return plugin's namespace
$pluginName
_pluginPath( string $pluginName )
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
$pluginName
_pluralHumanName( string $name )
Creates the plural human name used in views
$name
_singularHumanName( string $name )
Creates the singular human name used in views
$name
_singularName( string $name )
Creates the singular name for use in views.
$name
_variableName( string $name )
Creates the plural variable name for views
$name
tableLocator( Cake\ORM\Locator\LocatorInterface $tableLocator null )
Sets the table locator. If no parameters are passed, it will return the currently used locator.
Cake\ORM\Locator\LocatorInterface
$tableLocator
optional null Cake\ORM\Locator\LocatorInterface
protected string
The type of join to be used when adding the association to a query
'INNER'
protected string
Saving strategy to be used by this association
self::SAVE_APPEND
protected string
The strategy name to be used to fetch associated records.
self::STRATEGY_SELECT
protected array
Valid strategies for this type of association
[ self::STRATEGY_SELECT, self::STRATEGY_SUBQUERY ]
© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.4/class-Cake.ORM.Association.HasMany.html