Added patchEntity and patchEntities to Table

src/Datasource/RepositoryInterface.php

@@ -169,4 +169,43 @@ public function newEntity(array $data = [], $associations = null);
  */
 	public function newEntities(array $data, $associations = null);
 
+/**
+ * Merges the passed `$data` into `$entity` respecting the accessible
+ * fields as configured for it. Returns the same entity after being
+ * altered.
+ *
+ * This is most useful when editing an existing entity using request data:
+ *
+ * {{{
+ * $article = $this->Articles->patchEntity($article, $this->request->data());
+ * }}}
+ *
+ * @param \Cake\Datasource\EntityInterface $entity the entity that will get the
+ * data merged in
+ * @param array $data key value list of fields to be merged into the entity
+ * @param array $include The list of associations to be merged
+ * @return \Cake\Datasource\EntityInterface
+ */
+	public function  patchEntity(EntityInterface $entity, array $data, $associations = null);
+
+/**
+ * Merges the each for the elements passed in `$data` into each of the entities
+ * found in `$entities` respecting the accessible fields as configured for it.
+ * Merging is done by matching the primary key in each of the elements in `$data`
+ * and `$entities`.
+ *
+ * This is most useful when editing a list of existing entities using request data:
+ *
+ * {{{
+ * $article = $this->Articles->patchEntities($articles, $this->request->data());
+ * }}}
+ *
+ * @param array|\Traversable $entities the entities that will get the
+ * data merged in
+ * @param array $data list of arrays to be merged into the entities
+ * @param array $include The list of associations to be merged
+ * @return array
+ */
+	public function  patchEntities($entities, array $data, $associations = null);
+
 }

src/ORM/Table.php

@@ -1571,6 +1571,40 @@ public function newEntities(array $data, $associations = null) {
 		return $marshaller->many($data, $associations);
 	}
 
+/**
+ * {@inheritdoc}
+ *
+ * When merging HasMany or BelongsToMany associations, all the entities in the
+ * `$data` array will appear, those that can be matched by primary key will get
+ * the data merged, but those that cannot, will be discarded.
+ */
+	public function patchEntity(EntityInterface $entity, array $data, $associations = null) {
+		if ($associations === null) {
+			$associations = $this->_associated->keys();
+		}
+		$marshaller = $this->marshaller();
+		return $marshaller->merge($entity, $data, $associations);
+	}
+
+/**
+ * {@inheritdoc}
+ *
+ * Those entries in `$entities` that cannot be matched to any record in
+ * `$data` will be discarded. Records in `$data` that could not be matched will
+ * be marshalled as a new entity.
+ *
+ * When merging HasMany or BelongsToMany associations, all the entities in the
+ * `$data` array will appear, those that can be matched by primary key will get
+ * the data merged, but those that cannot, will be discarded.
+ */
+	public function patchEntities($entities, array $data, $associations = null) {
+		if ($associations === null) {
+			$associations = $this->_associated->keys();
+		}
+		$marshaller = $this->marshaller();
+		return $marshaller->mergeMany($entities, $data, $associations);
+	}
+
 /**
  * Validates a single entity based on the passed options and validates
  * any nested entity for this table associations as requested in the

tests/TestCase/ORM/TableTest.php

@@ -3197,4 +3197,50 @@ public function testValidateManyWithCustomOptions() {
 		$this->assertFalse($table->validateMany($entities, $options));
 	}
 
+/**
+ * Tests that patchEntity delegates the task to the marshaller and passed
+ * all associations
+ *
+ * @return void
+ */
+	public function testPatchEntity() {
+		$table = $this->getMock('Cake\ORM\Table', ['marshaller']);
+		$marshaller = $this->getMock('Cake\ORM\Marshaller', [], [$table]);
+		$table->belongsTo('users');
+		$table->hasMany('articles');
+		$table->expects($this->once())->method('marshaller')
+			->will($this->returnValue($marshaller));
+
+		$entity = new \Cake\ORM\Entity;
+		$data = ['foo' => 'bar'];
+		$marshaller->expects($this->once())
+			->method('merge')
+			->with($entity, $data, ['users', 'articles'])
+			->will($this->returnValue($entity));
+		$table->patchEntity($entity, $data);
+	}
+
+/**
+ * Tests that patchEntities delegates the task to the marshaller and passed
+ * all associations
+ *
+ * @return void
+ */
+	public function testPatchEntities() {
+		$table = $this->getMock('Cake\ORM\Table', ['marshaller']);
+		$marshaller = $this->getMock('Cake\ORM\Marshaller', [], [$table]);
+		$table->belongsTo('users');
+		$table->hasMany('articles');
+		$table->expects($this->once())->method('marshaller')
+			->will($this->returnValue($marshaller));
+
+		$entities = [new \Cake\ORM\Entity];
+		$data = [['foo' => 'bar']];
+		$marshaller->expects($this->once())
+			->method('mergeMany')
+			->with($entities, $data, ['users', 'articles'])
+			->will($this->returnValue($entities));
+		$table->patchEntities($entities, $data);
+	}
+
 }