Author: Kamil Tekiela (kamil-tekiela)
Committer: GitHub (web-flow)
Pusher: kamil-tekiela
Date: 2026-10-04T19:13:11+01:00
Commit: https://github.com/php/doc-en/commit/01175bf92d73d885dc5a19793bc1d0c5d1a75bac
Raw diff: https://github.com/php/doc-en/commit/01175bf92d73d885dc5a19793bc1d0c5d1a75bac.diff
Documentation for mysqli::quote_string (PHP 8.6) (#5908)
Changed paths:
A reference/mysqli/mysqli/quote-string.xml
M reference/mysqli/mysqli/real-escape-string.xml
M reference/mysqli/versions.xml
Diff:
diff --git a/reference/mysqli/mysqli/quote-string.xml b/reference/mysqli/mysqli/quote-string.xml
new file mode 100644
index 000000000000..d3b6f71c86d5
--- /dev/null
+++ b/reference/mysqli/mysqli/quote-string.xml
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="mysqli.quote-string" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>mysqli::quote_string</refname>
+ <refname>mysqli_quote_string</refname>
+ <refpurpose>Quotes and escapes a string for use in an SQL statement</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <simpara>&style.oop;</simpara>
+ <methodsynopsis role="mysqli">
+ <modifier>public</modifier>
<type>string</type><methodname>mysqli::quote_string</methodname>
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>&style.procedural;</simpara>
+ <methodsynopsis>
+ <type>string</type><methodname>mysqli_quote_string</methodname>
+
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>
+ Creates a legal SQL string literal that can be used in an SQL statement.
+ The given string is escaped in the same way as
+ <methodname>mysqli::real_escape_string</methodname>, taking into account
+ the current character set of the connection, and the result is wrapped in
+ single quotes. The returned value must therefore be inserted into the
+ query without adding any further quotes around it.
+ </simpara>
+ <simpara>
+ Unlike <methodname>mysqli::real_escape_string</methodname>, the result is
+ also safe when the <literal>NO_BACKSLASH_ESCAPES</literal> SQL mode is
+ enabled on the connection.
+ </simpara>
+ <caution>
+ <title>Security: the default character set</title>
+ <simpara>
+ The character set must be set either at the server level, or with
+ the API function <function>mysqli_set_charset</function> for it to affect
+ <function>mysqli_quote_string</function>. See the concepts section
+ on <link linkend="mysqlinfo.concepts.charset">character sets</link> for
+ more information.
+ </simpara>
+ </caution>
+ <note>
+ <simpara>
+ Quoting is only suitable for string literals. It does not make
+ identifiers, such as table or column names, safe. Whenever possible, use
+ <link linkend="mysqli.quickstart.prepared-statements">prepared
+ statements</link> instead of building queries manually.
+ </simpara>
+ </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ &mysqli.link.description;
+ <varlistentry>
+ <term><parameter>string</parameter></term>
+ <listitem>
+ <simpara>
+ The string to be quoted and escaped.
+ </simpara>
+ <simpara>
+ Characters encoded are <literal>NUL (ASCII 0)</literal>,
+ <literal>\n</literal>, <literal>\r</literal>,
<literal>\</literal>,
+ <literal>'</literal>, <literal>"</literal>, and
+ <keycombo
action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>.
+ If the <literal>NO_BACKSLASH_ESCAPES</literal> SQL mode is enabled on
+ the connection, only <literal>'</literal> is encoded, by doubling it.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ Returns the escaped string enclosed in single quotes.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>mysqli::quote_string</methodname> example</title>
+ <simpara>&style.oop;</simpara>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = new mysqli("localhost", "my_user", "my_password",
"world");
+
+$city = "'s-Hertogenbosch";
+
+/* this query with quoted $city will work */
+$query = sprintf("SELECT CountryCode FROM City WHERE name=%s",
$mysqli->quote_string($city));
+$result = $mysqli->query($query);
+printf("Select returned %d rows.\n", $result->num_rows);
+
+/* this query will fail, because we didn't quote and escape $city */
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
+$result = $mysqli->query($query);
+]]>
+ </programlisting>
+ <simpara>&style.procedural;</simpara>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
+$mysqli = mysqli_connect("localhost", "my_user", "my_password",
"world");
+
+$city = "'s-Hertogenbosch";
+
+/* this query with quoted $city will work */
+$query = sprintf("SELECT CountryCode FROM City WHERE name=%s",
mysqli_quote_string($mysqli, $city));
+$result = mysqli_query($mysqli, $query);
+printf("Select returned %d rows.\n", mysqli_num_rows($result));
+
+/* this query will fail, because we didn't quote and escape $city */
+$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
+$result = mysqli_query($mysqli, $query);
+]]>
+ </programlisting>
+ &examples.outputs.similar;
+ <screen>
+<![CDATA[
+Select returned 1 rows.
+
+Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual
that corresponds to your MySQL server version for the right syntax to use near
's-Hertogenbosch'' at line 1 in...
+]]>
+ </screen>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>mysqli::real_escape_string</methodname></member>
+ <member><methodname>mysqli::set_charset</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/mysqli/mysqli/real-escape-string.xml
b/reference/mysqli/mysqli/real-escape-string.xml
index 9efe54bea686..4ae5c10318ba 100644
--- a/reference/mysqli/mysqli/real-escape-string.xml
+++ b/reference/mysqli/mysqli/real-escape-string.xml
@@ -35,6 +35,19 @@
more information.
</para>
</caution>
+ <warning>
+ <simpara>
+ This function does not add quotes around the result; they must be added
+ by the caller. If the <literal>NO_BACKSLASH_ESCAPES</literal> SQL mode is
+ enabled on the connection, only the single quote
+ (<literal>'</literal>) is escaped, so a value placed between double quotes
+ (<literal>"</literal>) can terminate the string and allow SQL injection.
+ Use <link linkend="mysqli.quickstart.prepared-statements">prepared
+ statements</link> instead. If that is not possible, use
+ <methodname>mysqli::quote_string</methodname>, which always wraps the
+ result in single quotes.
+ </simpara>
+ </warning>
</refsect1>
<refsect1 role="parameters">
@@ -48,12 +61,14 @@
<para>
The string to be escaped.
</para>
- <para>
+ <simpara>
Characters encoded are <literal>NUL (ASCII 0)</literal>,
<literal>\n</literal>, <literal>\r</literal>,
<literal>\</literal>,
<literal>'</literal>, <literal>"</literal>, and
<keycombo
action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>.
- </para>
+ If the <literal>NO_BACKSLASH_ESCAPES</literal> SQL mode is enabled on
+ the connection, only <literal>'</literal> is encoded, by doubling it.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
@@ -126,11 +141,10 @@ Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL
syntax
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><function>mysqli_set_charset</function></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><function>mysqli_set_charset</function></member>
+ <member><function>mysqli_quote_string</function></member>
+ </simplelist>
</refsect1>
</refentry>
diff --git a/reference/mysqli/versions.xml b/reference/mysqli/versions.xml
index 2f1800a32999..750ecde77221 100644
--- a/reference/mysqli/versions.xml
+++ b/reference/mysqli/versions.xml
@@ -64,6 +64,7 @@
<function name="mysqli_poll" from="PHP 5 >= 5.3.0, PHP 7, PHP
8"/>
<function name="mysqli_prepare" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_query" from="PHP 5, PHP 7, PHP 8"/>
+ <function name="mysqli_quote_string" from="PHP 8 >= 8.6.0"/>
<function name="mysqli_real_connect" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_real_escape_string" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli_real_query" from="PHP 5, PHP 7, PHP 8"/>
@@ -150,6 +151,7 @@
<function name="mysqli::poll" from="PHP 5 >= 5.3.0, PHP 7, PHP
8"/>
<function name="mysqli::prepare" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::query" from="PHP 5, PHP 7, PHP 8"/>
+ <function name="mysqli::quote_string" from="PHP 8 >= 8.6.0"/>
<function name="mysqli::real_connect" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::real_escape_string" from="PHP 5, PHP 7, PHP 8"/>
<function name="mysqli::real_query" from="PHP 5, PHP 7, PHP 8"/>