Skip to content

[Sync-En] mysqli: document quote_string() #3641

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
lacatoire merged 1 commit into from
Oct 5, 2026
Merged

[Sync-En] mysqli: document quote_string() #3641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
174 changes: 174 additions & 0 deletions reference/mysqli/mysqli/quote-string.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 01175bf92d73d885dc5a19793bc1d0c5d1a75bac Maintainer: lacatoire Status: ready -->
<refentry xml:id="mysqli.quote-string" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mysqli::quote_string</refname>
<refname>mysqli_quote_string</refname>
<refpurpose>Entoure de guillemets et protège une chaîne pour l'utiliser dans une requête SQL</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>
Cette fonction est utilisée pour créer une chaîne SQL valide qui pourra
être utilisée dans une requête SQL.
La chaîne donnée est échappée de la même façon que par
<methodname>mysqli::real_escape_string</methodname>, en tenant compte du jeu
de caractères courant de la connexion, et le résultat est entouré de
guillemets simples. La valeur retournée doit donc être insérée dans la
requête sans ajouter d'autres guillemets autour d'elle.
</simpara>
<simpara>
Contrairement à <methodname>mysqli::real_escape_string</methodname>, le résultat
est également sûr lorsque le mode SQL <literal>NO_BACKSLASH_ESCAPES</literal>
est activé sur la connexion.
</simpara>
<caution>
<title>Sécurité : Le jeu de caractères par défaut</title>
<simpara>
Le jeu de caractères doit être défini soit au niveau serveur,
soit avec la fonction API <function>mysqli_set_charset</function>
pour qu'il affecte la fonction <function>mysqli_quote_string</function>.
Voir la section sur les concepts
<link linkend="mysqlinfo.concepts.charset">des jeux de caractères</link>
pour plus d'informations.
</simpara>
</caution>
<note>
<simpara>
L'ajout de guillemets ne convient qu'aux littéraux de type chaîne. Cela ne
sécurise pas les identifiants, tels que les noms de tables ou de colonnes.
Dès que c'est possible, il faut utiliser des
<link linkend="mysqli.quickstart.prepared-statements">requêtes préparées</link>
plutôt que de construire les requêtes manuellement.
</simpara>
</note>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&mysqli.link.description;
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
<simpara>
La &string; à entourer de guillemets et à échapper.
</simpara>
<simpara>
Les caractères encodés sont <literal>NUL (ASCII 0)</literal>,
<literal>\n</literal>, <literal>\r</literal>, <literal>\</literal>,
<literal>'</literal>, <literal>"</literal>, et
<keycombo action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>.
Si le mode SQL <literal>NO_BACKSLASH_ESCAPES</literal> est activé sur
la connexion, seul <literal>'</literal> est encodé, en le doublant.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Retourne la chaîne échappée, entourée de guillemets simples.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Exemple avec <methodname>mysqli::quote_string</methodname></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";

/* Cette requête avec $city entouré de guillemets fonctionnera */
$query = sprintf("SELECT CountryCode FROM City WHERE name=%s", $mysqli->quote_string($city));
$result = $mysqli->query($query);
printf("Select a retourné %d lignes.\n", $result->num_rows);

/* Cette requête échouera, car $city n'a pas été entouré de guillemets ni échappé */
$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";

/* Cette requête avec $city entouré de guillemets fonctionnera */
$query = sprintf("SELECT CountryCode FROM City WHERE name=%s", mysqli_quote_string($mysqli, $city));
$result = mysqli_query($mysqli, $query);
printf("Select a retourné %d lignes.\n", mysqli_num_rows($result));

/* Cette requête échouera, car $city n'a pas été entouré de guillemets ni échappé */
$query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
$result = mysqli_query($mysqli, $query);
]]>
</programlisting>
&examples.outputs.similar;
<screen>
<![CDATA[
Select a retourné 1 lignes.

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
-->
32 changes: 23 additions & 9 deletions reference/mysqli/mysqli/real-escape-string.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: fc174e8d6162091550edde46159917ee7e5a2e73 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<!-- EN-Revision: 01175bf92d73d885dc5a19793bc1d0c5d1a75bac Maintainer: yannick Status: ready -->
<refentry xml:id="mysqli.real-escape-string" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mysqli::real_escape_string</refname>
Expand Down Expand Up @@ -40,6 +39,20 @@
pour plus d'informations.
</para>
</caution>
<warning>
<simpara>
Cette fonction n'ajoute pas de guillemets autour du résultat : ils doivent être
ajoutés par l'appelant. Si le mode SQL <literal>NO_BACKSLASH_ESCAPES</literal> est
activé sur la connexion, seul le guillemet simple
(<literal>'</literal>) est échappé : une valeur placée entre guillemets doubles
(<literal>"</literal>) peut donc terminer la chaîne et permettre une injection SQL.
Il faut utiliser à la place des
<link linkend="mysqli.quickstart.prepared-statements">requêtes préparées</link>.
Si ce n'est pas possible, il faut utiliser
<methodname>mysqli::quote_string</methodname>, qui entoure toujours le
résultat de guillemets simples.
</simpara>
</warning>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -53,12 +66,14 @@
<para>
La &string; à échapper.
</para>
<para>
<simpara>
Les caractères encodés sont <literal>NUL (ASCII 0)</literal>,
<literal>\n</literal>, <literal>\r</literal>, <literal>\</literal>,
<literal>'</literal>, <literal>"</literal>, et
<keycombo action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>.
</para>
Si le mode SQL <literal>NO_BACKSLASH_ESCAPES</literal> est activé sur
la connexion, seul <literal>'</literal> est encodé, en le doublant.
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -131,11 +146,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>
Expand Down
Loading