Merge pull request #59 from xp-forge/feature/fluent-document

Add fields API to Document

Author: thekid

src/main/php/com/mongodb/Document.class.php

@@ -79,6 +79,72 @@ public function offsetUnset($name) {
   /** Iterator over all properties */
   public function getIterator(): Traversable { yield from $this->properties; }
 
+  /**
+   * Gets a field. Returns NULL if it did not exist.
+   *
+   * @param  string $field
+   * @return var
+   */
+  public function get($field) {
+    $ptr= &$this->properties;
+    foreach (explode('.', $field) as $path) {
+      $ptr= &$ptr[$path];
+    }
+    return $ptr;
+  }
+
+  /**
+   * Sets a field to a given value
+   *
+   * @param  string $field
+   * @param  var $value
+   * @return self
+   */
+  public function with($field, $value) {
+    $ptr= &$this->properties;
+    foreach (explode('.', $field) as $path) {
+      $ptr= &$ptr[$path];
+    }
+    $ptr= $value;
+    return $this;
+  }
+
+  /**
+   * Updates this document from a given iterable producing field => value pairs.
+   *
+   * @param  iterable $from
+   * @return self
+   */
+  public function update(iterable $from) {
+    foreach ($from as $field => $value) {
+      $ptr= &$this->properties;
+      foreach (explode('.', $field) as $path) {
+        $ptr= &$ptr[$path];
+      }
+      $ptr= $value;
+    }
+    return $this;
+  }
+
+  /**
+   * Unsets a list of fields
+   *
+   * @param  string... $fields
+   * @return self
+   */
+  public function unset(... $fields) {
+    foreach ($fields as $field) {
+      $paths= explode('.', $field);
+      $last= array_pop($paths);
+      $ptr= &$this->properties;
+      foreach ($paths as $path) {
+        $ptr= &$ptr[$path];
+      }
+      unset($ptr[$last]);
+    }
+    return $this;
+  }
+
   /** @return string */
   public function hashCode() {
     return 'D'.Objects::hashOf($this->properties);

src/test/php/com/mongodb/unittest/DocumentTest.class.php

@@ -18,6 +18,13 @@ private function representations() {
     yield [['_id' => 6100, 'key' => 'value'], "com.mongodb.Document(6100)@{\n  key: \"value\"\n}"];
   }
 
+  /** @return iterable */
+  private function iterables() {
+    yield [['topic' => 'Test']];
+    yield [new Document(['topic' => 'Test'])];
+    yield [(function() { yield 'topic' => 'Test'; })()];
+  }
+
   #[Test]
   public function can_create() {
     new Document();
@@ -115,6 +122,132 @@ public function set_offset_array_key() {
     Assert::equals(['color' => 'green', 'price' => 12.99], $fixture['properties']);
   }
 
+  #[Test]
+  public function get() {
+    $fixture= new Document(['topic' => 'Test', 'context' => ['readonly' => true]]);
+
+    Assert::equals('Test', $fixture->get('topic'));
+    Assert::equals(true, $fixture->get('context.readonly'));
+  }
+
+  #[Test]
+  public function get_non_existant() {
+    $fixture= new Document(['topic' => 'Test', 'context' => ['readonly' => true]]);
+
+    Assert::equals(null, $fixture->get('state'));
+    Assert::equals(null, $fixture->get('context.owner'));
+  }
+
+  #[Test, Values(from: 'iterables')]
+  public function update_from($iterable) {
+    $fixture= new Document(['id' => 'one']);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => 'Test'],
+      $fixture->update($iterable)->properties()
+    );
+  }
+
+  #[Test]
+  public function add_field_via_update() {
+    $fixture= new Document(['id' => 'one']);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => 'Test'],
+      $fixture->update(['topic' => 'Test'])->properties()
+    );
+  }
+
+  #[Test]
+  public function change_field_via_update() {
+    $fixture= new Document(['id' => 'one', 'topic' => 'Test']);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => 'Changed'],
+      $fixture->update(['topic' => 'Changed'])->properties()
+    );
+  }
+
+  #[Test]
+  public function change_nested_field_via_update() {
+    $fixture= new Document(['id' => 'one', 'topic' => ['en' => 'Test', 'de' => 'Test']]);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => ['en' => 'Changed', 'de' => 'Test']],
+      $fixture->update(['topic.en' => 'Changed'])->properties()
+    );
+  }
+
+  #[Test]
+  public function add_field_via_with() {
+    $fixture= new Document(['id' => 'one']);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => 'Test'],
+      $fixture->with('topic', 'Test')->properties()
+    );
+  }
+
+  #[Test]
+  public function change_field_via_with() {
+    $fixture= new Document(['id' => 'one', 'topic' => 'Test']);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => 'Changed'],
+      $fixture->with('topic', 'Changed')->properties()
+    );
+  }
+
+  #[Test]
+  public function change_nested_field_via_with() {
+    $fixture= new Document(['id' => 'one', 'topic' => ['en' => 'Test', 'de' => 'Test']]);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => ['en' => 'Changed', 'de' => 'Test']],
+      $fixture->with('topic.en', 'Changed')->properties()
+    );
+  }
+
+  #[Test]
+  public function remove_field() {
+    $fixture= new Document(['id' => 'one', 'topic' => 'Test']);
+
+    Assert::equals(
+      ['topic' => 'Test'],
+      $fixture->unset('id')->properties()
+    );
+  }
+
+  #[Test]
+  public function remove_fields() {
+    $fixture= new Document(['id' => 'one', 'connections' => [], 'topic' => 'Test']);
+
+    Assert::equals(
+      ['topic' => 'Test'],
+      $fixture->unset('id', 'connections')->properties()
+    );
+  }
+
+  #[Test]
+  public function remove_non_existant_field() {
+    $fixture= new Document(['topic' => 'Test']);
+
+    Assert::equals(
+      ['topic' => 'Test'],
+      $fixture->unset('id')->properties()
+    );
+  }
+
+  #[Test]
+  public function remove_nested_field() {
+    $fixture= new Document(['id' => 'one', 'topic' => ['en' => 'Test', 'de' => 'Test']]);
+
+    Assert::equals(
+      ['id' => 'one', 'topic' => ['de' => 'Test']],
+      $fixture->unset('topic.en')->properties()
+    );
+  }
+
   #[Test]
   public function create() {
     Assert::instance(ObjectId::class, Document::create()->id());