[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401]

   1  <?php
   2  /*
   3   * Copyright 2015-present 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   *   https://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 an update operation.
  25   */
  26  class UpdateResult
  27  {
  28      /** @var WriteResult */
  29      private $writeResult;
  30  
  31      /** @var boolean */
  32      private $isAcknowledged;
  33  
  34      public function __construct(WriteResult $writeResult)
  35      {
  36          $this->writeResult = $writeResult;
  37          $this->isAcknowledged = $writeResult->isAcknowledged();
  38      }
  39  
  40      /**
  41       * Return the number of documents that were matched by the filter.
  42       *
  43       * This method should only be called if the write was acknowledged.
  44       *
  45       * @see UpdateResult::isAcknowledged()
  46       * @return integer|null
  47       * @throws BadMethodCallException is the write result is unacknowledged
  48       */
  49      public function getMatchedCount()
  50      {
  51          if ($this->isAcknowledged) {
  52              return $this->writeResult->getMatchedCount();
  53          }
  54  
  55          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
  56      }
  57  
  58      /**
  59       * Return the number of documents that were modified.
  60       *
  61       * This value is undefined (i.e. null) if the write executed as a legacy
  62       * operation instead of command.
  63       *
  64       * This method should only be called if the write was acknowledged.
  65       *
  66       * @see UpdateResult::isAcknowledged()
  67       * @return integer|null
  68       * @throws BadMethodCallException is the write result is unacknowledged
  69       */
  70      public function getModifiedCount()
  71      {
  72          if ($this->isAcknowledged) {
  73              return $this->writeResult->getModifiedCount();
  74          }
  75  
  76          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
  77      }
  78  
  79      /**
  80       * Return the number of documents that were upserted.
  81       *
  82       * This method should only be called if the write was acknowledged.
  83       *
  84       * @see UpdateResult::isAcknowledged()
  85       * @return integer|null
  86       * @throws BadMethodCallException is the write result is unacknowledged
  87       */
  88      public function getUpsertedCount()
  89      {
  90          if ($this->isAcknowledged) {
  91              return $this->writeResult->getUpsertedCount();
  92          }
  93  
  94          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
  95      }
  96  
  97      /**
  98       * Return the ID of the document inserted by an upsert operation.
  99       *
 100       * If the document had an ID prior to upserting (i.e. the server did not
 101       * need to generate an ID), this will contain its "_id". Any
 102       * server-generated ID will be a MongoDB\BSON\ObjectId instance.
 103       *
 104       * This value is undefined (i.e. null) if an upsert did not take place.
 105       *
 106       * This method should only be called if the write was acknowledged.
 107       *
 108       * @see UpdateResult::isAcknowledged()
 109       * @return mixed|null
 110       * @throws BadMethodCallException is the write result is unacknowledged
 111       */
 112      public function getUpsertedId()
 113      {
 114          if ($this->isAcknowledged) {
 115              foreach ($this->writeResult->getUpsertedIds() as $id) {
 116                  return $id;
 117              }
 118  
 119              return null;
 120          }
 121  
 122          throw BadMethodCallException::unacknowledgedWriteResultAccess(__METHOD__);
 123      }
 124  
 125      /**
 126       * Return whether this update was acknowledged by the server.
 127       *
 128       * If the update was not acknowledged, other fields from the WriteResult
 129       * (e.g. matchedCount) will be undefined and their getter methods should not
 130       * be invoked.
 131       *
 132       * @return boolean
 133       */
 134      public function isAcknowledged()
 135      {
 136          return $this->isAcknowledged;
 137      }
 138  }