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 |
/**
* Tests that replaceLink requires the sourceEntity to have primaryKey values
* for the source entity
*
* @expectedException \InvalidArgumentException
* @expectedExceptionMessage Could not find primary key value for source entity
* @return void
*/
public function testReplaceWithMissingPrimaryKey()
{
$config = ['sourceTable' => $this->article, 'targetTable' => $this->tag, 'joinTable' => 'tags_articles'];
$assoc = new BelongsToMany('Test', $config);
$entity = new Entity(['foo' => 1], ['markNew' => false]);
$tags = [new Entity(['id' => 2]), new Entity(['id' => 3])];
$assoc->replaceLinks($entity, $tags);
}
