From 3742d36be1e1d0d9249ce7e093f4f05ead85b8e8 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Fri, 30 Oct 2020 15:45:26 +0000
Subject: [PATCH] Improve transaction examples for mysqli

A correct example was provided in begin_transaction() and commit()
& rollback are linked. For autocommit the example was expanded to
show how one can use autocommit to create transactions. This
should also clarify the behaviour of commit in regards to
autocommit. A note section was copied from autocommit doc to the
other three.

Also added simple description of SAVEPOINT and RELEASE SAVEPOINT.

Patch contributed by Dharman <tekiela246@gmail.com>.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351087 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqli/mysqli/autocommit.xml        | 137 ++++++++++++++----
 reference/mysqli/mysqli/begin-transaction.xml | 100 +++++++++----
 reference/mysqli/mysqli/commit.xml            |  83 ++---------
 reference/mysqli/mysqli/release-savepoint.xml |  11 +-
 reference/mysqli/mysqli/rollback.xml          | 121 ++--------------
 reference/mysqli/mysqli/savepoint.xml         |  10 +-
 6 files changed, 217 insertions(+), 245 deletions(-)

diff --git a/reference/mysqli/mysqli/autocommit.xml b/reference/mysqli/mysqli/autocommit.xml
index 329592254e..822bc7a1c3 100644
--- a/reference/mysqli/mysqli/autocommit.xml
+++ b/reference/mysqli/mysqli/autocommit.xml
@@ -57,7 +57,7 @@
   &reftitle.notes;
   <note>
    <para>
-    This function doesn't work with non transactional table types (like
+    This function does not work with non transactional table types (like
     MyISAM or ISAM).
    </para>
   </note>
@@ -71,56 +71,139 @@
    <programlisting role="php">
 <![CDATA[
 <?php
+
+/* Tell mysqli to throw an exception if an error occurs */
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+
 $mysqli = new mysqli("localhost", "my_user", "my_password", "world");
 
-if (mysqli_connect_errno()) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
-}
+/* The table engine has to support transactions */
+$mysqli->query("CREATE TABLE IF NOT EXISTS language (
+    Code text NOT NULL,
+    Speakers int(11) NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
 
-/* turn autocommit on */
-$mysqli->autocommit(TRUE);
+/* Turn autocommit off */
+$mysqli->autocommit(false);
 
-if ($result = $mysqli->query("SELECT @@autocommit")) {
+$result = $mysqli->query("SELECT @@autocommit");
+$row = $result->fetch_row();
+printf("Autocommit is %s\n", $row[0]);
+
+try {
+    /* Prepare insert statement */
+    $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
+    $stmt->bind_param('ss', $language_code, $native_speakers);
+
+    /* Insert some values */
+    $language_code = 'DE';
+    $native_speakers = 50_123_456;
+    $stmt->execute();
+    $language_code = 'FR';
+    $native_speakers = 40_546_321;
+    $stmt->execute();
+
+    /* Commit the data in the database. This doesn't set autocommit=true */
+    $mysqli->commit();
+    print "Committed 2 rows in the database\n";
+
+    $result = $mysqli->query("SELECT @@autocommit");
     $row = $result->fetch_row();
     printf("Autocommit is %s\n", $row[0]);
-    $result->free();
-}
 
-/* close connection */
-$mysqli->close();
-?>
+    /* Try to insert more values */
+    $language_code = 'PL';
+    $native_speakers = 30_555_444;
+    $stmt->execute();
+    $language_code = 'DK';
+    $native_speakers = 5_222_444;
+    $stmt->execute();
+
+    /* Setting autocommit=true will trigger a commit */
+    $mysqli->autocommit(true);
+
+    print "Committed 2 row in the database\n";
+} catch (mysqli_sql_exception $exception) {
+    $mysqli->rollback();
+
+    throw $exception;
+}
 ]]>
    </programlisting>
    <para>&style.procedural;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
-$link = mysqli_connect("localhost", "my_user", "my_password", "world");
 
-if (!$link) {
-    printf("Can't connect to localhost. Error: %s\n", mysqli_connect_error());
-    exit();
-}
+/* Tell mysqli to throw an exception if an error occurs */
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
 
-/* turn autocommit on */
-mysqli_autocommit($link, TRUE);
+$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
 
-if ($result = mysqli_query($link, "SELECT @@autocommit")) {
+/* The table engine has to support transactions */
+mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
+    Code text NOT NULL,
+    Speakers int(11) NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
+
+/* Turn autocommit off */
+mysqli_autocommit($mysqli, false);
+
+$result = mysqli_query($mysqli, "SELECT @@autocommit");
+$row = mysqli_fetch_row($result);
+printf("Autocommit is %s\n", $row[0]);
+
+try {
+    /* Prepare insert statement */
+    $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
+    mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
+
+    /* Insert some values */
+    $language_code = 'DE';
+    $native_speakers = 50_123_456;
+    mysqli_stmt_execute($stmt);
+    $language_code = 'FR';
+    $native_speakers = 40_546_321;
+    mysqli_stmt_execute($stmt);
+
+    /* Commit the data in the database. This doesn't set autocommit=true */
+    mysqli_commit($mysqli);
+    print "Committed 2 rows in the database\n";
+
+    $result = mysqli_query($mysqli, "SELECT @@autocommit");
     $row = mysqli_fetch_row($result);
     printf("Autocommit is %s\n", $row[0]);
-    mysqli_free_result($result);
-}
 
-/* close connection */
-mysqli_close($link);
-?>
+    /* Try to insert more values */
+    $language_code = 'PL';
+    $native_speakers = 30_555_444;
+    mysqli_stmt_execute($stmt);
+    $language_code = 'DK';
+    $native_speakers = 5_222_444;
+    mysqli_stmt_execute($stmt);
+
+    /* Setting autocommit=true will trigger a commit */
+    mysqli_autocommit($mysqli, true);
+
+    print "Committed 2 row in the database\n";
+} catch (mysqli_sql_exception $exception) {
+    mysqli_rollback($mysqli);
+
+    throw $exception;
+}
 ]]>
    </programlisting>
    &examples.outputs;
    <screen>
 <![CDATA[
-Autocommit is 1
+Autocommit is 0
+Committed 2 rows in the database
+Autocommit is 0
+Committed 2 row in the database
+Autocommit is 0
+Committed 2 rows in the database
+Autocommit is 0
+Committed 2 row in the database
 ]]>
    </screen>
   </example>
diff --git a/reference/mysqli/mysqli/begin-transaction.xml b/reference/mysqli/mysqli/begin-transaction.xml
index 15b11d6c22..f0a078e100 100644
--- a/reference/mysqli/mysqli/begin-transaction.xml
+++ b/reference/mysqli/mysqli/begin-transaction.xml
@@ -84,48 +84,96 @@
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    This function does not work with non transactional table types (like
+    MyISAM or ISAM).
+   </para>
+  </note>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
-  <example>
-   <title><methodname>$mysqli->begin_transaction</methodname> example</title>
+  <example xml:id="mysqli.begin-transaction.example.basic">
+   <title><methodname>mysqli::begin_transaction</methodname> example</title>
    <para>&style.oop;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
-$mysqli = new mysqli("127.0.0.1", "my_user", "my_password", "sakila");
 
-if ($mysqli->connect_errno) {
-    printf("Connect failed: %s\n", $mysqli->connect_error);
-    exit();
+/* Tell mysqli to throw an exception if an error occurs */
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
+
+/* The table engine has to support transactions */
+$mysqli->query("CREATE TABLE IF NOT EXISTS language (
+    Code text NOT NULL,
+    Speakers int(11) NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
+
+/* Start transaction */
+$mysqli->begin_transaction();
+
+try {
+    /* Insert some values */
+    $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");
+
+    /* Try to insert invalid values */
+    $language_code = 'FR';
+    $native_speakers = 'Unknown';
+    $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
+    $stmt->bind_param('ss', $language_code, $native_speakers);
+    $stmt->execute();
+
+    /* If code reaches this point without errors then commit the data in the database */
+    $mysqli->commit();
+} catch (mysqli_sql_exception $exception) {
+    $mysqli->rollback();
+
+    throw $exception;
 }
-
-$mysqli->begin_transaction(MYSQLI_TRANS_START_READ_ONLY);
-
-$mysqli->query("SELECT first_name, last_name FROM actor");
-$mysqli->commit();
-
-$mysqli->close();
-?>
 ]]>
    </programlisting>
    <para>&style.procedural;</para>
    <programlisting role="php">
 <![CDATA[
 <?php
-$link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");
 
-if (mysqli_connect_errno()) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
+/* Tell mysqli to throw an exception if an error occurs */
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+
+$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
+
+/* The table engine has to support transactions */
+mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
+    Code text NOT NULL,
+    Speakers int(11) NOT NULL
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
+
+/* Start transaction */
+mysqli_begin_transaction($mysqli);
+
+try {
+    /* Insert some values */
+    mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");
+
+    /* Try to insert invalid values */
+    $language_code = 'FR';
+    $native_speakers = 'Unknown';
+    $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
+    mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
+    mysqli_stmt_execute($stmt);
+
+    /* If code reaches this point without errors then commit the data in the database */
+    mysqli_commit($mysqli);
+} catch (mysqli_sql_exception $exception) {
+    mysqli_rollback($mysqli);
+
+    throw $exception;
 }
-
-mysqli_begin_transaction($link, MYSQLI_TRANS_START_READ_ONLY);
-
-mysqli_query($link, "SELECT first_name, last_name FROM actor LIMIT 1");
-mysqli_commit($link);
-
-mysqli_close($link);
-?>
 ]]>
    </programlisting>
   </example>
diff --git a/reference/mysqli/mysqli/commit.xml b/reference/mysqli/mysqli/commit.xml
index 91896cba05..2a819b004a 100644
--- a/reference/mysqli/mysqli/commit.xml
+++ b/reference/mysqli/mysqli/commit.xml
@@ -59,6 +59,16 @@
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    This function does not work with non transactional table types (like
+    MyISAM or ISAM).
+   </para>
+  </note>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <para>
@@ -86,76 +96,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <example>
-   <title><methodname>mysqli::commit</methodname> example</title>
-   <para>&style.oop;</para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
-
-/* check connection */
-if (mysqli_connect_errno()) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
-}
-
-$mysqli->query("CREATE TABLE Language LIKE CountryLanguage");
-
-/* set autocommit to off */
-$mysqli->autocommit(FALSE);
-
-/* Insert some values */
-$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)");
-$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)");
-
-/* commit transaction */
-if (!$mysqli->commit()) {
-    print("Transaction commit failed\n");
-    exit();
-}
-
-/* drop table */
-$mysqli->query("DROP TABLE Language");
-
-/* close connection */
-$mysqli->close();
-?>
-]]>
-   </programlisting>
-   <para>&style.procedural;</para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$link = mysqli_connect("localhost", "my_user", "my_password", "test");
-
-/* check connection */
-if (!$link) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
-}
-
-/* set autocommit to off */
-mysqli_autocommit($link, FALSE);
-
-mysqli_query($link, "CREATE TABLE Language LIKE CountryLanguage");
-
-/* Insert some values */
-mysqli_query($link, "INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)");
-mysqli_query($link, "INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)");
-
-/* commit transaction */
-if (!mysqli_commit($link)) {
-    print("Transaction commit failed\n");
-    exit();
-}
-
-/* close connection */
-mysqli_close($link);
-?>
-]]>
-   </programlisting>
-  </example>
+  <para>
+   See the <link linkend="mysqli.begin-transaction.example.basic"><methodname>mysqli::begin_transaction</methodname> example</link>.
+  </para>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/reference/mysqli/mysqli/release-savepoint.xml b/reference/mysqli/mysqli/release-savepoint.xml
index 54275e0bdc..71fe00ae49 100644
--- a/reference/mysqli/mysqli/release-savepoint.xml
+++ b/reference/mysqli/mysqli/release-savepoint.xml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
 <refentry xml:id="mysqli.release-savepoint" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>mysqli::release_savepoint</refname>
@@ -22,11 +21,9 @@
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   This function is identical to executing <code>$mysqli->query("RELEASE SAVEPOINT `$name`");</code>.
+   This function does not trigger commit or rollback.
   </para>
-  
-  &warn.undocumented.func;
- 
  </refsect1>
 
  <refsect1 role="parameters">
@@ -38,7 +35,7 @@
      <term><parameter>name</parameter></term>
      <listitem>
       <para>
-       
+       The identifier of the savepoint.
       </para>
      </listitem>
     </varlistentry>
@@ -57,7 +54,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>mysqli_rollback</function></member>
+    <member><function>mysqli_savepoint</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/mysqli/mysqli/rollback.xml b/reference/mysqli/mysqli/rollback.xml
index dbc1b4f419..afafc4aeb8 100644
--- a/reference/mysqli/mysqli/rollback.xml
+++ b/reference/mysqli/mysqli/rollback.xml
@@ -59,6 +59,16 @@
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    This function does not work with non transactional table types (like
+    MyISAM or ISAM).
+   </para>
+  </note>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <para>
@@ -86,114 +96,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <example>
-   <title><methodname>mysqli::rollback</methodname> example</title>
-   <para>&style.oop;</para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
-
-/* check connection */
-if (mysqli_connect_errno()) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
-}
-
-/* disable autocommit */
-$mysqli->autocommit(FALSE);
-
-$mysqli->query("CREATE TABLE myCity LIKE City");
-$mysqli->query("ALTER TABLE myCity Type=InnoDB");
-$mysqli->query("INSERT INTO myCity SELECT * FROM City LIMIT 50");
-
-/* commit insert */
-$mysqli->commit();
-
-/* delete all rows */
-$mysqli->query("DELETE FROM myCity");
-
-if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) {
-    $row = $result->fetch_row();
-    printf("%d rows in table myCity.\n", $row[0]);
-    /* Free result */
-    $result->close();
-}
-
-/* Rollback */
-$mysqli->rollback();
-
-if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) {
-    $row = $result->fetch_row();
-    printf("%d rows in table myCity (after rollback).\n", $row[0]);
-    /* Free result */
-    $result->close();
-}
-
-/* Drop table myCity */
-$mysqli->query("DROP TABLE myCity");
-
-$mysqli->close();
-?>
-]]>
-   </programlisting>
-   <para>&style.procedural;</para>
-   <programlisting role="php">
-<![CDATA[
-<?php
-$link = mysqli_connect("localhost", "my_user", "my_password", "world");
-
-/* check connection */
-if (mysqli_connect_errno()) {
-    printf("Connect failed: %s\n", mysqli_connect_error());
-    exit();
-}
-
-/* disable autocommit */
-mysqli_autocommit($link, FALSE);
-
-mysqli_query($link, "CREATE TABLE myCity LIKE City");
-mysqli_query($link, "ALTER TABLE myCity Type=InnoDB");
-mysqli_query($link, "INSERT INTO myCity SELECT * FROM City LIMIT 50");
-
-/* commit insert */
-mysqli_commit($link);
-
-/* delete all rows */
-mysqli_query($link, "DELETE FROM myCity");
-
-if ($result = mysqli_query($link, "SELECT COUNT(*) FROM myCity")) {
-    $row = mysqli_fetch_row($result);
-    printf("%d rows in table myCity.\n", $row[0]);
-    /* Free result */
-    mysqli_free_result($result);
-}
-
-/* Rollback */
-mysqli_rollback($link);
-
-if ($result = mysqli_query($link, "SELECT COUNT(*) FROM myCity")) {
-    $row = mysqli_fetch_row($result);
-    printf("%d rows in table myCity (after rollback).\n", $row[0]);
-    /* Free result */
-    mysqli_free_result($result);
-}
-
-/* Drop table myCity */
-mysqli_query($link, "DROP TABLE myCity");
-
-mysqli_close($link);
-?>
-]]>
-   </programlisting>
-   &examples.outputs;
-   <screen>
-<![CDATA[
-0 rows in table myCity.
-50 rows in table myCity (after rollback).
-]]>
-   </screen>
-  </example>
+  <para>
+   See the <link linkend="mysqli.begin-transaction.example.basic"><methodname>mysqli::begin_transaction</methodname> example</link>.
+  </para>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/reference/mysqli/mysqli/savepoint.xml b/reference/mysqli/mysqli/savepoint.xml
index 7b0bfc2d74..dde2307dcb 100644
--- a/reference/mysqli/mysqli/savepoint.xml
+++ b/reference/mysqli/mysqli/savepoint.xml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
 <refentry xml:id="mysqli.savepoint" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>mysqli::savepoint</refname>
@@ -22,11 +21,8 @@
    <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   This function is identical to executing <code>$mysqli->query("SAVEPOINT `$name`");</code>
   </para>
-  
-  &warn.undocumented.func;
- 
  </refsect1>
 
  <refsect1 role="parameters">
@@ -38,7 +34,7 @@
      <term><parameter>name</parameter></term>
      <listitem>
       <para>
-       
+       The identifier of the savepoint.
       </para>
      </listitem>
     </varlistentry>
@@ -57,7 +53,7 @@
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>mysqli_commit</function></member>
+    <member><function>mysqli_release_savepoint</function></member>
    </simplelist>
   </para>
  </refsect1>