Merge pull request #477

Author: kvwalker

docs/includes/apiargs-MongoDBClient-method-startSession-option.yaml

@@ -0,0 +1,12 @@
+arg_name: option
+name: causalConsistency
+type: boolean
+description: |
+  Enables or disables :ref:`causal consistency <causal-consistency>` for the
+  session. If true, each operation in the session will be causally ordered after
+  the previous read or write operation. Set to false to disable causal
+  consistency. Defaults to true.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/reference/class/MongoDBClient.txt

@@ -39,3 +39,4 @@ Methods
    /reference/method/MongoDBClient-listDatabases
    /reference/method/MongoDBClient-selectCollection
    /reference/method/MongoDBClient-selectDatabase
+   /reference/method/MongoDBClient-startSession

docs/reference/method/MongoDBClient-startSession.txt

@@ -0,0 +1,82 @@
+===============================
+MongoDB\\Client::startSession()
+===============================
+
+.. default-domain:: mongodb
+
+.. versionadded:: 1.3
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Client::startSession()
+
+   Start a new client session for use with this client.
+
+   .. code-block:: php
+
+      function startSession(array $options = []): MongoDB\Driver\Session
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBClient-method-startSession-option.rst
+
+Return Values
+-------------
+
+A :php:`MongoDB\Driver\Session <mongodb-driver-session>`
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-driver-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Example
+-------
+
+The following example starts a new session:
+
+.. code-block:: php
+
+   <?php
+
+   $client = new MongoDB\Client;
+
+   $session = $client->startSession();
+
+   var_dump($session);
+
+The output would then resemble::
+
+   object(MongoDB\Driver\Session)#2043 (4) {
+     ["logicalSessionId"]=>
+     array(1) {
+       ["id"]=>
+       object(MongoDB\BSON\Binary)#225 (2) {
+         ["data"]=>
+         string(16) "................"
+         ["type"]=>
+         int(4)
+       }
+     }
+     ["clusterTime"]=>
+     NULL
+     ["causalConsistency"]=>
+     bool(true)
+     ["operationTime"]=>
+     NULL
+   }
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\Manager::startSession()
+  <manual/en/mongodb-driver-manager.startsession.php>`
+- :ref:`Causal Consistency <causal-consistency>` in the MongoDB manual

src/Client.php

@@ -256,4 +256,16 @@ public function selectDatabase($databaseName, array $options = [])
 
         return new Database($this->manager, $databaseName, $options);
     }
+
+    /**
+     * Start a new client session.
+     *
+     * @see http://php.net/manual/en/mongodb-driver-manager.startsession.php
+     * @param array  $options      Session options
+     * @return MongoDB\Driver\Session
+     */
+    public function startSession(array $options = [])
+    {
+        return $this->manager->startSession($options);
+    }
 }

tests/ClientFunctionalTest.php

@@ -97,4 +97,12 @@ private function assertDatabaseExists($databaseName, $callback = null)
             call_user_func($callback, $foundDatabase);
         }
     }
+
+    public function testStartSession()
+    {
+        if (version_compare($this->getFeatureCompatibilityVersion(), '3.6', '<')) {
+            $this->markTestSkipped('startSession() is only supported on FCV 3.6 or higher');
+        }
+        $this->assertInstanceOf('MongoDB\Driver\Session', $this->client->startSession());
+    }
 }