com doc/ja: Improve mysqli_query docs: reference/mysqli /mysqli/query.xml reference/mysqli/mysqli/real-query.xml
| From: | Yoshinari Takaoka | Date: | Wed, 24 Mar 2021 19:13:52 +0000 |
| Subject: | com doc/ja: Improve mysqli_query docs: reference/mysqli /mysqli/query.xml reference/mysqli/mysqli/real-query.xml | ||
| Groups: | php.doc.ja | ||
| Request: | Send a blank email to doc-ja+get-6279@lists.php.net to get a copy of this message | ||
Commit: 794c4935899f3f3019b51bd0be2f07d89f637633
Author: Yoshinari Takaoka <mumumu@mumumu.org> Thu, 25 Mar 2021 04:13:52 +0900
Parents: 3fd5a3d04ff4d9e7d9277f4d1c8210f8c135d22a
Branches: master
Link: http://git.php.net/?p=doc/ja.git;a=commitdiff;h=794c4935899f3f3019b51bd0be2f07d89f637633
Log:
Improve mysqli_query docs
* Add a nice big SQL injection warning
* Break overlong breaks
* Rewrite result_mode explanation
* Simplify examples
* Add mysqli_prepare to see also
Closes GH-497.
Changed paths:
M reference/mysqli/mysqli/query.xml
M reference/mysqli/mysqli/real-query.xml
diff --git a/reference/mysqli/mysqli/query.xml b/reference/mysqli/mysqli/query.xml index 21f36550c4..35e22c35b2 100644 --- a/reference/mysqli/mysqli/query.xml +++ b/reference/mysqli/mysqli/query.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> -<!-- EN-Revision: 7e5d0d1bb69180c9de1992edf9613215c975fa57 Maintainer: takagi Status: ready --> +<!-- EN-Revision: 9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2 Maintainer: takagi Status: ready --> <!-- Credits: mumumu --> <refentry xml:id="mysqli.query" xmlns="http://docbook.org/ns/docbook"> <refnamediv> @@ -80,33 +80,50 @@ <para> クエリ文字列。 </para> - <para> - クエリ内のデータは <link - linkend="mysqli.real-escape-string">適切にエスケープ</link>. - する必要があります。 - </para> + <warning> + <title>セキュリティ上の注意: SQLインジェクション</title> + <para> + クエリに入力値を含める場合は、 + <link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメ +ント</link> を使うべきです。 + 使わない場合、 + データを適切にフォーマットし、 + 全ての文字列は <function>mysqli_real_escape_string</function> + を使ってエスケープしなければいけません。 + </para> + </warning> </listitem> </varlistentry> <varlistentry> <term><parameter>result_mode</parameter></term> <listitem> <para> - 定数 <constant>MYSQLI_USE_RESULT</constant> あるいは - <constant>MYSQLI_STORE_RESULT</constant> で、望みの挙動を指定します。 - デフォルトでは <constant>MYSQLI_STORE_RESULT</constant> - を使用します。 + MySQLサーバからどのように結果が返されたかを示す結果モード。 + 以下の3つの定数のうちのいずれかです。 + </para> + <para> + <constant>MYSQLI_STORE_RESULT</constant> (デフォルト) - + バッファリングされた結果セットを + <classname>mysqli_result</classname> オブジェクトとして返します。 </para> <para> - <literal>MYSQLI_USE_RESULT</literal> を使用すると、 - <function>mysqli_free_result</function> をコールするまでは - それ以降のコールはすべて <literal>Commands out of sync</literal> + <constant>MYSQLI_USE_RESULT</constant> - + バッファリングせずに結果セットを + <classname>mysqli_result</classname> オブジェクトとして返します。 + 取得されるのを待っているレコードが存在する限り、 + 接続はビジーとなり、<literal>Commands out of sync</literal> エラーを返します。 + このエラーを回避するには、全てのレコードをサーバから取得するか、 + 結果セットを <function>mysqli_free_result</function> + 関数をコールすることで捨てなければいけません。 </para> <para> - <constant>MYSQLI_ASYNC</constant> (mysqlnd で使用可能) - を使用すると、クエリを非同期実行できるようになります。 - このクエリの結果を取得するには - <function>mysqli_poll</function> を使用します。 + <constant>MYSQLI_ASYNC</constant> (mysqlnd で利用できます) - + クエリを非同期実行します。よって結果セットはすぐには返されません。 + このようなクエリから結果を取得するには、 + <function>mysqli_poll</function> を使います。 + <constant>MYSQLI_STORE_RESULT</constant> や + <constant>MYSQLI_USE_RESULT</constant> と組み合わせて使います。 </para> </listitem> </varlistentry> @@ -134,90 +151,59 @@ <programlisting role="php"> <![CDATA[ <?php -$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); - -/* 接続状況をチェックします */ -if ($mysqli->connect_errno) { - printf("Connect failed: %s\n", $mysqli->connect_error); - exit(); -} - -/* テーブルを作成します。これは結果セットを返しません */ -if ($mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) { - printf("Table myCity successfully created.\n"); -} -/* Select クエリを実行します。これは結果セットを返します */ -if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) { - printf("Select returned %d rows.\n", $result->num_rows); +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); - /* 結果セットを開放します */ - $result->close(); -} +/* 結果セットを返さないテーブルを作成します。*/ +$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City"); +printf("Table myCity successfully created.\n"); -/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */ -if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) { +/* 結果セットを返す SELECT 文 */ +$result = $mysqli->query("SELECT Name FROM City LIMIT 10"); +printf("Select returned %d rows.\n", $result->num_rows); - /* この結果セットが閉じられるまで、サーバーとやりとりする関数は - 一切実行できないことに注意しましょう。関数をコールすると、 - 'out of sync' エラーが発生します */ - if (!$mysqli->query("SET @a:='this will not work'")) { - printf("Error: %s\n", $mysqli->error); - } - $result->close(); -} +/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */ +$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT); -$mysqli->close(); -?> +/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで +サーバとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは +'out of sync' を返します */ +$mysqli->query("SET @a:='this will not work'"); ]]> </programlisting> <para>&style.procedural;</para> <programlisting role="php"> <![CDATA[ <?php -$link = mysqli_connect("localhost", "my_user", "my_password", "world"); - -/* 接続状況をチェックします */ -if (mysqli_connect_errno()) { - printf("Connect failed: %s\n", mysqli_connect_error()); - exit(); -} -/* テーブルを作成します。これは結果セットを返しません */ -if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) { - printf("Table myCity successfully created.\n"); -} - -/* Select クエリを実行します。これは結果セットを返します */ -if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) { - printf("Select returned %d rows.\n", mysqli_num_rows($result)); +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$link = mysqli_connect("localhost", "my_user", "my_password", "world"); - /* 結果セットを開放します */ - mysqli_free_result($result); -} +/* 結果セットを返さないテーブルを作成します。*/ +mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City"); +printf("Table myCity successfully created.\n"); -/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */ -if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) { +/* 結果セットを返す SELECT 文 */ +$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10"); +printf("Select returned %d rows.\n", mysqli_num_rows($result)); - /* この結果セットが閉じられるまで、サーバーとやりとりする関数は - 一切実行できないことに注意しましょう。関数をコールすると、 - 'out of sync' エラーが発生します */ - if (!mysqli_query($link, "SET @a:='this will not work'")) { - printf("Error: %s\n", mysqli_error($link)); - } - mysqli_free_result($result); -} +/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */ +$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT); -mysqli_close($link); -?> +/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで +サーバとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは +'out of sync' を返します */ +mysqli_query($link, "SET @a:='this will not work'"); ]]> </programlisting> - &examples.outputs; + &examples.outputs.similar; <screen> <![CDATA[ Table myCity successfully created. Select returned 10 rows. -Error: Commands out of sync; You can't run this command now + +Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in... ]]> </screen> </example> @@ -229,6 +215,7 @@ Error: Commands out of sync; You can't run this command now <simplelist> <member><function>mysqli_real_query</function></member> <member><function>mysqli_multi_query</function></member> + <member><function>mysqli_prepare</function></member> <member><function>mysqli_free_result</function></member> </simplelist> </para> diff --git a/reference/mysqli/mysqli/real-query.xml b/reference/mysqli/mysqli/real-query.xml index 88fb3442f8..66c2f939ea 100644 --- a/reference/mysqli/mysqli/real-query.xml +++ b/reference/mysqli/mysqli/real-query.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> -<!-- EN-Revision: 7e5d0d1bb69180c9de1992edf9613215c975fa57 Maintainer: takagi Status: ready --> +<!-- EN-Revision: 9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2 Maintainer: takagi Status: ready --> <!-- Credits: mumumu --> <refentry xml:id="mysqli.real-query" xmlns="http://docbook.org/ns/docbook"> <refnamediv> @@ -45,11 +45,17 @@ <para> クエリを表す文字列。 </para> - <para> - クエリ内のデータは <link - linkend="mysqli.real-escape-string">適切にエスケープ</link>. - する必要があります。 - </para> + <warning> + <title>セキュリティ上の注意: SQLインジェクション</title> + <para> + クエリに入力値を含める場合は、 + <link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメント</link> を使うべきです。 + 使わない場合、 + データを適切にフォーマットし、 + 全ての文字列は <function>mysqli_real_escape_string</function> + を使ってエスケープしなければいけません。 + </para> + </warning> </listitem> </varlistentry> </variablelist>
diff --git a/reference/mysqli/mysqli/query.xml b/reference/mysqli/mysqli/query.xml index 21f36550c4..35e22c35b2 100644 --- a/reference/mysqli/mysqli/query.xml +++ b/reference/mysqli/mysqli/query.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> -<!-- EN-Revision: 7e5d0d1bb69180c9de1992edf9613215c975fa57 Maintainer: takagi Status: ready --> +<!-- EN-Revision: 9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2 Maintainer: takagi Status: ready --> <!-- Credits: mumumu --> <refentry xml:id="mysqli.query" xmlns="http://docbook.org/ns/docbook"> <refnamediv> @@ -80,33 +80,50 @@ <para> クエリ文字列。 </para> - <para> - クエリ内のデータは <link - linkend="mysqli.real-escape-string">適切にエスケープ</link>. - する必要があります。 - </para> + <warning> + <title>セキュリティ上の注意: SQLインジェクション</title> + <para> + クエリに入力値を含める場合は、 + <link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメ +ント</link> を使うべきです。 + 使わない場合、 + データを適切にフォーマットし、 + 全ての文字列は <function>mysqli_real_escape_string</function> + を使ってエスケープしなければいけません。 + </para> + </warning> </listitem> </varlistentry> <varlistentry> <term><parameter>result_mode</parameter></term> <listitem> <para> - 定数 <constant>MYSQLI_USE_RESULT</constant> あるいは - <constant>MYSQLI_STORE_RESULT</constant> で、望みの挙動を指定します。 - デフォルトでは <constant>MYSQLI_STORE_RESULT</constant> - を使用します。 + MySQLサーバからどのように結果が返されたかを示す結果モード。 + 以下の3つの定数のうちのいずれかです。 + </para> + <para> + <constant>MYSQLI_STORE_RESULT</constant> (デフォルト) - + バッファリングされた結果セットを + <classname>mysqli_result</classname> オブジェクトとして返します。 </para> <para> - <literal>MYSQLI_USE_RESULT</literal> を使用すると、 - <function>mysqli_free_result</function> をコールするまでは - それ以降のコールはすべて <literal>Commands out of sync</literal> + <constant>MYSQLI_USE_RESULT</constant> - + バッファリングせずに結果セットを + <classname>mysqli_result</classname> オブジェクトとして返します。 + 取得されるのを待っているレコードが存在する限り、 + 接続はビジーとなり、<literal>Commands out of sync</literal> エラーを返します。 + このエラーを回避するには、全てのレコードをサーバから取得するか、 + 結果セットを <function>mysqli_free_result</function> + 関数をコールすることで捨てなければいけません。 </para> <para> - <constant>MYSQLI_ASYNC</constant> (mysqlnd で使用可能) - を使用すると、クエリを非同期実行できるようになります。 - このクエリの結果を取得するには - <function>mysqli_poll</function> を使用します。 + <constant>MYSQLI_ASYNC</constant> (mysqlnd で利用できます) - + クエリを非同期実行します。よって結果セットはすぐには返されません。 + このようなクエリから結果を取得するには、 + <function>mysqli_poll</function> を使います。 + <constant>MYSQLI_STORE_RESULT</constant> や + <constant>MYSQLI_USE_RESULT</constant> と組み合わせて使います。 </para> </listitem> </varlistentry> @@ -134,90 +151,59 @@ <programlisting role="php"> <![CDATA[ <?php -$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); - -/* 接続状況をチェックします */ -if ($mysqli->connect_errno) { - printf("Connect failed: %s\n", $mysqli->connect_error); - exit(); -} - -/* テーブルを作成します。これは結果セットを返しません */ -if ($mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) { - printf("Table myCity successfully created.\n"); -} -/* Select クエリを実行します。これは結果セットを返します */ -if ($result = $mysqli->query("SELECT Name FROM City LIMIT 10")) { - printf("Select returned %d rows.\n", $result->num_rows); +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); - /* 結果セットを開放します */ - $result->close(); -} +/* 結果セットを返さないテーブルを作成します。*/ +$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City"); +printf("Table myCity successfully created.\n"); -/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */ -if ($result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT)) { +/* 結果セットを返す SELECT 文 */ +$result = $mysqli->query("SELECT Name FROM City LIMIT 10"); +printf("Select returned %d rows.\n", $result->num_rows); - /* この結果セットが閉じられるまで、サーバーとやりとりする関数は - 一切実行できないことに注意しましょう。関数をコールすると、 - 'out of sync' エラーが発生します */ - if (!$mysqli->query("SET @a:='this will not work'")) { - printf("Error: %s\n", $mysqli->error); - } - $result->close(); -} +/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */ +$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT); -$mysqli->close(); -?> +/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで +サーバとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは +'out of sync' を返します */ +$mysqli->query("SET @a:='this will not work'"); ]]> </programlisting> <para>&style.procedural;</para> <programlisting role="php"> <![CDATA[ <?php -$link = mysqli_connect("localhost", "my_user", "my_password", "world"); - -/* 接続状況をチェックします */ -if (mysqli_connect_errno()) { - printf("Connect failed: %s\n", mysqli_connect_error()); - exit(); -} -/* テーブルを作成します。これは結果セットを返しません */ -if (mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City") === TRUE) { - printf("Table myCity successfully created.\n"); -} - -/* Select クエリを実行します。これは結果セットを返します */ -if ($result = mysqli_query($link, "SELECT Name FROM City LIMIT 10")) { - printf("Select returned %d rows.\n", mysqli_num_rows($result)); +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$link = mysqli_connect("localhost", "my_user", "my_password", "world"); - /* 結果セットを開放します */ - mysqli_free_result($result); -} +/* 結果セットを返さないテーブルを作成します。*/ +mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City"); +printf("Table myCity successfully created.\n"); -/* 大量のデータを取得する必要がある場合は MYSQLI_USE_RESULT を使用します */ -if ($result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT)) { +/* 結果セットを返す SELECT 文 */ +$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10"); +printf("Select returned %d rows.\n", mysqli_num_rows($result)); - /* この結果セットが閉じられるまで、サーバーとやりとりする関数は - 一切実行できないことに注意しましょう。関数をコールすると、 - 'out of sync' エラーが発生します */ - if (!mysqli_query($link, "SET @a:='this will not work'")) { - printf("Error: %s\n", mysqli_error($link)); - } - mysqli_free_result($result); -} +/* 大量のデータを取得しなければならない場合、MYSQLI_USE_RESULT を使います */ +$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT); -mysqli_close($link); -?> +/* 注意: 全てのレコードが取得されるか、結果セットがクローズされるまで +サーバとやりとりを行うあらゆる関数は実行できません。あらゆる呼び出しは +'out of sync' を返します */ +mysqli_query($link, "SET @a:='this will not work'"); ]]> </programlisting> - &examples.outputs; + &examples.outputs.similar; <screen> <![CDATA[ Table myCity successfully created. Select returned 10 rows. -Error: Commands out of sync; You can't run this command now + +Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in... ]]> </screen> </example> @@ -229,6 +215,7 @@ Error: Commands out of sync; You can't run this command now <simplelist> <member><function>mysqli_real_query</function></member> <member><function>mysqli_multi_query</function></member> + <member><function>mysqli_prepare</function></member> <member><function>mysqli_free_result</function></member> </simplelist> </para> diff --git a/reference/mysqli/mysqli/real-query.xml b/reference/mysqli/mysqli/real-query.xml index 88fb3442f8..66c2f939ea 100644 --- a/reference/mysqli/mysqli/real-query.xml +++ b/reference/mysqli/mysqli/real-query.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> -<!-- EN-Revision: 7e5d0d1bb69180c9de1992edf9613215c975fa57 Maintainer: takagi Status: ready --> +<!-- EN-Revision: 9c9b8f3e66ec3cb9a2e638bec8d2be2b8cfc0ff2 Maintainer: takagi Status: ready --> <!-- Credits: mumumu --> <refentry xml:id="mysqli.real-query" xmlns="http://docbook.org/ns/docbook"> <refnamediv> @@ -45,11 +45,17 @@ <para> クエリを表す文字列。 </para> - <para> - クエリ内のデータは <link - linkend="mysqli.real-escape-string">適切にエスケープ</link>. - する必要があります。 - </para> + <warning> + <title>セキュリティ上の注意: SQLインジェクション</title> + <para> + クエリに入力値を含める場合は、 + <link linkend="mysqli.quickstart.prepared-statements">プリペアドステートメント</link> を使うべきです。 + 使わない場合、 + データを適切にフォーマットし、 + 全ての文字列は <function>mysqli_real_escape_string</function> + を使ってエスケープしなければいけません。 + </para> + </warning> </listitem> </varlistentry> </variablelist>