Add query API to collections

[thekid]

This pull request adds two methods to the com.mongodb.Collection class, query() and first().

---

The query() method is liberal in what it accepts:

$cursor= $collection->query();                      // same as ->find()
$cursor= $collection->query([])                     // same as ->find([])
$cursor= $collection->query($objectId);             // same as ->find($objectId)
$cursor= $collection->query(['color' => 'green']);  // same as ->find(['color' => 'green'])

---

The query() method delegates to aggregate() if passed an array of arrays. This allows refactoring queries from simple matching semantics to pipelines easily:

// Before
$cursor= $collection->query(['color' => 'green', 'state' => 'ACTIVE']);

// We decide to join on users
$cursor= $collection->query([
  ['$match' => ['color' => 'green', 'state' => 'ACTIVE']],
  ['$lookup' => [
    'from'         => 'users',
    'localField'   => 'owner.id',
    'foreignField' => '_id',
    'as'           => 'owner',
  ]],
  ['$addFields' => ['owner' => ['$first' => '$owner']]],
]);

---

The first() method is a shorthand for query()->first(). This shortens the common case of writing $cursor= $collection->aggregate(...); return $cursor->first() as described in #46:

$document= $collection->first($query);

[thekid]

Example on how this makes code more concise from https://github.com/thekid/dialog:

diff --git a/src/main/php/de/thekid/dialog/Repository.php b/src/main/php/de/thekid/dialog/Repository.php
index db1c9fa..748cd32 100755
--- a/src/main/php/de/thekid/dialog/Repository.php
+++ b/src/main/php/de/thekid/dialog/Repository.php
@@ -27,11 +27,10 @@ class Repository {
 
   /** Authenticates a given user, returning NULL on failure */
   public function authenticate(string $user, Secret $secret): ?Document {
-    $cursor= $this->collection('users')->find([
+    return $this->collection('users')->first([
       'handle' => $user,
       'hash'   => $this->passwords->digest($secret->reveal())->hex()
     ]);
-    return $cursor->first();
   }
 
   /** Returns newest entries */
@@ -110,7 +109,7 @@ class Repository {
         ['text' => ['path' => 'slug', 'query' => '@cover']
       ]],
     ];
-    $meta= $this->collection('entries')->aggregate([
+    $meta= $this->collection('entries')->first([
       ['$searchMeta' => [
         'index'    => $this->database,
         'count'    => ['type' => 'lowerBound'],
@@ -128,16 +127,15 @@ class Repository {
       ['$skip'      => $pagination->skip($page)],
       ['$limit'     => $pagination->limit()],
     ]);
-    return new SearchResult($meta->first(), $pagination->paginate($page, $cursor));
+    return new SearchResult($meta, $pagination->paginate($page, $cursor));
   }
 
   /** Returns a single entry */
   public function entry(string $slug, bool $published= true): ?Document {
-    $cursor= $this->collection('entries')->aggregate([
+    return $this->collection('entries')->first([
       ['$match' => ['slug' => $slug] + ($published ? ['published' => ['$lt' => Date::now()]] : [])],
       ['$unset' => '_searchable'],
     ]);
-    return $cursor->first();
   }
 
   /** Returns an entry's children, latest first */

[thekid]

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