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

_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

_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.
See also: Cake\ORM\Table::find()
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

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

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.
See also: Cake\ORM\Table::save()
See also: Cake\ORM\Association\BelongsToMany::replaceLinks()
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

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

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