Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
   1  <?php
   2  /*
   3   * Copyright 2021-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\Exception\RuntimeException as DriverRuntimeException;
  22  use MongoDB\Driver\Server;
  23  use MongoDB\Driver\Session;
  24  use MongoDB\Driver\WriteConcern;
  25  use MongoDB\Exception\InvalidArgumentException;
  26  use MongoDB\Exception\UnsupportedException;
  27  
  28  use function current;
  29  use function is_array;
  30  use function is_bool;
  31  
  32  /**
  33   * Operation for the renameCollection command.
  34   *
  35   * @api
  36   * @see \MongoDB\Collection::rename()
  37   * @see \MongoDB\Database::renameCollection()
  38   * @see https://mongodb.com/docs/manual/reference/command/renameCollection/
  39   */
  40  class RenameCollection implements Executable
  41  {
  42      /** @var string */
  43      private $fromNamespace;
  44  
  45      /** @var string */
  46      private $toNamespace;
  47  
  48      /** @var array */
  49      private $options;
  50  
  51      /**
  52       * Constructs a renameCollection command.
  53       *
  54       * Supported options:
  55       *
  56       *  * comment (mixed): BSON value to attach as a comment to this command.
  57       *
  58       *    This is not supported for servers versions < 4.4.
  59       *
  60       *  * session (MongoDB\Driver\Session): Client session.
  61       *
  62       *  * typeMap (array): Type map for BSON deserialization. This will be used
  63       *    for the returned command result document.
  64       *
  65       *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.
  66       *
  67       *  * dropTarget (boolean): If true, MongoDB will drop the target before
  68       *    renaming the collection.
  69       *
  70       * @param string $fromDatabaseName   Database name
  71       * @param string $fromCollectionName Collection name
  72       * @param string $toDatabaseName     New database name
  73       * @param string $toCollectionName   New collection name
  74       * @param array  $options            Command options
  75       * @throws InvalidArgumentException for parameter/option parsing errors
  76       */
  77      public function __construct(string $fromDatabaseName, string $fromCollectionName, string $toDatabaseName, string $toCollectionName, array $options = [])
  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          if (isset($options['writeConcern']) && ! $options['writeConcern'] instanceof WriteConcern) {
  88              throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], WriteConcern::class);
  89          }
  90  
  91          if (isset($options['writeConcern']) && $options['writeConcern']->isDefault()) {
  92              unset($options['writeConcern']);
  93          }
  94  
  95          if (isset($options['dropTarget']) && ! is_bool($options['dropTarget'])) {
  96              throw InvalidArgumentException::invalidType('"dropTarget" option', $options['dropTarget'], 'boolean');
  97          }
  98  
  99          $this->fromNamespace = $fromDatabaseName . '.' . $fromCollectionName;
 100          $this->toNamespace = $toDatabaseName . '.' . $toCollectionName;
 101          $this->options = $options;
 102      }
 103  
 104      /**
 105       * Execute the operation.
 106       *
 107       * @see Executable::execute()
 108       * @return array|object Command result document
 109       * @throws UnsupportedException if write concern is used and unsupported
 110       * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
 111       */
 112      public function execute(Server $server)
 113      {
 114          $inTransaction = isset($this->options['session']) && $this->options['session']->isInTransaction();
 115          if ($inTransaction && isset($this->options['writeConcern'])) {
 116              throw UnsupportedException::writeConcernNotSupportedInTransaction();
 117          }
 118  
 119          $cursor = $server->executeWriteCommand('admin', $this->createCommand(), $this->createOptions());
 120  
 121          if (isset($this->options['typeMap'])) {
 122              $cursor->setTypeMap($this->options['typeMap']);
 123          }
 124  
 125          return current($cursor->toArray());
 126      }
 127  
 128      /**
 129       * Create the renameCollection command.
 130       */
 131      private function createCommand(): Command
 132      {
 133          $cmd = [
 134              'renameCollection' => $this->fromNamespace,
 135              'to' => $this->toNamespace,
 136          ];
 137  
 138          foreach (['comment', 'dropTarget'] as $option) {
 139              if (isset($this->options[$option])) {
 140                  $cmd[$option] = $this->options[$option];
 141              }
 142          }
 143  
 144          return new Command($cmd);
 145      }
 146  
 147      /**
 148       * Create options for executing the command.
 149       *
 150       * @see https://php.net/manual/en/mongodb-driver-server.executewritecommand.php
 151       */
 152      private function createOptions(): array
 153      {
 154          $options = [];
 155  
 156          if (isset($this->options['session'])) {
 157              $options['session'] = $this->options['session'];
 158          }
 159  
 160          if (isset($this->options['writeConcern'])) {
 161              $options['writeConcern'] = $this->options['writeConcern'];
 162          }
 163  
 164          return $options;
 165      }
 166  }