documentation/manual/ja/module_specs/Zend_Db_Statement.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20766 -->
   4 <sect1 id="zend.db.statement">
   5
   6     <title>Zend_Db_Statement</title>
   7
   8     <para>
   9         <xref linkend="zend.db.adapter" /> で説明した
  10         <methodname>fetchAll()</methodname> や <methodname>insert()</methodname>
  11         のような便利なメソッド以外にも、
  12         ステートメントオブジェクトを使用することで、
  13         より柔軟にクエリの実効や結果の取得ができるようになります。
  14         ここでは、ステートメントオブジェクトを取得してそのメソッドを使用する方法を説明します。
  15     </para>
  16
  17     <para>
  18         <classname>Zend_Db_Statement</classname> は、
  19         <ulink url="http://www.php.net/pdo">PHP Data Objects</ulink>
  20         拡張モジュールの PDOStatement オブジェクトをもとにしたものです。
  21     </para>
  22
  23     <sect2 id="zend.db.statement.creating">
  24
  25         <title>ステートメントの作成</title>
  26
  27         <para>
  28             通常は、ステートメントオブジェクトはデータベースアダプタクラスの
  29             <methodname>query()</methodname> メソッドの返り値として取得します。
  30             このメソッドは、任意の <acronym>SQL</acronym> 文を実行できます。
  31             最初の引数には <acronym>SQL</acronym> 文を指定し、
  32             オプションの二番目の引数には <acronym>SQL</acronym> 文中のプレースホルダを置き換える
  33             バインド変数の配列を指定します。
  34         </para>
  35
  36         <example id="zend.db.statement.creating.example1">
  37             <title>query() による SQL ステートメントオブジェクトの作成</title>
  38             <programlisting language="php"><![CDATA[
  39 $stmt = $db->query(
  40             'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
  41             array('goofy', 'FIXED')
  42         );
  43 ]]></programlisting>
  44         </example>
  45
  46         <para>
  47             ステートメントオブジェクトは、準備された <acronym>SQL</acronym> 文に対して
  48             変数の値をバインドして一度実行したものに対応します。
  49             そのステートメントが SELECT クエリあるいは何らかの結果セットを返すものであった場合は、
  50             すでに結果を取得する準備ができています。
  51         </para>
  52
  53         <para>
  54             ステートメントオブジェクトをコンストラクタから作成することもできますが、
  55             あまり一般的ではありません。このオブジェクトを作成するための
  56             ファクトリメソッドはないので、特定のステートメントクラスを読み込んで
  57             そのコンストラクタをコールすることになります。
  58             コンストラクタの最初の引数にはアダプタオブジェクトを指定し、
  59             二番目の引数には <acronym>SQL</acronym> 文を文字列で指定します。
  60             このステートメントは、準備されただけでまだ実行されていない状態となります。
  61         </para>
  62
  63         <example id="zend.db.statement.creating.example2">
  64             <title>SQL ステートメントのコンストラクタの使用</title>
  65             <programlisting language="php"><![CDATA[
  66 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  67
  68 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  69 ]]></programlisting>
  70         </example>
  71
  72     </sect2>
  73
  74     <sect2 id="zend.db.statement.executing">
  75
  76         <title>ステートメントの実行</title>
  77
  78         <para>
  79             ステートメントをコンストラクタから作成した場合や、
  80             一度実行したステートメントをもう一度実行したい場合などは、
  81             ステートメントオブジェクトを自分で実行する必要があります。
  82             その場合は、ステートメントオブジェクトの <methodname>execute()</methodname>
  83             メソッドを使用します。このメソッドに渡す引数は、
  84             ステートメント中のプレースホルダにバインドする変数の値の配列となります。
  85         </para>
  86
  87         <para>
  88             <emphasis>位置指定によるパラメータ</emphasis>、
  89             つまりクエスチョンマーク (<emphasis>?</emphasis>) でパラメータを指定している場合は、
  90             バインドする値は通常の配列で渡します。
  91         </para>
  92
  93         <example id="zend.db.statement.executing.example1">
  94             <title>位置指定パラメータによるステートメントの実行</title>
  95             <programlisting language="php"><![CDATA[
  96 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  97
  98 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  99
 100 $stmt->execute(array('goofy', 'FIXED'));
 101 ]]></programlisting>
 102         </example>
 103
 104         <para>
 105             <emphasis>名前つきパラメータ</emphasis>、
 106             つまり先頭にコロン (<emphasis>:</emphasis>) をつけた識別子で
 107             パラメータを指定している場合は、バインドする値を連想配列で渡します。
 108             配列のキーが、パラメータの名前に対応します。
 109         </para>
 110
 111         <example id="zend.db.statement.executing.example2">
 112             <title>名前つきパラメータによるステートメントの実行</title>
 113             <programlisting language="php"><![CDATA[
 114 $sql = 'SELECT * FROM bugs WHERE ' .
 115        'reported_by = :reporter AND bug_status = :status';
 116
 117 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
 118
 119 $stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
 120 ]]></programlisting>
 121         </example>
 122
 123         <para>
 124             <acronym>PDO</acronym> のステートメントは位置指定パラメータと名前つきパラメータの両方をサポートしています。
 125             しかし、ひとつの <acronym>SQL</acronym> の中で両方を使用することはできません。
 126             <classname>Zend_Db_Statement</classname> クラスの中には <acronym>PDO</acronym> を使用していないものもありますが、
 127             それらの中にはいずれか一種類の形式のパラメータしかサポートしないものもあるかもしれません。
 128         </para>
 129
 130     </sect2>
 131
 132     <sect2 id="zend.db.statement.fetching">
 133
 134         <title>SELECT 文からの結果の取得</title>
 135
 136         <para>
 137             ステートメントオブジェクトのメソッドをコールすることで、
 138             <acronym>SQL</acronym> 文の結果セットから行を取得できます。
 139             SELECT、SHOW、DESCRIBE そして EXPLAIN
 140             などのステートメントが結果セットを返します。
 141             INSERT、UPDATE そして DELETE などのステートメントは結果セットを返しません。
 142             後者のような <acronym>SQL</acronym> 文も <classname>Zend_Db_Statement</classname> で実行できますが、
 143             その結果から行を取得するメソッドをコールすることはできません。
 144         </para>
 145
 146         <sect3 id="zend.db.statement.fetching.fetch">
 147
 148             <title>結果セットからの単一の行の取得</title>
 149
 150             <para>
 151                 結果セットから単一の行を取得するには、ステートメントオブジェクトの
 152                 <methodname>fetch()</methodname> メソッドを使用します。
 153                 このメソッドの三つの引数は、いずれも省略可能です。
 154             </para>
 155
 156             <itemizedlist>
 157                 <listitem>
 158                     <para>
 159                         最初の引数は
 160                         <emphasis>取得形式</emphasis>
 161                         を指定します。これは、返り値の構造を決めるものです。
 162                         ここで指定できる値と対応する返り値については
 163                         <xref linkend="zend.db.adapter.select.fetch-mode" />
 164                         を参照ください。
 165                     </para>
 166                 </listitem>
 167                 <listitem>
 168                     <para>
 169                         二番目の引数で指定するのは、
 170                         <emphasis>カーソルの種類</emphasis>
 171                         です。デフォルトは Zend_Db::FETCH_ORI_NEXT
 172                         で、<methodname>fetch()</methodname> をコールするたびに
 173                         <acronym>RDBMS</acronym> が返す順で次の行を返すというものです。
 174                     </para>
 175                 </listitem>
 176                 <listitem>
 177                     <para>
 178                         三番目の引数で指定するのは
 179                         <emphasis>オフセット</emphasis> です。
 180                         カーソルの種類が Zend_Db::FETCH_ORI_ABS の場合、
 181                         これは結果セットの中の何行目を返すのかを表します。
 182                         カーソルの種類が Zend_Db::FETCH_ORI_REL の場合、
 183                         これは直前に <methodname>fetch()</methodname>
 184                         をコールした際の位置からの相対位置を表します。
 185                     </para>
 186                 </listitem>
 187             </itemizedlist>
 188
 189             <para>
 190                 すでに結果セットのすべての行が取得済みである場合は
 191                 <methodname>fetch()</methodname> は <constant>FALSE</constant> を返します。
 192             </para>
 193
 194             <example id="zend.db.statement.fetching.fetch.example">
 195                 <title>ループ内での fetch() の使用</title>
 196                 <programlisting language="php"><![CDATA[
 197 $stmt = $db->query('SELECT * FROM bugs');
 198
 199 while ($row = $stmt->fetch()) {
 200     echo $row['bug_description'];
 201 }
 202 ]]></programlisting>
 203             </example>
 204
 205             <para>
 206                 <ulink url="http://www.php.net/PDOStatement-fetch">PDOStatement::fetch()</ulink>
 207                 のマニュアルも参照ください。
 208             </para>
 209
 210         </sect3>
 211
 212         <sect3 id="zend.db.statement.fetching.fetchall">
 213
 214             <title>結果セット全体の取得</title>
 215
 216             <para>
 217                 結果セットのすべての行を一度に取得するには、
 218                 <methodname>fetchAll()</methodname> メソッドを使用します。
 219                 これは、ループ内で <methodname>fetch()</methodname>
 220                 メソッドを繰り返し使用してすべての行を配列に格納するのと同じことです。
 221                 <methodname>fetchAll()</methodname> メソッドにはふたつの引数を指定できます。
 222                 最初の引数は、先ほど説明したのと同じ取得形式です。
 223                 二番目の引数は、返すカラム番号を指定します。これは最初の引数が
 224                 Zend_Db::FETCH_COLUMN である場合に使用します。
 225             </para>
 226
 227             <example id="zend.db.statement.fetching.fetchall.example">
 228                 <title>fetchAll() の使用法</title>
 229                 <programlisting language="php"><![CDATA[
 230 $stmt = $db->query('SELECT * FROM bugs');
 231
 232 $rows = $stmt->fetchAll();
 233
 234 echo $rows[0]['bug_description'];
 235 ]]></programlisting>
 236             </example>
 237
 238             <para>
 239                 <ulink url="http://www.php.net/PDOStatement-fetchAll">PDOStatement::fetchAll()</ulink>
 240                 のマニュアルも参照ください。
 241             </para>
 242
 243         </sect3>
 244
 245         <sect3 id="zend.db.statement.fetching.fetch-mode">
 246
 247             <title>取得形式の変更</title>
 248
 249             <para>
 250                 デフォルトでは、ステートメントオブジェクトが結果セットの行を返す形式は連想配列で、
 251                 カラム名とそのカラムの値を関連付けたものとなります。
 252                 結果を別の形式で返すように指定する方法は、アダプタクラスの場合と同じです。
 253                 ステートメントオブジェクトの <methodname>setFetchMode()</methodname>
 254                 メソッドで、取得形式を指定します。指定できる値は、<classname>Zend_Db</classname> クラスの定数
 255                 FETCH_ASSOC、FETCH_NUM、FETCH_BOTH、FETCH_COLUMN そして FETCH_OBJ です。
 256                 これらについての詳細は
 257                 <xref linkend="zend.db.adapter.select.fetch-mode" /> を参照ください。
 258                 これを指定すると、それ以降の <methodname>fetch()</methodname> メソッドや
 259                 <methodname>fetchAll()</methodname> メソッドでその形式を使用するようになります。
 260             </para>
 261
 262             <example id="zend.db.statement.fetching.fetch-mode.example">
 263                 <title>取得形式の設定</title>
 264                 <programlisting language="php"><![CDATA[
 265 $stmt = $db->query('SELECT * FROM bugs');
 266
 267 $stmt->setFetchMode(Zend_Db::FETCH_NUM);
 268
 269 $rows = $stmt->fetchAll();
 270
 271 echo $rows[0][0];
 272 ]]></programlisting>
 273             </example>
 274
 275             <para>
 276                 <ulink url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>
 277                 のマニュアルも参照ください。
 278             </para>
 279
 280         </sect3>
 281
 282         <sect3 id="zend.db.statement.fetching.fetchcolumn">
 283
 284             <title>結果セットからの単一のカラムの取得</title>
 285
 286             <para>
 287                 結果セットの次の行から単一のカラムの値を取得するには
 288                 <methodname>fetchColumn()</methodname> を使用します。
 289                 取得するカラムの位置を表すインデックスを引数で指定します。
 290                 省略した場合のデフォルトは 0 となります。このメソッドは、
 291                 スカラー値を返します。もし結果セットのすべての行が既に取得済みである場合は
 292                 <constant>FALSE</constant> を返します。
 293             </para>
 294
 295             <para>
 296                 このメソッドの動作は、アダプタクラスの
 297                 <methodname>fetchCol()</methodname> メソッドとは異なることに注意しましょう。
 298                 ステートメントクラスの <methodname>fetchColumn()</methodname> メソッドは、
 299                 単一の行の単一の値を返します。アダプタの
 300                 <methodname>fetchCol()</methodname> メソッドは、値の配列を返します。
 301                 これは、結果セットのすべての行の、最初のカラムの値をまとめたものです。
 302             </para>
 303
 304             <example id="zend.db.statement.fetching.fetchcolumn.example">
 305                 <title>fetchColumn() の使用法</title>
 306                 <programlisting language="php"><![CDATA[
 307 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 308
 309 $bug_status = $stmt->fetchColumn(2);
 310 ]]></programlisting>
 311             </example>
 312
 313             <para>
 314                 <ulink url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>
 315                 のマニュアルも参照ください。
 316             </para>
 317
 318         </sect3>
 319
 320         <sect3 id="zend.db.statement.fetching.fetchobject">
 321
 322             <title>オブジェクト形式での行の取得</title>
 323
 324             <para>
 325                 結果セットの行をオブジェクトとして取得するには
 326                 <methodname>fetchObject()</methodname> を使用します。このメソッドの引数は二つで、
 327                 いずれも省略可能です。最初の引数には、返り値のオブジェクトのクラス名を指定します。
 328                 デフォルトは 'stdClass' です。二番目の引数には配列を指定します。
 329                 これは、最初の引数で指定したクラスのコンストラクタに渡す引数となります。
 330             </para>
 331
 332             <example id="zend.db.statement.fetching.fetchobject.example">
 333                 <title>fetchObject() の使用法</title>
 334                 <programlisting language="php"><![CDATA[
 335 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 336
 337 $obj = $stmt->fetchObject();
 338
 339 echo $obj->bug_description;
 340 ]]></programlisting>
 341             </example>
 342
 343             <para>
 344                 <ulink url="http://www.php.net/PDOStatement-fetchObject">PDOStatement::fetchObject()</ulink>
 345                 のマニュアルも参照ください。
 346             </para>
 347
 348         </sect3>
 349
 350     </sect2>
 351
 352     <!--
 353       @todo: binding parameters is not working yet.
 354
 355     <sect2 id="zend.db.statement.binding-param">
 356
 357         <title>Binding PHP Variables to Parameters</title>
 358
 359         <para>
 360         </para>
 361
 362         <example id="zend.db.statement.binding-param.example">
 363             <title>Binding parameters from PHP variables</title>
 364             <programlisting language="php"><![CDATA[
 365 ]]></programlisting>
 366         </example>
 367
 368         <para>
 369             See also <ulink url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>.
 370         </para>
 371
 372     </sect2>
 373     -->
 374
 375     <!--
 376       @todo: binding columns is not working yet.
 377     <sect2 id="zend.db.statement.binding-column">
 378
 379         <title>Binding PHP Variables to Query Results</title>
 380
 381         <para>
 382         </para>
 383
 384         <example id="zend.db.statement.binding-column.example">
 385             <title>Binding results to PHP variables</title>
 386             <programlisting language="php"><![CDATA[
 387 ]]></programlisting>
 388         </example>
 389
 390         <para>
 391             See also <ulink url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>.
 392         </para>
 393
 394     </sect2>
 395     -->
 396
 397 </sect1>