[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\Operation;
  19  
  20  use MongoDB\Driver\Command;
  21  use MongoDB\Driver\Cursor;
  22  use MongoDB\Driver\ReadPreference;
  23  use MongoDB\Driver\Server;
  24  use MongoDB\Driver\Session;
  25  use MongoDB\Exception\InvalidArgumentException;
  26  
  27  use function is_array;
  28  use function is_object;
  29  
  30  /**
  31   * Operation for executing a database command.
  32   *
  33   * @api
  34   * @see \MongoDB\Database::command()
  35   */
  36  class DatabaseCommand implements Executable
  37  {
  38      /** @var string */
  39      private $databaseName;
  40  
  41      /** @var Command */
  42      private $command;
  43  
  44      /** @var array */
  45      private $options;
  46  
  47      /**
  48       * Constructs a command.
  49       *
  50       * Supported options:
  51       *
  52       *  * readPreference (MongoDB\Driver\ReadPreference): The read preference to
  53       *    use when executing the command. This may be used when issuing the
  54       *    command to a replica set or mongos node to ensure that the driver sets
  55       *    the wire protocol accordingly or adds the read preference to the
  56       *    command document, respectively.
  57       *
  58       *  * session (MongoDB\Driver\Session): Client session.
  59       *
  60       *  * typeMap (array): Type map for BSON deserialization. This will be
  61       *    applied to the returned Cursor (it is not sent to the server).
  62       *
  63       * @param string       $databaseName Database name
  64       * @param array|object $command      Command document
  65       * @param array        $options      Options for command execution
  66       * @throws InvalidArgumentException for parameter/option parsing errors
  67       */
  68      public function __construct(string $databaseName, $command, array $options = [])
  69      {
  70          if (! is_array($command) && ! is_object($command)) {
  71              throw InvalidArgumentException::invalidType('$command', $command, 'array or object');
  72          }
  73  
  74          if (isset($options['readPreference']) && ! $options['readPreference'] instanceof ReadPreference) {
  75              throw InvalidArgumentException::invalidType('"readPreference" option', $options['readPreference'], ReadPreference::class);
  76          }
  77  
  78          if (isset($options['session']) && ! $options['session'] instanceof Session) {
  79              throw InvalidArgumentException::invalidType('"session" option', $options['session'], Session::class);
  80          }
  81  
  82          if (isset($options['typeMap']) && ! is_array($options['typeMap'])) {
  83              throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array');
  84          }
  85  
  86          $this->databaseName = $databaseName;
  87          $this->command = $command instanceof Command ? $command : new Command($command);
  88          $this->options = $options;
  89      }
  90  
  91      /**
  92       * Execute the operation.
  93       *
  94       * @see Executable::execute()
  95       * @return Cursor
  96       */
  97      public function execute(Server $server)
  98      {
  99          $cursor = $server->executeCommand($this->databaseName, $this->command, $this->createOptions());
 100  
 101          if (isset($this->options['typeMap'])) {
 102              $cursor->setTypeMap($this->options['typeMap']);
 103          }
 104  
 105          return $cursor;
 106      }
 107  
 108      /**
 109       * Create options for executing the command.
 110       *
 111       * @see https://php.net/manual/en/mongodb-driver-server.executecommand.php
 112       */
 113      private function createOptions(): array
 114      {
 115          $options = [];
 116  
 117          if (isset($this->options['readPreference'])) {
 118              $options['readPreference'] = $this->options['readPreference'];
 119          }
 120  
 121          if (isset($this->options['session'])) {
 122              $options['session'] = $this->options['session'];
 123          }
 124  
 125          return $options;
 126      }
 127  }