PHPLIB-659 Support options for time-series collections (#829)

* PHPLIB-659 Support options for time-series collections

* Update wording about 5.0 support

Author: alcaeus

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

@@ -35,6 +35,21 @@ pre: |
   </reference/bson-type-comparison-order/#collation>` for the collection.
 ---
 arg_name: option
+name: expireAfterSeconds
+type: integer
+description: |
+  Allows specifying a TTL after which documents will be removed from a
+  time-series collection.
+
+  This option is available in MongoDB 5.0+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.9
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: flags
 type: integer
 description: |
@@ -133,6 +148,20 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
+arg_name: option
+name: timeseries
+type: array|object
+description: |
+  Allows users to specify options for time-series collections.
+
+  This option is available in MongoDB 5.0+ and will result in an exception at
+  execution time if specified for an older server version.
+
+  .. versionadded:: 1.9
+interface: phpmethod
+operation: ~
+optional: true
+---
 source:
   file: apiargs-MongoDBDatabase-common-option.yaml
   ref: typeMap

src/Operation/CreateCollection.php

@@ -82,6 +82,10 @@ class CreateCollection implements Executable
      *    This is not supported for server versions < 3.4 and will result in an
      *    exception at execution time if used.
      *
+     *  * expireAfterSeconds: The TTL for documents in time series collections.
+     *
+     *    This is not supported for servers versions < 5.0.
+     *
      *  * flags (integer): Options for the MMAPv1 storage engine only. Must be a
      *    bitwise combination CreateCollection::USE_POWER_OF_2_SIZES and
      *    CreateCollection::NO_PADDING. The default is
@@ -104,6 +108,10 @@ class CreateCollection implements Executable
      *
      *  * storageEngine (document): Storage engine options.
      *
+     *  * timeseries (document): Options for time series collections.
+     *
+     *    This is not supported for servers versions < 5.0.
+     *
      *  * typeMap (array): Type map for BSON deserialization. This will only be
      *    used for the returned command result document.
      *
@@ -139,6 +147,10 @@ public function __construct($databaseName, $collectionName, array $options = [])
             throw InvalidArgumentException::invalidType('"collation" option', $options['collation'], 'array or object');
         }
 
+        if (isset($options['expireAfterSeconds']) && ! is_integer($options['expireAfterSeconds'])) {
+            throw InvalidArgumentException::invalidType('"expireAfterSeconds" option', $options['expireAfterSeconds'], 'integer');
+        }
+
         if (isset($options['flags']) && ! is_integer($options['flags'])) {
             throw InvalidArgumentException::invalidType('"flags" option', $options['flags'], 'integer');
         }
@@ -167,6 +179,10 @@ public function __construct($databaseName, $collectionName, array $options = [])
             throw InvalidArgumentException::invalidType('"storageEngine" option', $options['storageEngine'], 'array or object');
         }
 
+        if (isset($options['timeseries']) && ! is_array($options['timeseries']) && ! is_object($options['timeseries'])) {
+            throw InvalidArgumentException::invalidType('"timeseries" option', $options['timeseries'], ['array', 'object']);
+        }
+
         if (isset($options['typeMap']) && ! is_array($options['typeMap'])) {
             throw InvalidArgumentException::invalidType('"typeMap" option', $options['typeMap'], 'array');
         }
@@ -237,13 +253,13 @@ private function createCommand()
     {
         $cmd = ['create' => $this->collectionName];
 
-        foreach (['autoIndexId', 'capped', 'flags', 'max', 'maxTimeMS', 'size', 'validationAction', 'validationLevel'] as $option) {
+        foreach (['autoIndexId', 'capped', 'expireAfterSeconds', 'flags', 'max', 'maxTimeMS', 'size', 'validationAction', 'validationLevel'] as $option) {
             if (isset($this->options[$option])) {
                 $cmd[$option] = $this->options[$option];
             }
         }
 
-        foreach (['collation', 'indexOptionDefaults', 'storageEngine', 'validator'] as $option) {
+        foreach (['collation', 'indexOptionDefaults', 'storageEngine', 'timeseries', 'validator'] as $option) {
             if (isset($this->options[$option])) {
                 $cmd[$option] = (object) $this->options[$option];
             }

tests/Operation/CreateCollectionTest.php

@@ -32,6 +32,10 @@ public function provideInvalidConstructorOptions()
             $options[][] = ['collation' => $value];
         }
 
+        foreach ($this->getInvalidIntegerValues() as $value) {
+            $options[][] = ['expireAfterSeconds' => $value];
+        }
+
         foreach ($this->getInvalidIntegerValues() as $value) {
             $options[][] = ['flags' => $value];
         }
@@ -60,6 +64,10 @@ public function provideInvalidConstructorOptions()
             $options[][] = ['storageEngine' => $value];
         }
 
+        foreach ($this->getInvalidDocumentValues() as $value) {
+            $options[][] = ['timeseries' => $value];
+        }
+
         foreach ($this->getInvalidArrayValues() as $value) {
             $options[][] = ['typeMap' => $value];
         }

tests/UnifiedSpecTests/UnifiedSpecTest.php

@@ -141,6 +141,19 @@ public function provideChangeStreamsTests()
         return $this->provideTests(__DIR__ . '/change-streams/*.json');
     }
 
+    /**
+     * @dataProvider provideCollectionManagementTests
+     */
+    public function testCollectionManagement(UnifiedTestCase $test)
+    {
+        self::$runner->run($test);
+    }
+
+    public function provideCollectionManagementTests()
+    {
+        return $this->provideTests(__DIR__ . '/collection-management/*.json');
+    }
+
     /**
      * @dataProvider provideCrudTests
      */