[Summary view]

Differences Between: [Versions 311 and 401]

   1  <?php
   2  /*
   3   * Copyright 2015-2017 MongoDB, Inc.
   4   *
   5   * Licensed under the Apache License, Version 2.0 (the "License");
   6   * you may not use this file except in compliance with the License.
   7   * You may obtain a copy of the License at
   8   *
   9   *   http://www.apache.org/licenses/LICENSE-2.0
  10   *
  11   * Unless required by applicable law or agreed to in writing, software
  12   * distributed under the License is distributed on an "AS IS" BASIS,
  13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14   * See the License for the specific language governing permissions and
  15   * limitations under the License.
  16   */
  17  
  18  namespace MongoDB;
  19  
  20  use MongoDB\Driver\WriteResult;
  21  use MongoDB\Exception\BadMethodCallException;
  22  
  23  /**
  24   * Result class for a bulk write operation.
  25   */
  26  class BulkWriteResult
  27  {
  28      /** @var WriteResult */
  29      private $writeResult;
  30  
  31      /** @var mixed[] */
  32      private $insertedIds;
  33  
  34      /** @var boolean */
  35      private $isAcknowledged;
  36  
  37      /**
  38       * @param WriteResult $writeResult
  39       * @param mixed[]     $insertedIds
  40       */
  41      public function __construct(WriteResult $writeResult, array $insertedIds)
  42      {
  43          $this->writeResult = $writeResult;
  44          $this->insertedIds = $insertedIds;
  45          $this->isAcknowledged = $writeResult->isAcknowledged();
  46      }
  47  
  48      /**
  49       * Return the number of documents that were deleted.
  50       *
  51       * This method should only be called if the write was acknowledged.
  52       *
  53       * @see BulkWriteResult::isAcknowledged()
  54       * @return integer
  55       * @throws BadMethodCallException is the write result is unacknowledged
  56       */
  57      public function getDeletedCount()
  58      {
  59          if ($this->isAcknowledged) {
  60              return $this->writeResult->getDeletedCount();
  61          }
  62  
  63          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
  64      }
  65  
  66      /**
  67       * Return the number of documents that were inserted.
  68       *
  69       * This method should only be called if the write was acknowledged.
  70       *
  71       * @see BulkWriteResult::isAcknowledged()
  72       * @return integer
  73       * @throws BadMethodCallException is the write result is unacknowledged
  74       */
  75      public function getInsertedCount()
  76      {
  77          if ($this->isAcknowledged) {
  78              return $this->writeResult->getInsertedCount();
  79          }
  80  
  81          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
  82      }
  83  
  84      /**
  85       * Return a map of the inserted documents' IDs.
  86       *
  87       * The index of each ID in the map corresponds to each document's position
  88       * in the bulk operation. If a document had an ID prior to inserting (i.e.
  89       * the driver did not generate an ID), the index will contain its "_id"
  90       * field value. Any driver-generated ID will be a MongoDB\BSON\ObjectId
  91       * instance.
  92       *
  93       * @return mixed[]
  94       */
  95      public function getInsertedIds()
  96      {
  97          return $this->insertedIds;
  98      }
  99  
 100      /**
 101       * Return the number of documents that were matched by the filter.
 102       *
 103       * This method should only be called if the write was acknowledged.
 104       *
 105       * @see BulkWriteResult::isAcknowledged()
 106       * @return integer
 107       * @throws BadMethodCallException is the write result is unacknowledged
 108       */
 109      public function getMatchedCount()
 110      {
 111          if ($this->isAcknowledged) {
 112              return $this->writeResult->getMatchedCount();
 113          }
 114  
 115          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
 116      }
 117  
 118      /**
 119       * Return the number of documents that were modified.
 120       *
 121       * This value is undefined (i.e. null) if the write executed as a legacy
 122       * operation instead of command.
 123       *
 124       * This method should only be called if the write was acknowledged.
 125       *
 126       * @see BulkWriteResult::isAcknowledged()
 127       * @return integer|null
 128       * @throws BadMethodCallException is the write result is unacknowledged
 129       */
 130      public function getModifiedCount()
 131      {
 132          if ($this->isAcknowledged) {
 133              return $this->writeResult->getModifiedCount();
 134          }
 135  
 136          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
 137      }
 138  
 139      /**
 140       * Return the number of documents that were upserted.
 141       *
 142       * This method should only be called if the write was acknowledged.
 143       *
 144       * @see BulkWriteResult::isAcknowledged()
 145       * @return integer
 146       * @throws BadMethodCallException is the write result is unacknowledged
 147       */
 148      public function getUpsertedCount()
 149      {
 150          if ($this->isAcknowledged) {
 151              return $this->writeResult->getUpsertedCount();
 152          }
 153  
 154          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
 155      }
 156  
 157      /**
 158       * Return a map of the upserted documents' IDs.
 159       *
 160       * The index of each ID in the map corresponds to each document's position
 161       * in bulk operation. If a document had an ID prior to upserting (i.e. the
 162       * server did not need to generate an ID), this will contain its "_id". Any
 163       * server-generated ID will be a MongoDB\BSON\ObjectId instance.
 164       *
 165       * This method should only be called if the write was acknowledged.
 166       *
 167       * @see BulkWriteResult::isAcknowledged()
 168       * @return mixed[]
 169       * @throws BadMethodCallException is the write result is unacknowledged
 170       */
 171      public function getUpsertedIds()
 172      {
 173          if ($this->isAcknowledged) {
 174              return $this->writeResult->getUpsertedIds();
 175          }
 176  
 177          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
 178      }
 179  
 180      /**
 181       * Return whether this update was acknowledged by the server.
 182       *
 183       * If the update was not acknowledged, other fields from the WriteResult
 184       * (e.g. matchedCount) will be undefined.
 185       *
 186       * @return boolean
 187       */
 188      public function isAcknowledged()
 189      {
 190          return $this->isAcknowledged;
 191      }
 192  }