From 65dba42ed400ba2ee930e418aff9595ae2949b46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AD=A6=E7=94=B0=20=E6=86=B2=E5=A4=AA=E9=83=8E?=
 <takeda@youmind.jp>
Date: Sun, 11 Oct 2026 22:55:21 +0900
Subject: [PATCH] =?UTF-8?q?mysqli=20=E3=82=92=E5=8E=9F=E6=96=87=E3=81=AE?=
 =?UTF-8?q?=E5=A4=89=E6=9B=B4=E3=81=AB=E8=BF=BD=E5=BE=93=20(2=E3=83=95?=
 =?UTF-8?q?=E3=82=A1=E3=82=A4=E3=83=AB)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 reference/mysqli/mysqli/quote-string.xml      | 174 ++++++++++++++++++
 .../mysqli/mysqli/real-escape-string.xml      |  39 ++--
 2 files changed, 199 insertions(+), 14 deletions(-)
 create mode 100644 reference/mysqli/mysqli/quote-string.xml

diff --git a/reference/mysqli/mysqli/quote-string.xml b/reference/mysqli/mysqli/quote-string.xml
new file mode 100644
index 0000000000..e11d69edd3
--- /dev/null
+++ b/reference/mysqli/mysqli/quote-string.xml
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 01175bf92d73d885dc5a19793bc1d0c5d1a75bac Maintainer: KentarouTakeda 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>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>
+   SQL 文中で使用できる正しい形式の SQL 文字列リテラルを作成します。
+   指定した文字列は、接続で使用している現在の文字セットを考慮して
+   <methodname>mysqli::real_escape_string</methodname> と同じ方法でエスケープされたうえで、
+   シングルクォートで囲まれます。
+   そのため、戻り値にはクォートを追加せず、そのままクエリに埋め込む必要があります。
+  </simpara>
+  <simpara>
+   <methodname>mysqli::real_escape_string</methodname> とは異なり、
+   接続で <literal>NO_BACKSLASH_ESCAPES</literal> SQL モードが有効になっている場合でも、
+   結果を安全に使えます。
+  </simpara>
+  <caution>
+   <title>セキュリティ: デフォルトの文字セット</title>
+   <simpara>
+    文字セットは、サーバーレベルか API 関数
+    <function>mysqli_set_charset</function> のどちらかで設定しないと、
+    <function>mysqli_quote_string</function> に反映されません。詳細は
+    <link linkend="mysqlinfo.concepts.charset">文字セットの概念</link>
+    を参照ください。
+   </simpara>
+  </caution>
+  <note>
+   <simpara>
+    クォートが適しているのは、文字列リテラルだけです。
+    テーブル名やカラム名などの識別子は、クォートしても安全にはなりません。
+    可能な限り、<link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメント</link>
+    を使い、クエリを手動で組み立てるのは避けてください。
+   </simpara>
+  </note>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    &mysqli.link.description;
+    <varlistentry>
+     <term><parameter>string</parameter></term>
+     <listitem>
+      <simpara>
+       エスケープしてクォートで囲む文字列。
+      </simpara>
+      <simpara>
+       エンコードされる文字は
+       <literal>NUL (ASCII 0)</literal>、
+       <literal>\n</literal>、<literal>\r</literal>、
+       <literal>\</literal>、<literal>'</literal>、
+       <literal>"</literal>、および
+       <keycombo action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>
+       です。
+       接続で <literal>NO_BACKSLASH_ESCAPES</literal> SQL モードが有効になっている場合は、
+       <literal>'</literal> だけを 2 つ重ねてエンコードします。
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   シングルクォートで囲んだ、エスケープ済みの文字列を返します。
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><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";
+
+/* $city はクォートされ、クエリは動作します。*/
+$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);
+
+/* このクエリは失敗します。なぜなら、$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";
+
+/* $city はクォートされ、クエリは動作します。*/
+$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));
+
+/* このクエリは失敗します。なぜなら、$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 8006d0ac29..8f78f5d540 100644
--- a/reference/mysqli/mysqli/real-escape-string.xml
+++ b/reference/mysqli/mysqli/real-escape-string.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fc174e8d6162091550edde46159917ee7e5a2e73 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 01175bf92d73d885dc5a19793bc1d0c5d1a75bac Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="mysqli.real-escape-string" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -23,22 +23,32 @@
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
   </methodsynopsis>
   <para>
-   この関数を使用して、SQL 文中で使用できる正当な形式の SQL 文字列を作成します。
+   この関数を使用して、SQL 文中で使用できる正しい形式の SQL 文字列を作成します。
    文字列 <literal>escapestr</literal> が、エスケープされた
    SQL に変換されます。その際、接続で使用している現在の文字セットが考慮されます。
   </para>
   <caution>
    <title>セキュリティ: デフォルトの文字セット</title>
    <para>
-    サーバーレベルで設定するなり API 関数
-    <function>mysqli_set_charset</function> を使うなりして、
-    文字セットを明示しておく必要があります。この文字セットが
-    <function>mysqli_real_escape_string</function>
-    に影響を及ぼします。詳細は
+    文字セットは、サーバーレベルか API 関数
+    <function>mysqli_set_charset</function> のどちらかで設定しないと、
+    <function>mysqli_real_escape_string</function> に反映されません。詳細は
     <link linkend="mysqlinfo.concepts.charset">文字セットの概念</link>
     を参照ください。
    </para>
   </caution>
+  <warning>
+   <simpara>
+    この関数は結果をクォートで囲まないため、呼び出し側で囲む必要があります。
+    接続で <literal>NO_BACKSLASH_ESCAPES</literal> SQL モードが有効になっている場合、
+    エスケープされるのはシングルクォート (<literal>'</literal>) だけです。
+    そのため、値をダブルクォート (<literal>"</literal>) で囲むと、
+    文字列が途中で終わってしまい、SQL インジェクションにつながるおそれがあります。
+    代わりに <link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメント</link>
+    を使ってください。それができない場合は、結果を常にシングルクォートで囲む
+    <methodname>mysqli::quote_string</methodname> を使ってください。
+   </simpara>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -52,7 +62,7 @@
       <para>
        エスケープする文字列。
       </para>
-      <para>
+      <simpara>
        エンコードされる文字は
        <literal>NUL (ASCII 0)</literal>、
        <literal>\n</literal>、<literal>\r</literal>、
@@ -60,7 +70,9 @@
        <literal>"</literal>、および
        <keycombo action='simul'><keycap>CTRL</keycap><keycap>Z</keycap></keycombo>
        です。
-      </para>
+       接続で <literal>NO_BACKSLASH_ESCAPES</literal> SQL モードが有効になっている場合は、
+       <literal>'</literal> だけを 2 つ重ねてエンコードします。
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -133,11 +145,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>