documentation/manual/ru/module_specs/Zend_Db_Statement.xml

   1 <sect1 id="zend.db.statement">
   2
   3     <title>Zend_Db_Statement</title>
   4
   5     <para>
   6         В дополнение к удобным методам, таким, как <code>fetchAll()</code> и
   7         <code>insert()</code>, документированным в
   8         <xref linkend="zend.db.adapter" />, вы можете использовать объект
   9         оператора для того, чтобы восспользоваться
  10         бOльшим количеством опций запуска запросов и
  11         получения результатов запроса. Этот раздел описывает, как получить
  12         экземпляр объекта оператора и как использовать его методы.
  13     </para>
  14
  15     <para>
  16         Zend_Db_Statement основан на объекте PDOStatement в расширении <ulink url="http://www.php.net/pdo">PDO</ulink>.
  17     </para>
  18
  19     <sect2 id="zend.db.statement.creating">
  20
  21         <title>Создание оператора</title>
  22
  23         <para>
  24             Обычно объект оператора возвращается методом <code>query()</code>
  25             класса адаптера БД. Этот метод является основным средством
  26             подготовки любых операторов SQL. Первым аргументом является строка,
  27             содержащая оператор SQL. Опциональный второй аргумент - массив
  28             значений для подстановки вместо меток заполнения в строке SQL.
  29         </para>
  30
  31         <example id="zend.db.statement.creating.example1">
  32             <title>Создание объекта оператора SQL с помощью query()</title>
  33             <programlisting language="php"><![CDATA[
  34 $stmt = $db->query(
  35             'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
  36             array('goofy', 'FIXED')
  37         );
  38 ]]>
  39             </programlisting>
  40         </example>
  41
  42         <para>
  43             Объект оператора соответствует оператору SQL, который был
  44             подготовлен и выполнен с заданными значениями для связки. Если
  45             оператор был запросом SELECT или любым другим типом оператора,
  46             который возвращает результат, то он уже готов для извлечения
  47             результатов.
  48         </para>
  49
  50         <para>
  51             Вы можете создать оператор с помощью его конструктора, но это менее
  52             типичный вариант использования. Не существует метода-фабрики для
  53             создания этого объекта, поэтому нужно загружать определенный
  54             класс оператора и вызывать его конструктор. Передавайте объект
  55             адаптера в качестве первого аргумента и строку, содержащую оператор
  56             SQL в качестве второго. Теперь оператор подготовлен, но еще не
  57             выполнен.
  58         </para>
  59
  60         <example id="zend.db.statement.creating.example2">
  61             <title>Using a SQL statement constructor</title>
  62             <programlisting language="php"><![CDATA[
  63 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  64
  65 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  66 ]]>
  67             </programlisting>
  68         </example>
  69
  70     </sect2>
  71
  72     <sect2 id="zend.db.statement.executing">
  73
  74         <title>Выполнение оператора</title>
  75
  76         <para>
  77             Вам нужно выполнять оператор самостоятельно, если создали его объект
  78             с помощью его конструктора или хотите запустить один и тот же
  79             оператор несколько раз. Используйте метод <code>execute()</code>
  80             объекта оператора. Его единственным аргументом является массив
  81             значений для связки с метками заполнения в операторе.
  82         </para>
  83
  84         <para>
  85             Если вы используете <emphasis>позиционные параметры</emphasis> - те,
  86             которые помечаются знаками вопроса (<code>?</code>), - то передавайте значения для связки в простом массиве.
  87         </para>
  88
  89         <example id="zend.db.statement.executing.example1">
  90             <title>Выполнение оператора с позиционными параметрами</title>
  91             <programlisting language="php"><![CDATA[
  92 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  93
  94 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  95
  96 $stmt->execute(array('goofy', 'FIXED'));
  97 ]]>
  98             </programlisting>
  99         </example>
 100
 101         <para>
 102             Если вы используете <emphasis>именованные параметры</emphasis> - те,
 103             что указываются через строковой идентификатор с двоеточием
 104             (<code>:</code>) в начале, - то передавайте значения для связки в
 105             ассоциативном массиве. Ключи этого массива должны соответствовать
 106             именам параметров.
 107         </para>
 108
 109         <example id="zend.db.statement.executing.example2">
 110             <title>Выполнение оператора с именованными параметрами</title>
 111             <programlisting language="php"><![CDATA[
 112 $sql = 'SELECT * FROM bugs WHERE ' .
 113        'reported_by = :reporter AND bug_status = :status';
 114
 115 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
 116
 117 $stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
 118 ]]>
 119             </programlisting>
 120         </example>
 121
 122         <para>
 123             Операторы PDO поддерживают как позиционные, так именованные
 124             параметры по отдельности, но не вместе в одном операторе SQL.
 125             Некоторые классы Zend_Db_Statement для не-PDO расширений могут
 126             поддерживать только один тип параметров.
 127         </para>
 128
 129     </sect2>
 130
 131     <sect2 id="zend.db.statement.fetching">
 132
 133         <title>Извлечение результатов выполнения оператора <code>SELECT</code></title>
 134
 135         <para>
 136             Вы можете вызывать методы объекта оператора для получения строк из
 137             SQL-операторов, которые возвращают наборы результатов. SELECT, SHOW,
 138             DESCRIBE и EXPLAIN являются примерами операторов, которые генерируют
 139             наборы результатов, а INSERT, UPDATE и DELETE - примерами
 140             операторов, которые не возвращают наборы результатов. Вы можете
 141             выполнять последние операторы, используя Zend_Db_Statement, но не
 142             можете вызывать методы для получения строк из результатов их
 143             выполнения.
 144         </para>
 145
 146         <sect3 id="zend.db.statement.fetching.fetch">
 147
 148             <title>Извлечение одной строки из набора результатов</title>
 149
 150             <para>
 151                 Для извлечения одной строки из набора результатов используйте
 152                 метод <code>fetch()</code> объекта оператора. Все три аргумента
 153                 этого метода являются опциональными:
 154             </para>
 155
 156             <itemizedlist>
 157                 <listitem>
 158                     <para>
 159                         <emphasis>Формат извлечения</emphasis> -
 160                         первый аргумент. Он используется для управления
 161                         структурой, в которой возвращаются данные. Описания
 162                         допустимых значений и соответствующих им форматов данных
 163                         читайте в <xref linkend="zend.db.adapter.select.fetch-mode" />.
 164                     </para>
 165                 </listitem>
 166                 <listitem>
 167                     <para>
 168                         <emphasis>Ориентация курсора</emphasis> -
 169                         второй аргумент. Значением по умолчанию является
 170                         константа Zend_Db::FETCH_ORI_NEXT, которая просто
 171                         означает, что каждый вызов метода <code>fetch()</code>
 172                         возвращает следующую строку в наборе результатов, в той
 173                         же последовательности, в которой строки были возвращены
 174                         из БД.
 175                     </para>
 176                 </listitem>
 177                 <listitem>
 178                     <para>
 179                         <emphasis>Смещение</emphasis> - третий
 180                         аргумент.
 181                         Если ориентация курсора - Zend_Db::FETCH_ORI_ABS, то
 182                         число смещения - порядковый номер строки для
 183                         возвращения.
 184                         Если ориентация курсора - Zend_Db::FETCH_ORI_REL, то
 185                         число смещения является относительным по отношению к
 186                         положению курсора до того, как был вызван
 187                         <code>fetch()</code>.
 188                     </para>
 189                 </listitem>
 190             </itemizedlist>
 191
 192             <para>
 193                 <code>fetch()</code> возвращает <constant>FALSE</constant>, если все
 194                 строки из набора результатов были извлечены.
 195             </para>
 196
 197             <example id="zend.db.statement.fetching.fetch.example">
 198                 <title>Использование fetch() в цикле</title>
 199                 <programlisting language="php"><![CDATA[
 200 $stmt = $db->query('SELECT * FROM bugs');
 201
 202 while ($row = $stmt->fetch()) {
 203     echo $row['bug_description'];
 204 }
 205 ]]>
 206                 </programlisting>
 207             </example>
 208
 209             <para>
 210                 См. также <ulink url="http://www.php.net/PDOStatement-fetch">PDOStatement::fetch()</ulink>.
 211             </para>
 212
 213         </sect3>
 214
 215         <sect3 id="zend.db.statement.fetching.fetchall">
 216
 217             <title>Извлечение всего набора результатов</title>
 218
 219             <para>
 220                 Для единовременного получения всех строк из набора результатов
 221                 используйте метод <code>fetchAll()</code>. Он является
 222                 эквивалентным вызову метода <code>fetch()</code> в цикле и
 223                 возвращению всех строк в массиве. Метод <code>fetchAll()</code>
 224                 принимает два аргумента. Первый из них - формат извлечения,
 225                 описанный выше, через второй аргумент указывается число
 226                 возвращаемых столбцов, если формат извлечения
 227                 Zend_Db::FETCH_COLUMN.
 228             </para>
 229
 230             <example id="zend.db.statement.fetching.fetchall.example">
 231                 <title>Использование fetchAll()</title>
 232                 <programlisting language="php"><![CDATA[
 233 $stmt = $db->query('SELECT * FROM bugs');
 234
 235 $rows = $stmt->fetchAll();
 236
 237 echo $rows[0]['bug_description'];
 238 ]]>
 239                 </programlisting>
 240             </example>
 241
 242             <para>
 243                 См. также <ulink url="http://www.php.net/PDOStatement-fetchAll">PDOStatement::fetchAll()</ulink>.
 244             </para>
 245
 246         </sect3>
 247
 248         <sect3 id="zend.db.statement.fetching.fetch-mode">
 249
 250             <title>Изменение формата извлечения</title>
 251
 252             <para>
 253                 По умолчанию объект оператора возвращает строки из набора
 254                 результатов в виде ассоциативного массива имен столбцов и их
 255                 значений. Вы можете указать другой формат для класса оператора,
 256                 так же, как это делается для класса адаптера. Вы можете
 257                 использовать метод <code>setFetchMode()</code> объекта оператора
 258                 для указания режима извлечения. Указывайте режим извлечения,
 259                 используя константы FETCH_ASSOC, FETCH_NUM, FETCH_BOTH,
 260                 FETCH_COLUMN и FETCH_OBJ класса Zend_Db. Более подробную
 261                 информацию об этих режимах читайте в
 262                 <xref linkend="zend.db.adapter.select.fetch-mode" />. В
 263                 последующих вызовах методов <code>fetch()</code>
 264                 и <code>fetchAll()</code> объекта оператора будет использоваться
 265                 заданный вами режим извлечения.
 266             </para>
 267
 268             <example id="zend.db.statement.fetching.fetch-mode.example">
 269                 <title>Установка формата извлечения</title>
 270                 <programlisting language="php"><![CDATA[
 271 $stmt = $db->query('SELECT * FROM bugs');
 272
 273 $stmt->setFetchMode(Zend_Db::FETCH_NUM);
 274
 275 $rows = $stmt->fetchAll();
 276
 277 echo $rows[0][0];
 278 ]]>
 279                 </programlisting>
 280             </example>
 281
 282             <para>
 283                 См. также <ulink url="http://www.php.net/PDOStatement-setFetchMode">PDOStatement::setFetchMode()</ulink>.
 284             </para>
 285
 286         </sect3>
 287
 288         <sect3 id="zend.db.statement.fetching.fetchcolumn">
 289
 290             <title>Извлечение одного столбца из набора результатов</title>
 291
 292             <para>
 293                 Для извлечения одного столбца из следующей строки в наборе
 294                 результатов используйте <code>fetchColumn()</code>. Опциональный
 295                 аргумент - целочисленный индекс столбца, по умолчанию это 0.
 296                 Этот метод возвращает скалярное значение или <constant>FALSE</constant>,
 297                 если все строки набора результатов были уже извлечены
 298             </para>
 299
 300             <para>
 301                 Обратите внимание, что этот метод работает иначе, чем метод
 302                 <code>fetchCol()</code> класса адаптера. Метод
 303                 <code>fetchColumn()</code> оператора возвращает единственное
 304                 значение из одной строки. Метод <code>fetchCol()</code> адаптера
 305                 возвращает массив значений, взятых из первого столбца всех строк
 306                 набора результатов.
 307             </para>
 308
 309             <example id="zend.db.statement.fetching.fetchcolumn.example">
 310                 <title>Использование fetchColumn()</title>
 311                 <programlisting language="php"><![CDATA[
 312 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 313
 314 $bug_status = $stmt->fetchColumn(2);
 315 ]]>
 316                 </programlisting>
 317             </example>
 318
 319             <para>
 320                 См. также <ulink url="http://www.php.net/PDOStatement-fetchColumn">PDOStatement::fetchColumn()</ulink>.
 321             </para>
 322
 323         </sect3>
 324
 325         <sect3 id="zend.db.statement.fetching.fetchobject">
 326
 327             <title>Извлечение строки в виде объекта</title>
 328
 329             <para>
 330                 Для извлечения строки из набора результатов в виде объекта
 331                 используйте метод <code>fetchObject()</code>. Этот метод
 332                 принимает два опциональных аргумента. Первый аргумент является
 333                 именем класса для возвращаемого объекта, по умолчанию это
 334                 'stdClass'. Второй аргумент является массивом значений, которые
 335                 будут переданы конструктору этого класса.
 336             </para>
 337
 338             <example id="zend.db.statement.fetching.fetchobject.example">
 339                 <title>Использование fetchObject()</title>
 340                 <programlisting language="php"><![CDATA[
 341 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 342
 343 $obj = $stmt->fetchObject();
 344
 345 echo $obj->bug_description;
 346 ]]>
 347                 </programlisting>
 348             </example>
 349
 350             <para>
 351                 См. также <ulink url="http://www.php.net/PDOStatement-fetchObject">PDOStatement::fetchObject()</ulink>.
 352             </para>
 353
 354         </sect3>
 355
 356     </sect2>
 357
 358     <!--
 359       @todo: binding parameters is not working yet.
 360
 361     <sect2 id="zend.db.statement.binding-param">
 362
 363         <title>Binding PHP Variables to Parameters</title>
 364
 365         <para>
 366         </para>
 367
 368         <example id="zend.db.statement.binding-param.example">
 369             <title>Binding parameters from PHP variables</title>
 370             <programlisting language="php"><![CDATA[<?php
 371 ]]>
 372             </programlisting>
 373         </example>
 374
 375         <para>
 376             See also <ulink url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>.
 377         </para>
 378
 379     </sect2>
 380     -->
 381
 382     <!--
 383       @todo: binding columns is not working yet.
 384     <sect2 id="zend.db.statement.binding-column">
 385
 386         <title>Binding PHP Variables to Query Results</title>
 387
 388         <para>
 389         </para>
 390
 391         <example id="zend.db.statement.binding-column.example">
 392             <title>Binding results to PHP variables</title>
 393             <programlisting language="php"><![CDATA[<?php
 394 ]]>
 395             </programlisting>
 396         </example>
 397
 398         <para>
 399             See also <ulink url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>.
 400         </para>
 401
 402     </sect2>
 403     -->
 404
 405 </sect1>