Updating mysqli prepared statements docs

Co-authored-by: George Peter Banyard <7906688+Girgias@users.noreply.github.com>

Closes GH-338.

reference/mysqli/mysqli/prepare.xml

@@ -4,7 +4,7 @@
  <refnamediv>
   <refname>mysqli::prepare</refname>
   <refname>mysqli_prepare</refname>
-  <refpurpose>Prepare an SQL statement for execution</refpurpose>
+  <refpurpose>Prepares an SQL statement for execution</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -25,10 +25,10 @@
    operations on the statement. The query must consist of a single SQL statement.
   </para>
   <para>
+   The statement template can contain zero or more question mark
+   (<literal>?</literal>) parameter markers⁠—also called placeholders.
    The parameter markers must be bound to application variables using
-   <function>mysqli_stmt_bind_param</function> and/or 
-   <function>mysqli_stmt_bind_result</function> before executing the
-   statement or fetching rows.
+   <function>mysqli_stmt_bind_param</function> before executing the statement.
   </para>
  </refsect1>
 
@@ -41,38 +41,30 @@
      <term><parameter>query</parameter></term>
      <listitem>
       <para>
-       The query, as a string.
+       The query, as a string. It must consist of a single SQL statement.
       </para>
-      <note>
-       <para>
-        You should not add a terminating semicolon or <literal>\g</literal>
-        to the statement.
-       </para>
-      </note>
       <para>
-       This parameter can include one or more parameter markers in the SQL
-       statement by embedding question mark (<literal>?</literal>) characters
+       The SQL statement may contain zero or more parameter markers
+       represented by question mark (<literal>?</literal>) characters
        at the appropriate positions.
       </para>
       <note>
+<!-- Copied from https://dev.mysql.com/doc/c-api/8.0/en/mysql-stmt-prepare.html -->
        <para>
         The markers are legal only in certain places in SQL statements.
-        For example, they are allowed in the <literal>VALUES()</literal>
+        For example, they are permitted in the <literal>VALUES()</literal>
         list of an <literal>INSERT</literal> statement (to specify column
         values for a row), or in a comparison with a column in a
         <literal>WHERE</literal> clause to specify a comparison value.
        </para>
        <para>
-        However, they are not allowed for identifiers (such as table or
-        column names), in the select list that names the columns to be
-        returned by a <literal>SELECT</literal> statement, or to specify both
+        However, they are not permitted for identifiers (such as table or
+        column names), or to specify both
         operands of a binary operator such as the <literal>=</literal> equal
         sign. The latter restriction is necessary because it would be
-        impossible to determine the parameter type. It's not allowed to
-        compare marker with <literal>NULL</literal> by 
-        <literal>? IS NULL</literal> too. In general, parameters are legal
-        only in Data Manipulation Language (DML) statements, and not in Data
-        Definition Language (DDL) statements.
+        impossible to determine the parameter type. In general, parameters are
+        legal only in Data Manipulation Language (DML) statements, and not in
+        Data Definition Language (DDL) statements.
        </para>
       </note>
      </listitem>
@@ -96,80 +88,56 @@
    <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_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
 
 $city = "Amersfoort";
 
 /* create a prepared statement */
-if ($stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?")) {
+$stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
 
-    /* bind parameters for markers */
-    $stmt->bind_param("s", $city);
+/* bind parameters for markers */
+$stmt->bind_param("s", $city);
 
-    /* execute query */
-    $stmt->execute();
+/* execute query */
+$stmt->execute();
 
-    /* bind result variables */
-    $stmt->bind_result($district);
+/* bind result variables */
+$stmt->bind_result($district);
 
-    /* fetch value */
-    $stmt->fetch();
+/* fetch value */
+$stmt->fetch();
 
-    printf("%s is in district %s\n", $city, $district);
-
-    /* close statement */
-    $stmt->close();
-}
-
-/* close connection */
-$mysqli->close();
-?>
+printf("%s is in district %s\n", $city, $district);
 ]]>
    </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();
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$link = mysqli_connect("localhost", "my_user", "my_password", "world");
 
 $city = "Amersfoort";
 
 /* create a prepared statement */
-if ($stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?")) {
+$stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");
 
-    /* bind parameters for markers */
-    mysqli_stmt_bind_param($stmt, "s", $city);
+/* bind parameters for markers */
+mysqli_stmt_bind_param($stmt, "s", $city);
 
-    /* execute query */
-    mysqli_stmt_execute($stmt);
+/* execute query */
+mysqli_stmt_execute($stmt);
 
-    /* bind result variables */
-    mysqli_stmt_bind_result($stmt, $district);
+/* bind result variables */
+mysqli_stmt_bind_result($stmt, $district);
 
-    /* fetch value */
-    mysqli_stmt_fetch($stmt);
+/* fetch value */
+mysqli_stmt_fetch($stmt);
 
-    printf("%s is in district %s\n", $city, $district);
-
-    /* close statement */
-    mysqli_stmt_close($stmt);
-}
-
-/* close connection */
-mysqli_close($link);
-?>
+printf("%s is in district %s\n", $city, $district);
 ]]>
    </programlisting>
    &examples.outputs;
@@ -189,6 +157,7 @@ Amersfoort is in district Utrecht
     <member><function>mysqli_stmt_fetch</function></member>
     <member><function>mysqli_stmt_bind_param</function></member>
     <member><function>mysqli_stmt_bind_result</function></member>
+    <member><function>mysqli_stmt_get_result</function></member>
     <member><function>mysqli_stmt_close</function></member>
    </simplelist>
   </para>

reference/mysqli/mysqli_stmt/construct.xml

@@ -23,7 +23,14 @@
   &reftitle.parameters;
   <para>
    <variablelist>
-    &mysqli.link.description;
+    <varlistentry>
+     <term><parameter>link</parameter></term>
+     <listitem>
+      <para>
+       A valid <classname>mysqli</classname> object.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term><parameter>query</parameter></term>
      <listitem>

reference/mysqli/mysqli_stmt/execute.xml

@@ -4,7 +4,7 @@
  <refnamediv>
   <refname>mysqli_stmt::execute</refname>
   <refname>mysqli_stmt_execute</refname>
-  <refpurpose>Executes a prepared Query</refpurpose>
+  <refpurpose>Executes a prepared statement</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -20,10 +20,11 @@
    <methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Executes a query that has been previously prepared using the
-   <function>mysqli_prepare</function> function. When executed any
-   parameter markers which exist will automatically be replaced with the
-   appropriate data.
+   Executes previously prepared statement. The statement must be successfully 
+   prepared prior to execution, using either
+   the <function>mysqli_prepare</function> or
+   <function>mysqli_stmt_prepare</function> function, or by passing the second
+   argument to <methodname>mysqli_stmt::__construct</methodname>.
   </para>
   <para>
    If the statement is <literal>UPDATE</literal>, <literal>DELETE</literal>,
@@ -32,13 +33,6 @@
    function. Likewise, if the query yields a result set the 
    <function>mysqli_stmt_fetch</function> function is used.
   </para>
-  <note>
-   <para>
-    When using <function>mysqli_stmt_execute</function>, the 
-    <function>mysqli_stmt_fetch</function> function must be used to fetch the
-    data prior to performing any additional queries.
-   </para>
-  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -60,24 +54,21 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>&style.oop;</title>
+   <title><methodname>mysqli_stmt::execute</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_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
 
 $mysqli->query("CREATE TABLE myCity LIKE City");
 
 /* Prepare an insert statement */
-$query = "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)";
-$stmt = $mysqli->prepare($query);
+$stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");
 
+/* Bind variables to parameters */
 $stmt->bind_param("sss", $val1, $val2, $val3);
 
 $val1 = 'Stuttgart';
@@ -94,47 +85,31 @@ $val3 = 'Aquitaine';
 /* Execute the statement */
 $stmt->execute();
 
-/* close statement */
-$stmt->close();
-
 /* retrieve all rows from myCity */
 $query = "SELECT Name, CountryCode, District FROM myCity";
-if ($result = $mysqli->query($query)) {
-    while ($row = $result->fetch_row()) {
-        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
-    }
-    /* free result set */
-    $result->close();
+$result = $mysqli->query($query);
+while ($row = $result->fetch_row()) {
+    printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
 }
 
 /* remove table */
 $mysqli->query("DROP TABLE myCity");
-
-/* close connection */
-$mysqli->close();
-?>
 ]]>
    </programlisting>
-  </example>
-  <example>
-   <title>&style.procedural;</title>
+   <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();
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$link = mysqli_connect("localhost", "my_user", "my_password", "world");
 
 mysqli_query($link, "CREATE TABLE myCity LIKE City");
 
 /* Prepare an insert statement */
-$query = "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)";
-$stmt = mysqli_prepare($link, $query);
+$stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");
 
+/* Bind variables to parameters */
 mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);
 
 $val1 = 'Stuttgart';
@@ -151,25 +126,15 @@ $val3 = 'Aquitaine';
 /* Execute the statement */
 mysqli_stmt_execute($stmt);
 
-/* close statement */
-mysqli_stmt_close($stmt);
-
 /* retrieve all rows from myCity */
 $query = "SELECT Name, CountryCode, District FROM myCity";
-if ($result = mysqli_query($link, $query)) {
-    while ($row = mysqli_fetch_row($result)) {
-        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
-    }
-    /* free result set */
-    mysqli_free_result($result);
+$result = mysqli_query($link, $query);
+while ($row = mysqli_fetch_row($result)) {
+    printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
 }
 
 /* remove table */
 mysqli_query($link, "DROP TABLE myCity");
-
-/* close connection */
-mysqli_close($link);
-?>
 ]]>
      </programlisting>
      &examples.outputs;

reference/mysqli/mysqli_stmt/prepare.xml

@@ -4,14 +4,14 @@
  <refnamediv>
   <refname>mysqli_stmt::prepare</refname>
   <refname>mysqli_stmt_prepare</refname>
-  <refpurpose>Prepare an SQL statement for execution</refpurpose>
+  <refpurpose>Prepares an SQL statement for execution</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;
   <para>&style.oop;</para>
   <methodsynopsis role="oop">
-   <modifier>public</modifier> <type>mixed</type><methodname>mysqli_stmt::prepare</methodname>
+   <modifier>public</modifier> <type>bool</type><methodname>mysqli_stmt::prepare</methodname>
    <methodparam><type>string</type><parameter>query</parameter></methodparam>
   </methodsynopsis>
   <para>&style.procedural;</para>
@@ -21,13 +21,14 @@
    <methodparam><type>string</type><parameter>query</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Prepares the SQL query pointed to by the null-terminated string query. 
+   Prepares a statement for execution.
+   The query must consist of a single SQL statement.
   </para>
   <para>
+   The statement template can contain zero or more question mark
+   (<literal>?</literal>) parameter markers⁠—also called placeholders.
    The parameter markers must be bound to application variables using
-   <function>mysqli_stmt_bind_param</function> and/or 
-   <function>mysqli_stmt_bind_result</function> before executing the
-   statement or fetching rows.
+   <function>mysqli_stmt_bind_param</function> before executing the statement.
   </para>
   <note>
    <para>
@@ -75,31 +76,27 @@
        The query, as a string. It must consist of a single SQL statement.
       </para>
       <para>
-       You can include one or more parameter markers in the SQL statement by
-       embedding question mark (<literal>?</literal>) characters at the
-       appropriate positions.
+       The SQL statement may contain zero or more parameter markers
+       represented by question mark (<literal>?</literal>) characters
+       at the appropriate positions.
       </para>
       <note>
-       <para>
-        You should not add a terminating semicolon or <literal>\g</literal>
-        to the statement.
-       </para>
-      </note>
-      <note>
+<!-- Copied from https://dev.mysql.com/doc/c-api/8.0/en/mysql-stmt-prepare.html -->
        <para>
         The markers are legal only in certain places in SQL statements.
-        For example, they are allowed in the VALUES() list of an INSERT statement
-        (to specify column values for a row), or in a comparison with a column in
-        a WHERE clause to specify a comparison value.
+        For example, they are permitted in the <literal>VALUES()</literal>
+        list of an <literal>INSERT</literal> statement (to specify column
+        values for a row), or in a comparison with a column in a
+        <literal>WHERE</literal> clause to specify a comparison value.
        </para>
        <para>
-        However, they are not allowed for identifiers (such as table or column names),
-        in the select list that names the columns to be returned by a SELECT statement),
-        or to specify both operands of a binary operator such as the <literal>=</literal>
-        equal sign. The latter restriction is necessary because it would be impossible
-        to determine the parameter type. In general, parameters are legal only in Data
-        Manipulation Language (DML) statements, and not in Data Definition Language
-        (DDL) statements.
+        However, they are not permitted for identifiers (such as table or
+        column names), or to specify both
+        operands of a binary operator such as the <literal>=</literal> equal
+        sign. The latter restriction is necessary because it would be
+        impossible to determine the parameter type. In general, parameters are
+        legal only in Data Manipulation Language (DML) statements, and not in
+        Data Definition Language (DDL) statements.
        </para>
       </note>
      </listitem>
@@ -118,88 +115,63 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>&style.oop;</title>
+   <title><methodname>mysqli_stmt::prepare</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_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
 
 $city = "Amersfoort";
 
 /* create a prepared statement */
-$stmt =  $mysqli->stmt_init();
-if ($stmt->prepare("SELECT District FROM City WHERE Name=?")) {
+$stmt = $mysqli->stmt_init();
+$stmt->prepare("SELECT District FROM City WHERE Name=?");
 
-    /* bind parameters for markers */
-    $stmt->bind_param("s", $city);
+/* bind parameters for markers */
+$stmt->bind_param("s", $city);
 
-    /* execute query */
-    $stmt->execute();
+/* execute query */
+$stmt->execute();
 
-    /* bind result variables */
-    $stmt->bind_result($district);
+/* bind result variables */
+$stmt->bind_result($district);
 
-    /* fetch value */
-    $stmt->fetch();
+/* fetch value */
+$stmt->fetch();
 
-    printf("%s is in district %s\n", $city, $district);
-
-    /* close statement */
-    $stmt->close();
-}
-
-/* close connection */
-$mysqli->close();
-?>
+printf("%s is in district %s\n", $city, $district);
 ]]>
    </programlisting>
-  </example>
-  <example>
-   <title>&style.procedural;</title>
+   <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();
-}
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$link = mysqli_connect("localhost", "my_user", "my_password", "world");
 
 $city = "Amersfoort";
 
 /* create a prepared statement */
 $stmt = mysqli_stmt_init($link);
-if (mysqli_stmt_prepare($stmt, 'SELECT District FROM City WHERE Name=?')) {
+mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");
 
-    /* bind parameters for markers */
-    mysqli_stmt_bind_param($stmt, "s", $city);
+/* bind parameters for markers */
+mysqli_stmt_bind_param($stmt, "s", $city);
 
-    /* execute query */
-    mysqli_stmt_execute($stmt);
+/* execute query */
+mysqli_stmt_execute($stmt);
 
-    /* bind result variables */
-    mysqli_stmt_bind_result($stmt, $district);
+/* bind result variables */
+mysqli_stmt_bind_result($stmt, $district);
 
-    /* fetch value */
-    mysqli_stmt_fetch($stmt);
+/* fetch value */
+mysqli_stmt_fetch($stmt);
 
-    printf("%s is in district %s\n", $city, $district);
-
-    /* close statement */
-    mysqli_stmt_close($stmt);
-}
-
-/* close connection */
-mysqli_close($link);
-?>
+printf("%s is in district %s\n", $city, $district);
 ]]>
    </programlisting>
    &examples.outputs;