<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mysqli.execute-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli::execute_query</refname>
  <refname>mysqli_execute_query</refname>
  <refpurpose>Prepares, binds parameters, and executes SQL statement</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="mysqli">
   <modifier>public</modifier> <type class="union"><type>mysqli_result</type><type>bool</type></type><methodname>mysqli::execute_query</methodname>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>params</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type class="union"><type>mysqli_result</type><type>bool</type></type><methodname>mysqli_execute_query</methodname>
   <methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>params</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Prepares the SQL query, binds parameters, and executes it.
   The <methodname>mysqli::execute_query</methodname> method is a shortcut for
   <methodname>mysqli::prepare</methodname>,
   <methodname>mysqli_stmt::bind_param</methodname>,
   <methodname>mysqli_stmt::execute</methodname>,
   and <methodname>mysqli_stmt::get_result</methodname>.
  </para>
  <para>
   The statement template can contain zero or more question mark
   (<literal>?</literal>) parameter markers⁠—also called placeholders.
   The parameter values must be provided as an &array; using
   <parameter>params</parameter> parameter.
  </para>
  <para>
   A prepared statement is created under the hood but it&apos;s never exposed
   outside of the function. It&apos;s impossible to access properties of the
   statement as one would do with the <classname>mysqli_stmt</classname> object.
   Due to this limitation, the status information is copied to the
   <classname>mysqli</classname> object and is available using its methods, e.g.
   <function>mysqli_affected_rows</function> or <function>mysqli_error</function>.
  </para>
  <note>
   <para>
    In the case where a statement is passed to
    <function>mysqli_execute_query</function> that is longer than
    <literal>max_allowed_packet</literal> of the server, the returned
    error codes are different depending on the operating system.
    The behavior is as follows:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      On Linux returns an error code of 1153.
      The error message means <quote>got a packet bigger than
      <literal>max_allowed_packet</literal> bytes</quote>.
     </para>
    </listitem>
    <listitem>
     <para>
      On Windows returns an error code 2006.
      This error message means <quote>server has gone away</quote>.
     </para>
    </listitem>
   </itemizedlist>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.link.description;
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       The query, as a string. It must consist of a single SQL statement.
      </para>
      <para>
       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 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.
        However, they are not permitted for identifiers (such as table or
        column names).
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>params</parameter></term>
     <listitem>
      <para>
       An optional list &array; with as many elements as there are bound parameters in the SQL statement being executed. Each value is treated as a &string;.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &false; on failure. For successful queries which produce a result
   set, such as <literal>SELECT, SHOW, DESCRIBE</literal> or
   <literal>EXPLAIN</literal>, returns
   a <classname>mysqli_result</classname> object. For other successful queries,
   returns &true;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><methodname>mysqli::execute_query</methodname> example</title>
   <para>&style.oop;</para>
   <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = $mysqli->execute_query($query, ['DEU']);
foreach ($result as $row) {
    printf("%s (%s)\n", $row["Name"], $row["District"]);
}
]]>
   </programlisting>
   <para>&style.procedural;</para>
   <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = mysqli_execute_query($link, $query, ['DEU']);
foreach ($result as $row) {
    printf("%s (%s)\n", $row["Name"], $row["District"]);
}
]]>
   </programlisting>
   &examples.outputs.similar;
   <screen>
<![CDATA[
Aachen (Nordrhein-Westfalen)
Augsburg (Baijeri)
Bergisch Gladbach (Nordrhein-Westfalen)
Berlin (Berliini)
Bielefeld (Nordrhein-Westfalen)
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_prepare</function></member>
    <member><function>mysqli_stmt_execute</function></member>
    <member><function>mysqli_stmt_bind_param</function></member>
    <member><function>mysqli_stmt_get_result</function></member>
   </simplelist>
  </para>
 </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
-->
