[Summary view]

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