From c26c53aec6f52e4fec9a3e666214bb7548f0ad9d Mon Sep 17 00:00:00 2001
From: Derick Rethans <derick@php.net>
Date: Fri, 22 Jun 2018 16:19:51 +0000
Subject: [PATCH] Add (basic) documentation for MongoDB 4.0+ transactions.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@345182 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mongodb/driver/manager/startsession.xml   |  59 +++++++++
 .../driver/session/aborttransaction.xml       |  73 +++++++++++
 .../driver/session/committransaction.xml      |  80 ++++++++++++
 .../mongodb/driver/session/endsession.xml     |  73 +++++++++++
 .../driver/session/starttransaction.xml       | 116 ++++++++++++++++++
 reference/mongodb/versions.xml                |   4 +
 6 files changed, 405 insertions(+)
 create mode 100644 reference/mongodb/mongodb/driver/session/aborttransaction.xml
 create mode 100644 reference/mongodb/mongodb/driver/session/committransaction.xml
 create mode 100644 reference/mongodb/mongodb/driver/session/endsession.xml
 create mode 100644 reference/mongodb/mongodb/driver/session/starttransaction.xml

diff --git a/reference/mongodb/mongodb/driver/manager/startsession.xml b/reference/mongodb/mongodb/driver/manager/startsession.xml
index 1153bc42dd..5d32657e1d 100644
--- a/reference/mongodb/mongodb/driver/manager/startsession.xml
+++ b/reference/mongodb/mongodb/driver/manager/startsession.xml
@@ -62,6 +62,40 @@
           </entry>
           <entry>&true;</entry>
          </row>
+         <row>
+          <entry>defaultTransactionOptions</entry>
+          <entry><type>array</type></entry>
+          <entry>
+           <para>
+            Default options to apply to newly created transactions. These
+            options are used unless they are overridden when a transaction is
+            started with different value for each option.
+           </para>
+           <para>
+            <table>
+             <title>options</title>
+             <tgroup cols="3">
+              <thead>
+               <row>
+                <entry>Option</entry>
+                <entry>Type</entry>
+                <entry>Description</entry>
+               </row>
+              </thead>
+              <tbody>
+               &mongodb.option.readConcern;
+               &mongodb.option.readPreference;
+               &mongodb.option.writeConcern;
+              </tbody>
+             </tgroup>
+            </table>
+           </para>
+           <para>
+            This option is available in MongoDB 4.0+.
+           </para>
+          </entry>
+          <entry></entry>
+         </row>
         </tbody>
        </tgroup>
       </table>
@@ -86,6 +120,31 @@
   </simplelist>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>1.5.0</entry>
+       <entry>
+        <para>
+         The <literal>"defaultTransactionOptions"</literal> option was added.
+        </para>
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
diff --git a/reference/mongodb/mongodb/driver/session/aborttransaction.xml b/reference/mongodb/mongodb/driver/session/aborttransaction.xml
new file mode 100644
index 0000000000..e1a0ac04eb
--- /dev/null
+++ b/reference/mongodb/mongodb/driver/session/aborttransaction.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 344522 $ --> 
+
+<refentry xml:id="mongodb-driver-session.aborttransaction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoDB\Driver\Session::abortTransaction</refname>
+  <refpurpose>Aborts a transaction</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>final</modifier> <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\Session::abortTransaction</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   This method aborts an existing transaction and all the associated
+   operations are rolled back. It is like all operations that were part of
+   this transaction never existed.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simplelist>
+   &mongodb.throws.argumentparsing;
+   <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> if the the transaction could not be aborted (e.g. a transaction was not started).</member>
+  </simplelist>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>MongoDB\Driver\Manager::startSession</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::commitTransaction</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::startTransaction</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongodb/mongodb/driver/session/committransaction.xml b/reference/mongodb/mongodb/driver/session/committransaction.xml
new file mode 100644
index 0000000000..b731047d20
--- /dev/null
+++ b/reference/mongodb/mongodb/driver/session/committransaction.xml
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 344522 $ --> 
+
+<refentry xml:id="mongodb-driver-session.committransaction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoDB\Driver\Session::commitTransaction</refname>
+  <refpurpose>Commits a transaction</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>final</modifier> <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\Session::commitTransaction</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   This method commits an existing transaction and all the associated
+   operations are persisted in the database.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simplelist>
+   &mongodb.throws.argumentparsing;
+   <member>Throws
+   <classname>MongoDB\Driver\Exception\CommandException</classname> if the
+   server could not commit the transaction (e.g. due to conflicts, network
+   issues). In case the exception's
+   <methodname>MongoDB\Driver\Exception\CommandException::getResultDocument</methodname>
+   has a <literal>"errorLabels"</literal> element, and this array contains a
+   <literal>"TransientTransactionError"</literal> value, it is safe to re-try
+   the <emphasis>whole</emphasis> transaction.</member>
+   <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> if the transaction could not be commited (e.g. a transaction was not started).</member>
+  </simplelist>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>MongoDB\Driver\Manager::startSession</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::commitTransaction</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::startTransaction</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongodb/mongodb/driver/session/endsession.xml b/reference/mongodb/mongodb/driver/session/endsession.xml
new file mode 100644
index 0000000000..96fec21057
--- /dev/null
+++ b/reference/mongodb/mongodb/driver/session/endsession.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 344522 $ --> 
+
+<refentry xml:id="mongodb-driver-session.endsession" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoDB\Driver\Session::endSession</refname>
+  <refpurpose>Terminates a session</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>final</modifier> <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\Session::endSession</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   This method closes an existing session. If a transaction was associated
+   with this session, this transaction is also aborted, and all its
+   operations are rolled back.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simplelist>
+   &mongodb.throws.argumentparsing;
+  </simplelist>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>MongoDB\Driver\Manager::startSession</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::abortTransaction</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::commitTransaction</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::startTransaction</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongodb/mongodb/driver/session/starttransaction.xml b/reference/mongodb/mongodb/driver/session/starttransaction.xml
new file mode 100644
index 0000000000..09bc01fec7
--- /dev/null
+++ b/reference/mongodb/mongodb/driver/session/starttransaction.xml
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 344522 $ --> 
+
+<refentry xml:id="mongodb-driver-session.starttransaction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>MongoDB\Driver\Session::startTransaction</refname>
+  <refpurpose>Starts a transaction</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>final</modifier> <modifier>public</modifier> <type>void</type><methodname>MongoDB\Driver\Session::startTransaction</methodname>
+   <methodparam><type>array|object</type><parameter>options</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   This method starts a new transaction within this session. When the session
+   is attached to operations through the <literal>"session"</literal>
+   argument, these operations become of the started transaction.
+  </para>
+  <para>
+   Transactions can be committed through
+   <methodname>MongoDB\Driver\Session::commitTransaction</methodname>, and
+   aborted with
+   <methodname>MongoDB\Driver\Session::abortTransaction</methodname>.
+  </para>
+  <para>
+   Transactions are also automatically aborted when the session is terminated
+   through <methodname>MongoDB\Driver\Session::endSession</methodname>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>options</parameter></term>
+    <listitem>
+     <para>
+      Options can be passed as argument to this method. Each element in this
+      options array overrides the corresponding option from the
+      <literal>"defaultTransactionOptions"</literal> option, if set when
+      starting the session with
+      <methodname>MongoDB\Driver\Manager::startSession</methodname>.
+     </para>
+     <para>
+      <table>
+       <title>options</title>
+       <tgroup cols="4">
+        <thead>
+         <row>
+          <entry>Option</entry>
+          <entry>Type</entry>
+          <entry>Description</entry>
+         </row>
+        </thead>
+        <tbody>
+         &mongodb.option.readConcern;
+         &mongodb.option.readPreference;
+         &mongodb.option.writeConcern;
+        </tbody>
+       </tgroup>
+      </table>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simplelist>
+   &mongodb.throws.argumentparsing;
+   <member>Throws <classname>MongoDB\Driver\Exception\CommandException</classname> if the the transaction could not be started because of a server-side problem (e.g. a lock could not be obtained).</member>
+   <member>Throws <classname>MongoDB\Driver\Exception\RuntimeException</classname> if the the transaction could not be started (e.g. a transaction was already started).</member>
+  </simplelist>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>MongoDB\Driver\Manager::startSession</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::commitTransaction</methodname></member>
+   <member><methodname>MongoDB\Driver\Session::abortTransaction</methodname></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/mongodb/versions.xml b/reference/mongodb/versions.xml
index 07e9232780..5e8a91d819 100644
--- a/reference/mongodb/versions.xml
+++ b/reference/mongodb/versions.xml
@@ -87,11 +87,15 @@
 
  <function name='mongodb\driver\session' from='mongodb &gt;=1.4.0'/>
  <function name='mongodb\driver\session::__construct' from='mongodb &gt;=1.4.0'/>
+ <function name='mongodb\driver\session::aborttransaction' from='mongodb &gt;=1.5.0'/>
  <function name='mongodb\driver\session::advanceclustertime' from='mongodb &gt;=1.4.0'/>
  <function name='mongodb\driver\session::advanceoperationtime' from='mongodb &gt;=1.4.0'/>
+ <function name='mongodb\driver\session::committransaction' from='mongodb &gt;=1.5.0'/>
+ <function name='mongodb\driver\session::endsession' from='mongodb &gt;=1.5.0'/>
  <function name='mongodb\driver\session::getclustertime' from='mongodb &gt;=1.4.0'/>
  <function name='mongodb\driver\session::getlogicalsessionid' from='mongodb &gt;=1.4.0'/>
  <function name='mongodb\driver\session::getoperationtime' from='mongodb &gt;=1.4.0'/>
+ <function name='mongodb\driver\session::starttransaction' from='mongodb &gt;=1.5.0'/>
 
  <function name='mongodb\driver\bulkwrite' from='mongodb &gt;=1.0.0'/>
  <function name='mongodb\driver\bulkwrite::__construct' from='mongodb &gt;=1.0.0'/>