Skip to content

[PHP 8.2] Document mysqli_execute_query #1855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 12, 2022
Merged

[PHP 8.2] Document mysqli_execute_query #1855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f84144e
Document mysqli_execute_query
kamil-tekiela Sep 29, 2022
72a52bc
Drop inaccurate and confusing part copied from MySQL docs
kamil-tekiela Oct 12, 2022
fe3703e
Changed 'you' to formal style
kamil-tekiela Oct 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 205 additions & 0 deletions reference/mysqli/mysqli/execute-query.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
<?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="oop">
<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 role="procedural">
<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
-->
9 changes: 1 addition & 8 deletions reference/mysqli/mysqli/prepare.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,8 @@
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 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.
column names).
</para>
</note>
</listitem>
Expand Down
2 changes: 1 addition & 1 deletion reference/mysqli/mysqli/query.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
</para>
<note>
<para>
In the case where you pass a statement to
In the case where a statement is passed to
<function>mysqli_query</function> that is longer than
<literal>max_allowed_packet</literal> of the server, the returned
error codes are different depending on whether you are using MySQL
Expand Down
11 changes: 2 additions & 9 deletions reference/mysqli/mysqli_stmt/prepare.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
</para>
<note>
<para>
In the case where you pass a statement to
In the case where a statement is passed to
<function>mysqli_stmt_prepare</function> that is longer than
<literal>max_allowed_packet</literal> of the server, the returned
error codes are different depending on whether you are using MySQL
Expand Down Expand Up @@ -88,15 +88,8 @@
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 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.
column names).
</para>
</note>
</listitem>
Expand Down
2 changes: 2 additions & 0 deletions reference/mysqli/versions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
<function name="mysqli_error_list" from="PHP 5 &gt;= 5.4.0, PHP 7, PHP 8"/>
<function name="mysqli_escape_string" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_execute" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_execute_query" from="PHP 8 &gt;= 8.2.0"/>
<function name="mysqli_fetch_all" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/>
<function name="mysqli_fetch_array" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_fetch_assoc" from="PHP 5, PHP 7, PHP 8"/>
Expand Down Expand Up @@ -135,6 +136,7 @@
<function name="mysqli::debug" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::dump_debug_info" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::escape_string" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::execute_query" from="PHP 8 &gt;= 8.2.0"/>
<function name="mysqli::get_charset" from="PHP 5 &gt;= 5.1.0, PHP 7, PHP 8"/>
<function name="mysqli::get_client_info" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::get_connection_stats" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/>
Expand Down