svn: /phpdoc/ja/trunk/reference/sqlite3/sqlite3/ setauthorizer.xml

Added: phpdoc/ja/trunk/reference/sqlite3/sqlite3/setauthorizer.xml
===================================================================
--- phpdoc/ja/trunk/reference/sqlite3/sqlite3/setauthorizer.xml	                        (rev 0)
+++ phpdoc/ja/trunk/reference/sqlite3/sqlite3/setauthorizer.xml	2020-11-24 02:03:34 UTC (rev 351558)
@@ -0,0 +1,262 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- EN-Revision: 351547 Maintainer: mumumu Status: working -->
+
+<refentry xml:id="sqlite3.setauthorizer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>SQLite3::setAuthorizer</refname>
+  <refpurpose>SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="oop">
+   <modifier>public</modifier>
+   <type>bool</type><methodname>SQLite3::setAuthorizer</methodname>
+   <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   SQLite に対して毎回アクション(読み取り、削除、更新など)
+   が実行される度に呼び出されるコールバックを設定します。
+   これは信頼できないソースがSQL文を準備する時に、
+   自分たちが許可していないデータにアクセスさせないとか、
+   データベースに損害を与える不正なSQL文を実行させないといった用途に使います。
+   たとえば、アプリケーションはデータベースの評価の際は
+   任意のSQL文の実行を許可しています。しかし、
+   データベースに対する変更は許可したくありません。
+   ユーザーが入力したSQL文が準備される間に、
+   authorizer が割って入り、SELECT 文以外のSQL文を許可しないようにできます。
+  </para>
+  <para>
+   authorizer コールバックは、
+   SQLite が文を準備するたびに複数回呼ばれる可能性がありmす。
+   <literal>SELECT</literal> や
+   <literal>UPDATE</literal> 文は
+   個別のカラムが読み取られたり、更新されたりするたびに
+   authorizer を呼び出します。
+  </para>
+  <para>
+   authorizer は引数を5つまで指定して呼び出すことが出来ます。
+   最初の引数は常に与えられます。
+   これは <literal>SQLite3</literal> の定数に一致する
+   <type>int</type> の値(アクションコード) です。
+   それ以外の引数は、アクションによっては与えられないことがあります。
+   以下の表が、アクションに応じた2番目と3番目の引数に関する説明を記しています:
+   <table>
+    <title>アクションコードと引数の一覧</title>
+    <tgroup cols="3">
+     <thead>
+      <row>
+       <entry>アクション</entry>
+       <entry>第2引数</entry>
+       <entry>第3引数</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row><entry><constant>sqlite3::create_index</constant></entry><entry>index name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::create_table</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::create_temp_index</constant></entry><entry>index name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::create_temp_table</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::create_temp_trigger</constant></entry><entry>trigger name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::create_temp_view</constant></entry><entry>view name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::create_trigger</constant></entry><entry>trigger name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::create_view</constant></entry><entry>view name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::delete</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::drop_index</constant></entry><entry>index name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::drop_table</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::drop_temp_index</constant></entry><entry>index name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::drop_temp_table</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::drop_temp_trigger</constant></entry><entry>trigger name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::drop_temp_view</constant></entry><entry>view name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::drop_trigger</constant></entry><entry>trigger name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::drop_view</constant></entry><entry>view name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::insert</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::pragma</constant></entry><entry>pragma name</entry><entry>first argument passed to the pragma, or &null;</entry></row>
+      <row><entry><constant>sqlite3::read</constant></entry><entry>table name</entry><entry>column name</entry></row>
+      <row><entry><constant>sqlite3::select</constant></entry><entry>&null;</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::transaction</constant></entry><entry>operation</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::update</constant></entry><entry>table name</entry><entry>column name</entry></row>
+      <row><entry><constant>sqlite3::attach</constant></entry><entry>filename</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::detach</constant></entry><entry>database name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::alter_table</constant></entry><entry>database name</entry><entry>table name</entry></row>
+      <row><entry><constant>sqlite3::reindex</constant></entry><entry>index name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::analyze</constant></entry><entry>table name</entry><entry>&null;</entry></row>
+      <row><entry><constant>sqlite3::create_vtable</constant></entry><entry>table name</entry><entry>module name</entry></row>
+      <row><entry><constant>sqlite3::drop_vtable</constant></entry><entry>table name</entry><entry>module name</entry></row>
+      <row><entry><constant>sqlite3::function</constant></entry><entry>&null;</entry><entry>function name</entry></row>
+      <row><entry><constant>sqlite3::savepoint</constant></entry><entry>operation</entry><entry>savepoint name</entry></row>
+      <row><entry><constant>sqlite3::recursive</constant></entry><entry>&null;</entry><entry>&null;</entry></row>
+     </tbody>
+    </tgroup>
+   </table>
+  </para>
+  <para>
+   5番目の引数は、適切な場合にだけ指定する(<literal>"main"</literal>,
+   <literal>"temp"</literal>, などの) データベースの名前です。
+  </para>
+  <para>
+   <!-- to be translated -->
+   The 6th parameter to the authorizer callback is the name of the inner-most trigger or
+   view that is responsible for the access attempt or &null; if this access attempt is
+   directly from top-level SQL code.
+  </para>
+  <para>
+   コールバックが <constant>SQLite3::OK</constant>
+   を返すと、操作のリクエストが承認されたことになります。
+   コールバックが <constant>SQLite3::DENY</constant>
+   を返すと、authorizer を動かした呼び出しは失敗し、
+   なぜアクセスが失敗したのかを説明するメッセージが残ります。
+  </para>
+  <para>
+   <!-- to be translated -->
+   If the action code is <constant>SQLite3::READ</constant> and the callback returns
+   <constant>SQLite3::IGNORE</constant> then the prepared statement statement is
+   constructed to substitute a &null; value in place of the table column that would have
+   been read if <constant>SQLite3::OK</constant> had been returned. The
+   <constant>SQLite3::IGNORE</constant> return can be used to deny an untrusted user
+   access to individual columns of a table.
+  </para>
+  <para>
+   テーブルを <literal>SELECT</literal> 文で参照しているが、
+   そのテーブルからカラムの値を抜き出さない場合
+   (たとえば、<literal>"SELECT count(*) FROM table"</literal>
+   のようなクエリの場合)、
+   <constant>SQLite3::READ</constant> の authorizer コールバックは
+   カラムの情報が空文字列になった状態で一度だけ呼び出されます。
+  </para>
+  <para>
+   アクションコードが <constant>SQLite3::DELETE</constant> で、
+   さらにコールバックが
+   <constant>SQLite3::IGNORE</constant> を返した場合、
+   DELETE の操作は継続しますが、truncate による最適化は無効になります。
+   この場合、全ての行は個別に削除されます。
+  </para>
+  <para>
+   接続ひとつにつき、authorizer ひとつだけがデータベースに存在できます。
+   <methodname>SQLite3::setAuthorizer</methodname> が呼び出されるたびに、
+   以前の呼び出しは上書きされます。
+   &null; をコールバックに指定することで、
+   authorizer を無効に出来ます。authorizer はデフォルトで無効になっています。
+  </para>
+  <para>
+   authorizer コールバックは、コールバックを呼び出すデータベース接続に対していかなる変更もしてはいけません。
+  </para>
+  <para>
+   authorizer はSQL文が準備される時にだけ呼び出されることに注意して下さい。
+   実行時ではありません。
+  </para>
+  <para>
+   さらなる詳細は
+   <link xlink:href="&url.sqlite;c3ref/set_authorizer.html">SQLite3 のドキュメント</link> を参照して下さい。
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>callback</parameter></term>
+    <listitem>
+     <para>
+      呼び出される <type>callable</type>。
+     </para>
+     <para>
+      &null; が渡されると、
+      現在の authorizer のコールバックが無効になります。
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.success;
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   このメソッドは例外をスローしません。
+   しかし、いったん authorizer が有効になり、不正な値を返すと、
+   SQL文の準備がエラー
+   (または例外。
+   <methodname>SQLite3::enableExceptions</methodname> の使い方によります)
+   を発生させるようになります。
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><methodname>SQLite3::setAuthorizer</methodname> の例</title>
+   <para>
+     この例は、読み取りだけを許可します。
+     さらに、<literal>users</literal> テーブルのいくつかのカラムだけを返します。
+     他のカラムは &null; で置き換えられます。
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$db = new SQLite3('data.sqlite');
+$db->exec('CREATE TABLE users (id, name, password);');
+$db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');
+
+$allowed_columns = ['id', 'name'];
+
+$db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
+    if ($action === SQLite3::READ) {
+        list($table, $column) = $args;
+
+        if ($table === 'users' && in_array($column, $allowed_columns) {
+            return SQLite3::OK;
+        }
+
+        return SQLite3::IGNORE;
+    }
+
+    return SQLite3::DENY;
+});
+
+print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));
+]]>
+   </programlisting>
+
+   &example.outputs;
+   <screen>
+<![CDATA[
+Array
+(
+    [id] => 1
+    [name] => Pauline
+    [password] =>
+)
+]]>
+   </screen>
+  </example>
+ </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
+-->


Property changes on: phpdoc/ja/trunk/reference/sqlite3/sqlite3/setauthorizer.xml
___________________________________________________________________
Added: svn:keywords
## -0,0 +1 ##
+Id Rev Revision Date LastChangedDate LastChangedRevision Author LastChangedBy HeadURL URL
\ No newline at end of property