PHPLIB-60: Create result classes for CRUD methods

The bulkWrite() method still returns the driver's original WriteResult class. We may change this to use a library-specific wrapper class later.

Author: jmikola

src/Collection.php

@@ -406,11 +406,10 @@ public function bulkWrite(array $bulk, array $options = array())
      * Inserts the provided document
      *
      * @see http://docs.mongodb.org/manual/reference/command/insert/
-     * @see Collection::getWriteOptions() for supported $options
      *
      * @param array $document  The document to insert
      * @param array $options   Additional options
-     * @return InsertResult
+     * @return InsertOneResult
      */
     public function insertOne(array $document)
     {
@@ -420,7 +419,7 @@ public function insertOne(array $document)
         $id    = $bulk->insert($document);
         $wr    = $this->manager->executeBulkWrite($this->ns, $bulk, $this->wc);
 
-        return new InsertResult($wr, $id);
+        return new InsertOneResult($wr, $id);
     }
 
     /**

src/DeleteResult.php

@@ -4,17 +4,46 @@
 
 use MongoDB\Driver\WriteResult;
 
+/**
+ * Result class for a delete operation.
+ */
 class DeleteResult
 {
-    protected $wr;
+    private $writeResult;
 
-    public function __construct(WriteResult $wr)
+    /**
+     * Constructor.
+     *
+     * @param WriteResult $writeResult
+     */
+    public function __construct(WriteResult $writeResult)
     {
-        $this->wr = $wr;
+        $this->writeResult = $writeResult;
     }
 
+    /**
+     * Return the number of documents that were deleted.
+     *
+     * This value is undefined if the write was not acknowledged.
+     *
+     * @see UpdateResult::isAcknowledged()
+     * @return integer
+     */
     public function getDeletedCount()
     {
-        return $this->wr->getDeletedCount();
+        return $this->writeResult->getDeletedCount();
+    }
+
+    /**
+     * Return whether this delete was acknowledged by the server.
+     *
+     * If the delete was not acknowledged, other fields from the WriteResult
+     * (e.g. deletedCount) will be undefined.
+     *
+     * @return boolean
+     */
+    public function isAcknowledged()
+    {
+        return $this->writeResult->isAcknowledged();
     }
 }

src/InsertOneResult.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace MongoDB;
+
+use BSON\ObjectId;
+use MongoDB\Driver\WriteResult;
+
+/**
+ * Result class for a single-document insert operation.
+ */
+class InsertOneResult
+{
+    private $writeResult;
+    private $insertedId;
+
+    /**
+     * Constructor.
+     *
+     * @param WriteResult $writeResult
+     * @param ObjectId    $insertedId
+     */
+    public function __construct(WriteResult $writeResult, ObjectId $insertedId = null)
+    {
+        $this->writeResult = $writeResult;
+        $this->insertedId = $insertedId;
+    }
+
+    /**
+     * Return the number of documents that were inserted.
+     *
+     * This value is undefined if the write was not acknowledged.
+     *
+     * @see InsertOneResult::isAcknowledged()
+     * @return integer
+     */
+    public function getInsertedCount()
+    {
+        return $this->writeResult->getInsertedCount();
+    }
+
+    /**
+     * Return the inserted ID that was generated by the driver.
+     *
+     * If the inserted document already had an ID (e.g. it was generated by the
+     * application), this will be null.
+     *
+     * @return ObjectId|null
+     */
+    public function getInsertedId()
+    {
+        return $this->insertedId;
+    }
+
+    /**
+     * Return whether this insert was acknowledged by the server.
+     *
+     * If the insert was not acknowledged, other fields from the WriteResult
+     * (e.g. insertedCount) will be undefined.
+     *
+     * @return boolean
+     */
+    public function isAcknowledged()
+    {
+        return $this->writeResult->isAcknowledged();
+    }
+}

src/InsertResult.php

@@ -2,29 +2,76 @@
 
 namespace MongoDB;
 
+use BSON\ObjectId;
 use MongoDB\Driver\WriteResult;
 
+/**
+ * Result class for an update operation.
+ */
 class UpdateResult
 {
-    protected $wr;
+    private $writeResult;
 
-    public function __construct(WriteResult $wr)
+    /**
+     * Constructor.
+     *
+     * @param WriteResult $writeResult
+     */
+    public function __construct(WriteResult $writeResult)
     {
-        $this->wr = $wr;
+        $this->writeResult = $writeResult;
     }
 
+    /**
+     * Return the number of documents that were matched by the filter.
+     *
+     * This value is undefined if the write was not acknowledged.
+     *
+     * @see UpdateResult::isAcknowledged()
+     * @return integer
+     */
     public function getMatchedCount()
     {
-        return $this->wr->getMatchedCount();
+        return $this->writeResult->getMatchedCount();
     }
 
+    /**
+     * Return the number of documents that were modified.
+     *
+     * This value is undefined if the write was not acknowledged.
+     *
+     * @see UpdateResult::isAcknowledged()
+     * @return integer
+     */
     public function getModifiedCount()
     {
-        return $this->wr->getModifiedCount();
+        return $this->writeResult->getModifiedCount();
     }
 
+    /**
+     * Return the ID of the document inserted by an upsert operation.
+     *
+     * This value is undefined if an upsert did not take place.
+     *
+     * @return ObjectId|null
+     */
     public function getUpsertedId()
     {
-        return $this->wr->getUpsertedIds()[0];
+        foreach ($this->writeResult->getUpsertedIds() as $id) {
+            return $id;
+        }
+    }
+
+    /**
+     * Return whether this update was acknowledged by the server.
+     *
+     * If the update was not acknowledged, other fields from the WriteResult
+     * (e.g. matchedCount) will be undefined.
+     *
+     * @return boolean
+     */
+    public function isAcknowledged()
+    {
+        return $this->writeResult->isAcknowledged();
     }
 }

src/UpdateResult.php

@@ -21,7 +21,7 @@ function testInsertAndRetrieve() {
         for($i=0; $i<10;$i++) {
             $user = createUser($this->faker);
             $result = $collection->insertOne($user);
-            $this->assertInstanceOf('MongoDB\InsertResult', $result);
+            $this->assertInstanceOf('MongoDB\InsertOneResult', $result);
             $this->assertInstanceOf('BSON\ObjectId', $result->getInsertedId());
             $this->assertEquals(24, strlen($result->getInsertedId()));