Merge pull request #513

docs/includes/apiargs-MongoDBDatabase-method-modifyCollection-option.yaml

+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: typeMap
+post: |
+  This will be used for the returned command result document.
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: writeConcern
+...

docs/includes/apiargs-MongoDBDatabase-method-modifyCollection-param.yaml

+source:
+  file: apiargs-common-param.yaml
+  ref: $collectionName
+replacement:
+  subject: "collection or view"
+  action: " to modify"
+---
+arg_name: param
+name: $collectionOptions
+type: array
+description: |
+  Collection or view options to assign.
+interface: phpmethod
+operation: ~
+optional: false
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/includes/apiargs-common-param.yaml

@@ -23,11 +23,12 @@ arg_name: param
 name: $collectionName
 type: string
 description: |
-  The name of the collection{{action}}.
+  The name of the {{subject}}{{action}}.
 interface: phpmethod
 operation: ~
 optional: false
 replacement:
+  subject: "collection"
   action: ""
 ---
 arg_name: param

docs/reference/class/MongoDBDatabase.txt

@@ -56,6 +56,7 @@ Methods
    /reference/method/MongoDBDatabase-getTypeMap
    /reference/method/MongoDBDatabase-getWriteConcern
    /reference/method/MongoDBDatabase-listCollections
+   /reference/method/MongoDBDatabase-modifyCollection
    /reference/method/MongoDBDatabase-selectCollection
    /reference/method/MongoDBDatabase-selectGridFSBucket
    /reference/method/MongoDBDatabase-withOptions

docs/reference/method/MongoDBDatabase-modifyCollection.txt

+=====================================
+MongoDB\\Database::modifyCollection()
+=====================================
+
+.. versionadded:: 1.4
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Database::modifyCollection()
+
+   Modifies a collection or view according to the specified
+   ``$collectionOptions``.
+
+   .. code-block:: php
+
+      function modifyCollection($collectionName, array $collectionOptions, array $options = []): array|object
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-modifyCollection-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-modifyCollection-option.rst
+
+Return Values
+-------------
+
+An array or object with the result document of the :manual:`collMod
+</reference/command/collMod>` command.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Example
+-------
+
+The following example changes the expiration time of a TTL collection in the
+``test`` database:
+
+.. code-block:: php
+
+   <?php
+
+   $db = (new MongoDB\Client)->test;
+
+   $result = $db->modifyCollection('users', [
+       'keyPattern' => ['lastAccess' => 1],
+       'expireAfterSeconds' => 1000
+   ]);
+
+   var_dump($result);
+
+The output would then resemble::
+
+   object(stdClass)#2779 {
+     ["expireAfterSeconds_old"]=>
+     int(3)
+     ["expireAfterSeconds_new"]=>
+     int(1000)
+     ["ok"]=>
+     float(1)
+   }
+
+See Also
+--------
+
+- :manual:`collMod </reference/command/collMod>` command reference in the MongoDB
+  manual

src/Database.php

@@ -33,6 +33,7 @@ use MongoDB\Operation\DatabaseCommand;
 use MongoDB\Operation\DropCollection;
 use MongoDB\Operation\DropDatabase;
 use MongoDB\Operation\ListCollections;
+use MongoDB\Operation\ModifyCollection;
 
 class Database
 {
@@ -340,6 +341,33 @@ class Database
         return $operation->execute($server);
     }
 
+    /**
+     * Modifies a collection or view.
+     *
+     * @see ModifyCollection::__construct() for supported options
+     * @param string $collectionName    Collection or view to modify
+     * @param array  $collectionOptions Collection or view options to assign
+     * @param array  $options           Command options
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
+     */
+    public function modifyCollection($collectionName, array $collectionOptions, array $options = [])
+    {
+        if ( ! isset($options['typeMap'])) {
+            $options['typeMap'] = $this->typeMap;
+        }
+
+        $server = $this->manager->selectServer(new ReadPreference(ReadPreference::RP_PRIMARY));
+
+        if ( ! isset($options['writeConcern']) && \MongoDB\server_supports_feature($server, self::$wireVersionForWritableCommandWriteConcern)) {
+            $options['writeConcern'] = $this->writeConcern;
+        }
+
+        $operation = new ModifyCollection($this->databaseName, $collectionName, $collectionOptions, $options);
+
+        return $operation->execute($server);
+    }
+
     /**
      * Select a collection within this database.
      *

src/Operation/ModifyCollection.php

+<?php
+/*
+ * Copyright 2018 MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Operation;
+
+use MongoDB\Driver\Command;
+use MongoDB\Driver\Server;
+use MongoDB\Driver\Session;
+use MongoDB\Driver\WriteConcern;
+use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Exception\InvalidArgumentException;
+
+/**
+ * Operation for the collMod command.
+ *
+ * @api
+ * @see \MongoDB\Database::modifyCollection()
+ * @see http://docs.mongodb.org/manual/reference/command/collMod/
+ */
+class ModifyCollection implements Executable
+{
+    private $databaseName;
+    private $collectionName;
+    private $collectionOptions;
+    private $options;
+
+    /**
+     * Constructs a collMod command.
+     *
+     * Supported options:
+     *
+     *  * session (MongoDB\Driver\Session): Client session.
+     *
+     *    Sessions are not supported for server versions < 3.6.
+     *
+     *  * typeMap (array): Type map for BSON deserialization. This will only be
+     *    used for the returned command result document.
+     *
+     *  * writeConcern (MongoDB\Driver\WriteConcern): Write concern.
+     *
+     *    This is not supported for server versions < 3.2 and will result in an
+     *    exception at execution time if used.
+     *
+     * @param string       $databaseName      Database name
+     * @param string       $collectionName    Collection or view to modify
+     * @param string       $collectionOptions Collection or view options to assign
+     * @param array        $options           Command options
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     */
+    public function __construct($databaseName, $collectionName, array $collectionOptions, array $options = [])
+    {
+        if (empty($collectionOptions)) {
+            throw new InvalidArgumentException('$collectionOptions is empty');
+        }
+
+        if (isset($options['session']) && ! $options['session'] instanceof Session) {
+            throw InvalidArgumentException::invalidType('"session" option', $options['session'], 'MongoDB\Driver\Session');
+        }
+
+        if (isset($options['typeMap']) && ! is_array($options['typeMap'])) {
+            throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array');
+        }
+
+        if (isset($options['writeConcern']) && ! $options['writeConcern'] instanceof WriteConcern) {
+            throw InvalidArgumentException::invalidType('"writeConcern" option', $options['writeConcern'], 'MongoDB\Driver\WriteConcern');
+        }
+
+        if (isset($options['writeConcern']) && $options['writeConcern']->isDefault()) {
+            unset($options['writeConcern']);
+        }
+
+        $this->databaseName = (string) $databaseName;
+        $this->collectionName = (string) $collectionName;
+        $this->collectionOptions = $collectionOptions;
+        $this->options = $options;
+    }
+
+    /**
+     * Execute the operation.
+     *
+     * @see Executable::execute()
+     * @param Server $server
+     * @return array|object Command result document
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
+     */
+    public function execute(Server $server)
+    {
+        if (isset($this->options['writeConcern']) && ! \MongoDB\server_supports_feature($server, self::$wireVersionForWriteConcern)) {
+            throw UnsupportedException::writeConcernNotSupported();
+        }
+
+        $cursor = $server->executeWriteCommand($this->databaseName, new Command(['collMod' => $this->collectionName] + $this->collectionOptions), $this->createOptions());
+
+        if (isset($this->options['typeMap'])) {
+            $cursor->setTypeMap($this->options['typeMap']);
+        }
+
+        return current($cursor->toArray());
+    }
+
+    /**
+     * Create options for executing the command.
+     *
+     * @see http://php.net/manual/en/mongodb-driver-server.executereadwritecommand.php
+     * @return array
+     */
+    private function createOptions()
+    {
+        $options = [];
+
+        if (isset($this->options['session'])) {
+            $options['session'] = $this->options['session'];
+        }
+
+        if (isset($this->options['writeConcern'])) {
+            $options['writeConcern'] = $this->options['writeConcern'];
+        }
+
+        return $options;
+    }
+}

tests/Database/DatabaseFunctionalTest.php

@@ -8,6 +8,7 @@ use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Operation\CreateIndexes;
 
 /**
  * Functional tests for the Database class.
@@ -152,6 +153,22 @@ class DatabaseFunctionalTest extends FunctionalTestCase
         $this->assertSame(WriteConcern::MAJORITY, $debug['writeConcern']->getW());
     }
 
+    public function testModifyCollection()
+    {
+        $this->database->createCollection($this->getCollectionName());
+
+        $indexes = [['key' => ['lastAccess' => 1], 'expireAfterSeconds' => 3]];
+        $createIndexes = new CreateIndexes($this->getDatabaseName(), $this->getCollectionName(), $indexes);
+        $createIndexes->execute($this->getPrimaryServer());
+
+        $commandResult = $this->database->modifyCollection($this->getCollectionName(), ['index' => ['keyPattern' => ['lastAccess' => 1], 'expireAfterSeconds' => 1000]]);
+
+        $this->assertCommandSucceeded($commandResult);
+        $this->assertSame(3, $commandResult['expireAfterSeconds_old']);
+        $this->assertSame(1000, $commandResult['expireAfterSeconds_new']);
+    }
+
+
     public function testSelectCollectionInheritsOptions()
     {
         $databaseOptions = [

tests/Operation/ModifyCollectionFunctionalTest.php

+<?php
+
+namespace MongoDB\Tests\Operation;
+
+use MongoDB\Operation\ModifyCollection;
+use MongoDB\Operation\CreateCollection;
+use MongoDB\Operation\CreateIndexes;
+
+class ModifyCollectionFunctionalTest extends FunctionalTestCase
+{
+    public function testCollMod()
+    {
+        $operation = new CreateCollection($this->getDatabaseName(), $this->getCollectionName());
+        $operation->execute($this->getPrimaryServer());
+
+        $indexes = [['key' => ['lastAccess' => 1], 'expireAfterSeconds' => 3]];
+        $createIndexes = new CreateIndexes($this->getDatabaseName(), $this->getCollectionName(), $indexes);
+        $createIndexes->execute($this->getPrimaryServer());
+
+        $modifyCollection = new ModifyCollection(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            ['index' => ['keyPattern' => ['lastAccess' => 1], 'expireAfterSeconds' => 1000]],
+            ['typeMap' => ['root' => 'array']]
+        );
+        $result = $modifyCollection->execute($this->getPrimaryServer());
+
+        $this->assertSame(3, $result['expireAfterSeconds_old']);
+        $this->assertSame(1000, $result['expireAfterSeconds_new']);
+    }
+}

tests/Operation/ModifyCollectionTest.php

+<?php
+
+namespace MongoDB\Tests\Operation;
+
+use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Operation\ModifyCollection;
+
+class ModifyCollectionTest extends TestCase
+{
+    public function testConstructorEmptyCollectionOptions()
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('$collectionOptions is empty');
+        new ModifyCollection($this->getDatabaseName(), $this->getCollectionName(), []);
+    }
+
+    /**
+     * @dataProvider provideInvalidConstructorOptions
+     */
+    public function testConstructorOptionTypeChecks(array $options)
+    {
+        $this->expectException(InvalidArgumentException::class);
+        new ModifyCollection($this->getDatabaseName(), $this->getCollectionName(), [], $options);
+    }
+
+    public function provideInvalidConstructorOptions()
+    {
+        $options = [];
+
+        foreach ($this->getInvalidSessionValues() as $value) {
+            $options[][] = ['session' => $value];
+        }
+
+        foreach ($this->getInvalidArrayValues() as $value) {
+            $options[][] = ['typeMap' => $value];
+        }
+
+        foreach ($this->getInvalidWriteConcernValues() as $value) {
+            $options[][] = ['writeConcern' => $value];
+        }
+
+        return $options;
+    }
+}