PHP Class Cake\ORM\Association\BelongsToMany

An example of a BelongsToMany association would be Article belongs to many Tags.

Inheritance: extends Cake\ORM\Association, use trait Cake\ORM\Association\ExternalAssociationTrait

Mostra file Open project: cakephp/orm Class Usage Examples

Protected Properties

Property	Type	Description
$_dependent	boolean	Defaults to true for backwards compatibility.
$_joinType	string	The type of join to be used when adding the association to a query
$_junctionAssociationName	string	The name of the hasMany association from the target table to the junction table
$_junctionConditions	null \| array	Filtered conditions that reference the junction table.
$_junctionProperty	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	Cake\ORM\Table	Junction table instance
$_junctionTableName	string	Junction table name
$_saveStrategy	string	Saving strategy to be used by this association
$_strategy	string	The strategy name to be used to fetch associated records.
$_targetConditions	null \| array	Filtered conditions that reference the target table.
$_targetForeignKey	string \| array	The name of the field representing the foreign key to the target table
$_through	string \| Cake\ORM\Table	The table instance for the junction relation.
$_validStrategies	array	Valid strategies for this type of association

Public Methods

Method	Description
_buildBaseQuery ( )
_externalOptions ( )
attachTo ( Query $query, array $options = [] ) : void	Alters a Query object to include the associated target table data in the final result
cascadeDelete ( Cake\Datasource\EntityInterface $entity, array $options = [] ) : boolean	Clear out the data in the junction table for a given entity.
conditions ( $conditions = null )	{@inheritDoc}
find ( string \| array \| null $type = null, array $options = [] ) : Query	Proxies the finding operation to the target table's find method and modifies the query accordingly based of this association configuration.
isOwningSide ( Table $side ) : boolean	Returns boolean true, as both of the tables 'own' rows in the other side of the association via the joint table.
junction ( string \| Table \| null $table = null ) : Table	Sets the table instance for the junction relation. If no arguments are passed, the current configured table instance is returned
link ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = [] ) : boolean	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 ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = [] ) : 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.
saveAssociated ( Cake\Datasource\EntityInterface $entity, array $options = [] ) : 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
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
targetForeignKey ( string \| null $key = null ) : string	Sets the name of the field representing the foreign key to the target table.
type ( ) : string	Get the relationship type.
unlink ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array \| boolean $options = [] ) : boolean	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.

Protected Methods

Method	Description
_appendJunctionJoin ( Query $query, string \| array $conditions ) : Query	Append a join to the junction table.
_appendNotMatching ( $query, $options )	{@inheritDoc}
_buildQuery ( array $options ) : Query	Auxiliary function to construct a new Query object to return all the records in the target table that are associated to those specified in $options from the source table.
_buildResultMap ( Query $fetchQuery, array $options ) : array	Builds an array containing the results from fetchQuery indexed by the foreignKey value corresponding to this association.
_checkPersistenceStatus ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities ) : boolean	Throws an exception should any of the passed entities is not persisted.
_collectJointEntities ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities ) : array	Returns the list of joint entities that exist between the source entity and each of the passed target entities
_diffLinks ( Query $existing, array $jointEntities, array $targetEntities, array $options = [] ) : array	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.
_generateJunctionAssociations ( Table $junction, Table $source, Table $target ) : void	Generate associations on the junction table as necessary
_generateSourceAssociations ( Table $junction, Table $source ) : void	Generate additional source table associations as necessary.
_generateTargetAssociations ( Table $junction, Table $source, Table $target ) : void	Generate reciprocal associations as necessary.
_joinCondition ( array $options ) : boolean	Return false as join conditions are defined in the junction table
_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.
_junctionTableName ( string \| null $name = null ) : string	Sets the name of the junction table.
_linkField ( array $options ) : string	Generates a string used as a table field that contains the values upon which the filter should be applied
_options ( array $opts ) : void	Parse extra options passed in the constructor.
_saveLinks ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options ) : boolean	Creates links between the source entity and each of the passed target entities
_saveTarget ( Cake\Datasource\EntityInterface $parentEntity, array \| Traversable $entities, array $options ) : Cake\Datasource\EntityInterface \| 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.
junctionConditions ( ) : array	Returns filtered conditions that specifically reference the junction table.
targetConditions ( ) : mixed	Returns filtered conditions that reference the target table.

Method Details

_appendJunctionJoin() protected method

Append a join to the junction table.

protected _appendJunctionJoin ( Query $query, string \| array $conditions ) : Query
$query	Cake\ORM\Query	The query to append.
$conditions	string \| array	The query conditions to use.
return	Cake\ORM\Query	The modified query.

_appendNotMatching() protected method

{@inheritDoc}

protected _appendNotMatching ( $query, $options )

_buildBaseQuery() public method

public _buildBaseQuery ( )

_buildQuery() protected method

This is used for eager loading records on the target table based on conditions.

protected _buildQuery ( array $options ) : Query
$options	array	options accepted by eagerLoader()
return	Cake\ORM\Query

_buildResultMap() protected method

Builds an array containing the results from fetchQuery indexed by the foreignKey value corresponding to this association.

protected _buildResultMap ( Query $fetchQuery, array $options ) : array
$fetchQuery	Cake\ORM\Query	The query to get results from
$options	array	The options passed to the eager loader
return	array

_checkPersistenceStatus() protected method

Throws an exception should any of the passed entities is not persisted.

protected _checkPersistenceStatus ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities ) : boolean
$sourceEntity	Cake\Datasource\EntityInterface	the row belonging to the `source` side of this association
$targetEntities	array	list of entities belonging to the `target` side of this association
return	boolean

_collectJointEntities() protected method

Returns the list of joint entities that exist between the source entity and each of the passed target entities

protected _collectJointEntities ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities ) : array
$sourceEntity	Cake\Datasource\EntityInterface	The row belonging to the source side of this association.
$targetEntities	array	The rows belonging to the target side of this association.
return	array

_diffLinks() protected method

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.

protected _diffLinks ( Query $existing, array $jointEntities, array $targetEntities, array $options = [] ) : array
$existing	Cake\ORM\Query	a query for getting existing links
$jointEntities	array	link entities that should be persisted
$targetEntities	array	entities in target table that are related to the `$jointEntities`
$options	array	list of options accepted by `Table::delete()`
return	array

_externalOptions() public method

public _externalOptions ( )

_generateJunctionAssociations() protected method

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.

protected _generateJunctionAssociations ( Table $junction, Table $source, Table $target ) : void
$junction	Cake\ORM\Table	The junction table.
$source	Cake\ORM\Table	The source table.
$target	Cake\ORM\Table	The target table.
return	void

_generateSourceAssociations() protected method

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.

protected _generateSourceAssociations ( Table $junction, Table $source ) : void
$junction	Cake\ORM\Table	The junction table.
$source	Cake\ORM\Table	The source table.
return	void

_generateTargetAssociations() protected method

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.

protected _generateTargetAssociations ( Table $junction, Table $source, Table $target ) : void
$junction	Cake\ORM\Table	The junction table.
$source	Cake\ORM\Table	The source table.
$target	Cake\ORM\Table	The target table.
return	void

_joinCondition() protected method

Return false as join conditions are defined in the junction table

protected _joinCondition ( array $options ) : boolean
$options	array	list of options passed to attachTo method
return	boolean	false

_junctionAssociationName() protected method

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.

protected _junctionAssociationName ( ) : string
return	string

_junctionTableName() protected method

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.

protected _junctionTableName ( string \| null $name = null ) : string
$name	string \| null	The name of the junction table.
return	string

_linkField() protected method

Generates a string used as a table field that contains the values upon which the filter should be applied

protected _linkField ( array $options ) : string
$options	array	the options to use for getting the link field.
return	string

_options() protected method

Parse extra options passed in the constructor.

protected _options ( array $opts ) : void
$opts	array	original list of options passed in constructor
return	void

_saveLinks() protected method

Creates links between the source entity and each of the passed target entities

protected _saveLinks ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options ) : boolean
$sourceEntity	Cake\Datasource\EntityInterface	the entity from source table in this association
$targetEntities	array	list of entities to link to link to the source entity using the junction table
$options	array	list of options accepted by `Table::save()`
return	boolean	success

_saveTarget() protected method

Persists each of the entities into the target table and creates links between the parent entity and each one of the saved target entities.

protected _saveTarget ( Cake\Datasource\EntityInterface $parentEntity, array \| Traversable $entities, array $options ) : Cake\Datasource\EntityInterface \| boolean
$parentEntity	Cake\Datasource\EntityInterface	the source entity containing the target entities to be saved.
$entities	array \| Traversable	list of entities to persist in target table and to link to the parent entity
$options	array	list of options accepted by `Table::save()`
return	Cake\Datasource\EntityInterface \| boolean	The parent entity after all links have been created if no errors happened, false otherwise

attachTo() public method

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)

public attachTo ( Query $query, array $options = [] ) : void
$query	Cake\ORM\Query	the query to be altered to include the target table data
$options	array	Any extra options or overrides to be taken in account
return	void

cascadeDelete() public method

Clear out the data in the junction table for a given entity.

public cascadeDelete ( Cake\Datasource\EntityInterface $entity, array $options = [] ) : boolean
$entity	Cake\Datasource\EntityInterface	The entity that started the cascading delete.
$options	array	The options for the original delete.
return	boolean	Success.

conditions() public method

{@inheritDoc}

public conditions ( $conditions = null )

find() public method

If your association includes conditions, the junction table will be included in the query's contained associations.

isOwningSide() public method

Returns boolean true, as both of the tables 'own' rows in the other side of the association via the joint table.

public isOwningSide ( Table $side ) : boolean
$side	Cake\ORM\Table	The potential Table with ownership
return	boolean

junction() public method

Sets the table instance for the junction relation. If no arguments are passed, the current configured table instance is returned

public junction ( string \| Table \| null $table = null ) : Table
$table	string \| Cake\ORM\Table \| null	Name or instance for the join table
return	Cake\ORM\Table

junctionConditions() protected method

Returns filtered conditions that specifically reference the junction table.

protected junctionConditions ( ) : array
return	array

link() public method

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->association('tags')->link($article, $newTags); $article->get('tags') will contain all tags in $newTags after liking

public link ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = [] ) : boolean
$sourceEntity	Cake\Datasource\EntityInterface	the row belonging to the `source` side of this association
$targetEntities	array	list of entities belonging to the `target` side of this association
$options	array	list of options to be passed to the internal `save` call
return	boolean	true on success, false otherwise

replaceLinks() public method

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->association('tags')->replaceLinks($article, $tags); $article->get('tags') will contain only [$tag1, $tag3] at the end

public replaceLinks ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array $options = [] ) : boolean
$sourceEntity	Cake\Datasource\EntityInterface	an entity persisted in the source table for this association
$targetEntities	array	list of entities from the target table to be linked
$options	array	list of options to be passed to the internal `save`/`delete` calls when persisting/updating new links, or deleting existing ones
return	boolean	success

saveAssociated() public method

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.

saveStrategy() public method

Sets the strategy that should be used for saving. If called with no arguments, it will return the currently configured strategy

public saveStrategy ( string \| null $strategy = null ) : string
$strategy	string \| null	the strategy name to be used
return	string	the strategy to be used for saving

targetConditions() protected method

Any string expressions, or expression objects will also be returned in this list.

protected targetConditions ( ) : mixed
return	mixed	Generally an array. If the conditions are not an array, the association conditions will be returned unmodified.

targetForeignKey() public method

If no parameters are passed current field is returned

public targetForeignKey ( string \| null $key = null ) : string
$key	string \| null	the key to be used to link both tables together
return	string

type() public method

Get the relationship type.

public type ( ) : string
return	string

unlink() public method

### Options Additionally to the default options accepted by Table::delete(), the following keys are supported: - cleanProperty: Whether or not 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->association('tags')->unlink($article, $tags); $article->get('tags') will contain only [$tag4] after deleting in the database

public unlink ( Cake\Datasource\EntityInterface $sourceEntity, array $targetEntities, array \| boolean $options = [] ) : boolean
$sourceEntity	Cake\Datasource\EntityInterface	an entity persisted in the source table for this association
$targetEntities	array	list of entities persisted in the target table for this association
$options	array \| boolean	list of options to be passed to the internal `delete` call, or a `boolean`
return	boolean	Success

Property Details

$_dependent protected_oe property

Defaults to true for backwards compatibility.

protected bool $_dependent
return	boolean

$_joinType protected_oe property

The type of join to be used when adding the association to a query

protected string $_joinType
return	string

$_junctionAssociationName protected_oe property

The name of the hasMany association from the target table to the junction table

protected string $_junctionAssociationName
return	string

$_junctionConditions protected_oe property

Filtered conditions that reference the junction table.

protected null\|array $_junctionConditions
return	null \| array

$_junctionProperty protected_oe property

The name of the property to be set containing data from the junction table once a record from the target table is hydrated

protected string $_junctionProperty
return	string

$_junctionTable protected_oe property

Junction table instance

protected Table,Cake\ORM $_junctionTable
return	Cake\ORM\Table

$_junctionTableName protected_oe property

Junction table name

protected string $_junctionTableName
return	string

$_saveStrategy protected_oe property

Saving strategy to be used by this association

protected string $_saveStrategy
return	string

$_strategy protected_oe property

The strategy name to be used to fetch associated records.

protected string $_strategy
return	string

$_targetConditions protected_oe property

Filtered conditions that reference the target table.

protected null\|array $_targetConditions
return	null \| array

$_targetForeignKey protected_oe property

The name of the field representing the foreign key to the target table

protected string\|array $_targetForeignKey
return	string \| array

$_through protected_oe property

The table instance for the junction relation.

protected string\|Table,Cake\ORM $_through
return	string \| Cake\ORM\Table

$_validStrategies protected_oe property

Valid strategies for this type of association

protected array $_validStrategies
return	array

public find ( string \| array \| null $type = null, array $options = [] ) : Query
$type	string \| array \| null	the type of query to perform, if an array is passed, it will be interpreted as the `$options` parameter
$options	array	The options to for the find
return	Cake\ORM\Query

public saveAssociated ( Cake\Datasource\EntityInterface $entity, array $options = [] ) : boolean \| Cake\Datasource\EntityInterface
$entity	Cake\Datasource\EntityInterface	an entity from the source table
$options	array	options to be passed to the save method in the target table
return	boolean \| Cake\Datasource\EntityInterface	false if $entity could not be saved, otherwise it returns the saved entity