PHPLIB-68: Throw when accessing fields in unacknowledged write result

Author: jmikola

src/BulkWriteResult.php

@@ -2,8 +2,8 @@
 
 namespace MongoDB;
 
-use MongoDB\BSON\ObjectId;
 use MongoDB\Driver\WriteResult;
+use MongoDB\Exception\BadMethodCallException;
 
 /**
  * Result class for a bulk write operation.
@@ -12,6 +12,7 @@ class BulkWriteResult
 {
     private $writeResult;
     private $insertedIds;
+    private $isAcknowledged;
 
     /**
      * Constructor.
@@ -23,41 +24,53 @@ public function __construct(WriteResult $writeResult, array $insertedIds)
     {
         $this->writeResult = $writeResult;
         $this->insertedIds = $insertedIds;
+        $this->isAcknowledged = $writeResult->isAcknowledged();
     }
 
     /**
      * Return the number of documents that were deleted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getDeletedCount()
     {
-        return $this->writeResult->getDeletedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getDeletedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
      * Return the number of documents that were inserted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getInsertedCount()
     {
-        return $this->writeResult->getInsertedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getInsertedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
      * Return a map of the inserted documents' IDs.
      *
-     * The index of each ID in the map corresponds to the document's position
-     * in bulk operation. If the document had an ID prior to insertion (i.e. the
-     * driver did not generate an ID), this will contain its "_id" field value.
-     * Any driver-generated ID will be an MongoDB\Driver\ObjectID instance.
+     * The index of each ID in the map corresponds to the document's position in
+     * the bulk operation. If the document had an ID prior to insertion (i.e.
+     * the driver did not generate an ID), this will contain its "_id" field
+     * value. Any driver-generated ID will be an MongoDB\Driver\ObjectID
+     * instance.
      *
      * @return mixed[]
      */
@@ -69,41 +82,58 @@ public function getInsertedIds()
     /**
      * Return the number of documents that were matched by the filter.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getMatchedCount()
     {
-        return $this->writeResult->getMatchedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getMatchedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
      * Return the number of documents that were modified.
      *
-     * This value is undefined if the write was not acknowledged or if the write
-     * executed as a legacy operation instead of write command.
+     * This value is undefined (i.e. null) if the write executed as a legacy
+     * operation instead of command.
+     *
+     * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
      * @return integer|null
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getModifiedCount()
     {
-        return $this->writeResult->getModifiedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getModifiedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
      * Return the number of documents that were upserted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see BulkWriteResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getUpsertedCount()
     {
-        return $this->writeResult->getUpsertedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getUpsertedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
@@ -114,11 +144,19 @@ public function getUpsertedCount()
      * server did not need to generate an ID), this will contain its "_id". Any
      * server-generated ID will be an MongoDB\Driver\ObjectID instance.
      *
+     * This method should only be called if the write was acknowledged.
+     *
+     * @see BulkWriteResult::isAcknowledged()
      * @return mixed[]
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getUpsertedIds()
     {
-        return $this->writeResult->getUpsertedIds();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getUpsertedIds();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
@@ -131,6 +169,6 @@ public function getUpsertedIds()
      */
     public function isAcknowledged()
     {
-        return $this->writeResult->isAcknowledged();
+        return $this->isAcknowledged;
     }
 }

src/DeleteResult.php

@@ -3,13 +3,15 @@
 namespace MongoDB;
 
 use MongoDB\Driver\WriteResult;
+use MongoDB\Exception\BadMethodCallException;
 
 /**
  * Result class for a delete operation.
  */
 class DeleteResult
 {
     private $writeResult;
+    private $isAcknowledged;
 
     /**
      * Constructor.
@@ -19,19 +21,25 @@ class DeleteResult
     public function __construct(WriteResult $writeResult)
     {
         $this->writeResult = $writeResult;
+        $this->isAcknowledged = $writeResult->isAcknowledged();
     }
 
     /**
      * Return the number of documents that were deleted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
-     * @see UpdateResult::isAcknowledged()
+     * @see DeleteResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getDeletedCount()
     {
-        return $this->writeResult->getDeletedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getDeletedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
@@ -44,6 +52,6 @@ public function getDeletedCount()
      */
     public function isAcknowledged()
     {
-        return $this->writeResult->isAcknowledged();
+        return $this->isAcknowledged;
     }
 }

src/Exception/BadMethodCallException.php

@@ -4,4 +4,11 @@
 
 class BadMethodCallException extends \BadMethodCallException implements Exception
 {
+    /**
+     * Thrown when accessing a result field on an unacknowledged write result.
+     */
+    public static function unacknowledgedWriteResultAccess($method)
+    {
+        return new static(sprintf('%s should not be called for an unacknowledged write result', $method));
+    }
 }

src/InsertManyResult.php

@@ -3,14 +3,16 @@
 namespace MongoDB;
 
 use MongoDB\Driver\WriteResult;
+use MongoDB\Exception\BadMethodCallException;
 
 /**
- * Result class for a multi-document write operation.
+ * Result class for a multi-document insert operation.
  */
 class InsertManyResult
 {
     private $writeResult;
     private $insertedIds;
+    private $isAcknowledged;
 
     /**
      * Constructor.
@@ -22,28 +24,35 @@ public function __construct(WriteResult $writeResult, array $insertedIds)
     {
         $this->writeResult = $writeResult;
         $this->insertedIds = $insertedIds;
+        $this->isAcknowledged = $writeResult->isAcknowledged();
     }
 
     /**
      * Return the number of documents that were inserted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see InsertManyResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getInsertedCount()
     {
-        return $this->writeResult->getInsertedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getInsertedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
      * Return a map of the inserted documents' IDs.
      *
-     * The index of each ID in the map corresponds to the document's position
-     * in bulk operation. If the document had an ID prior to insertion (i.e. the
-     * driver did not generate an ID), this will contain its "_id" field value.
-     * Any driver-generated ID will be an MongoDB\Driver\ObjectID instance.
+     * The index of each ID in the map corresponds to the document's position in
+     * the bulk operation. If the document had an ID prior to insertion (i.e.
+     * the driver did not generate an ID), this will contain its "_id" field
+     * value. Any driver-generated ID will be an MongoDB\Driver\ObjectID
+     * instance.
      *
      * @return mixed[]
      */

src/InsertOneResult.php

@@ -3,6 +3,7 @@
 namespace MongoDB;
 
 use MongoDB\Driver\WriteResult;
+use MongoDB\Exception\BadMethodCallException;
 
 /**
  * Result class for a single-document insert operation.
@@ -11,6 +12,7 @@ class InsertOneResult
 {
     private $writeResult;
     private $insertedId;
+    private $isAcknowledged;
 
     /**
      * Constructor.
@@ -22,19 +24,25 @@ public function __construct(WriteResult $writeResult, $insertedId)
     {
         $this->writeResult = $writeResult;
         $this->insertedId = $insertedId;
+        $this->isAcknowledged = $writeResult->isAcknowledged();
     }
 
     /**
      * Return the number of documents that were inserted.
      *
-     * This value is undefined if the write was not acknowledged.
+     * This method should only be called if the write was acknowledged.
      *
      * @see InsertOneResult::isAcknowledged()
      * @return integer
+     * @throws BadMethodCallException is the write result is unacknowledged
      */
     public function getInsertedCount()
     {
-        return $this->writeResult->getInsertedCount();
+        if ($this->isAcknowledged) {
+            return $this->writeResult->getInsertedCount();
+        }
+
+        throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
     }
 
     /**
@@ -57,6 +65,10 @@ public function getInsertedId()
      * If the insert was not acknowledged, other fields from the WriteResult
      * (e.g. insertedCount) will be undefined.
      *
+     * If the insert was not acknowledged, other fields from the WriteResult
+     * (e.g. insertedCount) will be undefined and their getter methods should
+     * not be invoked.
+     *
      * @return boolean
      */
     public function isAcknowledged()