Renaming Entity::update() to Entity::sync() to better reflect fun…

…ctionality, and reduce API ambiguity.

data/Entity.php

@@ -292,13 +292,20 @@ public function exists() {
 	 * @see lithium\data\Model::save()
 	 * @param mixed $id The ID to assign, where applicable.
 	 * @param array $data Any additional generated data assigned to the object by the database.
+	 * @param array $options Method options:
+	 *              - `'materialize'` _boolean_: Determines whether or not the flag should be set
+	 *                that indicates that this entity exists in the data store. Defaults to `true`.
 	 * @return void
 	 */
-	public function update($id = null, array $data = array()) {
-		$this->_exists = true;
+	public function sync($id = null, array $data = array(), array $options = array()) {
+		$defaults = array('materialize' => true);
+		$options += $defaults;
 		$model = $this->_model;
 		$key = array();
 
+		if ($options['materialize']) {
+			$this->_exists = true;
+		}
 		if ($id && $model) {
 			$key = $model::meta('key');
 			$key = is_array($key) ? array_combine($key, $id) : array($key => $id);

data/collection/DocumentArray.php

@@ -40,7 +40,7 @@ public function exists() {
 		return $this->_exists;
 	}
 
-	public function update($id = null, array $data = array()) {
+	public function sync($id = null, array $data = array()) {
 		$this->_exists = true;
 		$this->_data = $data ?: $this->_data;
 	}

data/entity/Document.php

@@ -164,15 +164,31 @@ public function export() {
 		return parent::export() + array('key' => $this->_pathKey, 'remove' => $this->_removed);
 	}
 
-	public function update($id = null, array $data = array()) {
-		parent::update($id, $data);
+	/**
+	 * Extends the parent implementation to ensure that child documents are properly synced as well.
+	 *
+	 * @param mixed $id
+	 * @param array $data
+	 * @param array Options when calling this method:
+	 *              - `'recursive'` _boolean_: If `true` attempts to sync nested objects as well.
+	 *                Otherwise, only syncs the current object. Defaults to `true`.
+	 * @return void
+	 */
+	public function sync($id = null, array $data = array(), array $options = array()) {
+		$defaults = array('recursive' => true);
+		$options += $defaults;
+
+		if (!$options['recursive']) {
+			return parent::sync($id, $data, $options);
+		}
 
-		foreach ($this->_data as $key => $val) {
-			if (is_object($val) && method_exists($val, 'update')) {
-				$this->_data[$key]->update(null, isset($data[$key]) ? $data[$key] : array());
+		foreach ($this->_updated as $key => $val) {
+			if (is_object($val) && method_exists($val, 'sync')) {
+				$nested = isset($data[$key]) ? $data[$key] : array();
+				$this->_updated[$key]->sync(null, $nested, $options);
 			}
 		}
-		$this->_removed = array();
+		parent::sync($id, $data, $options);
 	}
 
 	/**

data/source/Database.php

@@ -231,7 +231,7 @@ public function create($query, array $options = array()) {
 				if (($model) && !$model::key($entity)) {
 					$id = $self->invokeMethod('_insertId', array($object));
 				}
-				$entity->update($id);
+				$entity->sync($id);
 			}
 			return true;
 		});
@@ -335,7 +335,7 @@ public function update($query, array $options = array()) {
 
 			if ($self->invokeMethod('_execute', array($sql))) {
 				if ($query->entity()) {
-					$query->entity()->update();
+					$query->entity()->sync();
 				}
 				return true;
 			}

data/source/MongoDb.php

@@ -392,7 +392,7 @@ public function create($query, array $options = array()) {
 
 			if ($result === true || isset($result['ok']) && (boolean) $result['ok'] === true) {
 				if ($query->entity()) {
-					$query->entity()->update($data['create']['_id']);
+					$query->entity()->sync($data['create']['_id']);
 				}
 				return true;
 			}
@@ -528,7 +528,7 @@ public function update($query, array $options = array()) {
 				$update = array('$set' => $update);
 			}
 			if ($self->connection->{$source}->update($args['conditions'], $update, $options)) {
-				$query->entity() ? $query->entity()->update() : null;
+				$query->entity() ? $query->entity()->sync() : null;
 				return true;
 			}
 			return false;

data/source/http/adapter/CouchDb.php

@@ -198,7 +198,7 @@ public function create($query, array $options = array()) {
 
 			if (isset($result['_id']) || (isset($result['ok']) && $result['ok'] === true)) {
 				$result = $self->invokeMethod('_format', array($result, $options));
-				$query->entity()->update($result['id'], $result);
+				$query->entity()->sync($result['id'], $result);
 				return true;
 			}
 			return false;
@@ -281,7 +281,7 @@ public function update($query, array $options = array()) {
 
 			if (isset($result['_id']) || (isset($result['ok']) && $result['ok'] === true)) {
 				$result = $self->invokeMethod('_format', array($result, $options));
-				$query->entity()->update($result['id'], array('rev' => $result['rev']));
+				$query->entity()->sync($result['id'], array('rev' => $result['rev']));
 				return true;
 			}
 			if (isset($result['error'])) {

tests/cases/data/EntityTest.php

@@ -50,7 +50,7 @@ public function testIncrement() {
 
 		$this->assertFalse(isset($entity->bar));
 		$entity->bar = 'blah';
-		$entity->update();
+		$entity->sync();
 
 		$this->expectException("/^Field 'bar' cannot be incremented.$/");
 		$entity->increment('bar');

tests/cases/data/entity/RecordTest.php

@@ -117,7 +117,7 @@ public function testSetData() {
 
 	public function testRecordExists() {
 		$this->assertFalse($this->record->exists());
-		$this->record->update(313);
+		$this->record->sync(313);
 		$this->assertIdentical(313, $this->record->id);
 		$this->assertTrue($this->record->exists());
 

tests/cases/data/source/mongo_db/ExporterTest.php

@@ -172,8 +172,6 @@ public function testFieldRemoval() {
 	/**
 	 * Tests that when an existing object is attached as a value of another existing object, the
 	 * whole sub-object is re-written to the new value.
-	 *
-	 * @return void
 	 */
 	public function testAppendExistingObjects() {
 		$doc = new Document(array('exists' => true, 'data' => array(
@@ -188,15 +186,15 @@ public function testAppendExistingObjects() {
 		$result = Exporter::get('update', $doc->export());
 		$expected = array('update' => array('deeply' => array('foo' => 'bar')));
 		$this->assertEqual($expected, $result);
-		$doc->update();
 
 		$expected = array('$set' => array('deeply' => array('foo' => 'bar')));
 		$this->assertEqual($expected, Exporter::toCommand($result));
 
+		$doc->sync();
 		$doc->append2 = new Document(array('exists' => false, 'data' => array('foo' => 'bar')));
 		$expected = array('update' => array('append2' => array('foo' => 'bar')));
 		$this->assertEqual($expected, Exporter::get('update', $doc->export()));
-		$doc->update();
+		$doc->sync();
 
 		$this->assertFalse(Exporter::get('update', $doc->export()));
 		$doc->append2->foo = 'baz';
@@ -206,6 +204,7 @@ public function testAppendExistingObjects() {
 		$expected = array('update' => array(
 			'append2.foo' => 'baz', 'append2.bar' => 'dib', 'deeply.nested' => true
 		));
+
 		$this->assertEqual($expected, Exporter::get('update', $doc->export()));
 	}