Add fields API to Document

[thekid]

This pull request adds 3 methods to the com.mongodb.Document class, get(), with() and unset(). All of these operate on fields instead of property names, the difference being that the field context.readonly references a context object's readonly property, where as property names are unparsed.

Accessing fields

use com\mongodb\Document;

$doc= new Document(['topic' => 'Test', 'context' => ['readonly' => true]]);

$fixture->get('topic');             // "Test", like $fixture['topic']
$fixture->get('context.readonly');  // true, like $fixture['context']['readonly']
$fixture->get('state');             // null, like $fixture['state'] ?? null

Modifying fields

use com\mongodb\Document;

$doc= $collection->find(['name' => 'Test']);

// Create a copy of this document
$collection->insert($doc
  ->unset('_id')
  ->with('name', 'Copy of '.$doc['name'])
  ->update(['updated' => $now, 'owner' => $user])
);

[thekid]

Real-life example:

Before

$dialogue= $this->dialogues->find($id)->first();

unset($dialogue['_id'], $dialogue['connections'], $dialogue['state']);
$dialogue['context']['readonly']= true;
$dialogue['published']= ['by' => $this->identity($user), 'at' => Date::now()];
$dialogue['helpful']= [];
$dialogue['topic']= $topic;

$this->dialogues->insert($dialogue);

After

$dialogue= $this->dialogues->find($id)->first();

$this->dialogues->insert($dialogue
  ->unset('_id', 'connection', 'state')
  ->with('context.readonly', true)
  ->with('published', ['by' => $this->identity($user), 'at' => Date::now()]),
  ->with('helpful', [])
  ->with('topic', $topic)
);

[thekid]

Released in https://github.com/xp-forge/mongodb/releases/tag/v3.3.0