repo_zf1/documentation/manual/ru/module_specs/Zend_Db_Adapter.xml

<sect1 id="zend.db.adapter">

    <title>Zend_Db_Adapter</title>

    <para>
        Zend_Db и его родственные классы предоставляют простой интерфейс к базам
        данных SQL в Zend Framework. Zend_Db_Adapter является базовым классом,
        который должен использоваться для подключения приложения PHP
        к СУРБД. Существуют различные классы адаптеров для наиболее часто
        используемых СУРБД.
    </para>

    <para>
        Адаптеры Zend_Db создают мост между общим интерфейсом и расширениями
        PHP от конкретных поставщиков для того, чтобы можно
        было единовременно писать приложения на PHP и затем переключаться между
        различными СУРБД с наименьшими усилиями.
    </para>

    <para>
        Интерфейс класса адаптера подобен интерфейсу расширения
        <ulink url="http://www.php.net/pdo">PHP Data Objects (PDO)</ulink>.
        Zend_Db предоставляет классы адаптеров к драйверам PDO для следующих
        популярных СУРБД:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                IBM DB2 и Informix Dynamic Server (IDS), с использованием
                расширения <ulink url="http://www.php.net/pdo-ibm">pdo_ibm</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                MySQL, с использованием расширения <ulink url="http://www.php.net/pdo-mysql">pdo_mysql</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                Microsoft SQL Server, с использованием расширения <ulink url="http://www.php.net/pdo-mssql">pdo_mssql</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                Oracle, с использованием расширения <ulink url="http://www.php.net/pdo-oci">pdo_oci</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                PostgreSQL, с использованием расширения <ulink url="http://www.php.net/pdo-pgsql">pdo_pgsql</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                SQLite, с использованием расширения <ulink url="http://www.php.net/pdo-sqlite">pdo_sqlite</ulink>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Кроме этого, Zend_Db предоставляет классы адаптеров, использующие расширения PHP для следующих распространенных СУРБД:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                MySQL, с использованием расширения <ulink url="http://www.php.net/mysqli">mysqli</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                Oracle, с использованием расширения <ulink url="http://www.php.net/oci8">oci8</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                IBM DB2, с использованием расширения <ulink url="http://www.php.net/ibm_db2">ibm_db2</ulink>
            </para>
        </listitem>
        <listitem>
            <para>
                Firebird/Interbase, с использованием расширения <ulink url="http://www.php.net/ibase">php_interbase</ulink>
            </para>
        </listitem>
    </itemizedlist>

    <note>
        <para>
            Все адаптеры Zend_Db используют расширения PHP. Вы должны иметь
            включенным соответствующее расширение в вашей среде PHP для
            использования адаптера Zend_Db. Например, если вы используете
            какой-либо из адаптеров PDO Zend_Db, то нужно включить как
            расширение PDO, так и драйвер PDO для используемой вами СУРБД.
        </para>
    </note>

    <sect2 id="zend.db.adapter.connecting">

        <title>Соединение с БД с использованием адаптера</title>

        <para>
            Этот раздел описывает, как создавать экземпляр адаптера БД. Это
            соответствует созданию соединения с сервером СУРБД из вашего
            приложения PHP.
        </para>

        <sect3 id="zend.db.adapter.connecting.constructor">

            <title>Использование конструктора адаптера Zend_Db</title>

            <para>
                Вы можете создавать экземпляр адаптера с помощью его
                конструктора. Конструктор адаптера принимает единственный
                аргумент, который является массивом параметров, использующихся
                для описания соединения.
            </para>

            <example id="zend.db.adapter.connecting.constructor.example">
                <title>Использование конструктора адаптера</title>
                <programlisting language="php"><![CDATA[
$db = new Zend_Db_Adapter_Pdo_Mysql(array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.connecting.factory">

            <title>Использование фабрики Zend_Db</title>

            <para>
                Вместо непосредственного использования конструктора
                адаптера можно создавать экземпляры адаптера, применяя
                статический метод <code>Zend_Db::factory()</code>. Этот метод
                динамически загружает файл класса адаптера, используя
                <link linkend="zend.loader.load.class">Zend_Loader::loadClass()</link>.
            </para>

            <para>
                Первым аргументом является строка с базовым именем класса
                адаптера. Например, строка 'Pdo_Mysql' соответствует классу
                Zend_Db_Adapter_Pdo_Mysql. Вторым аргументом является тот же
                массив параметров, который вы должны были бы передать
                конструктору адаптера.
            </para>

            <example id="zend.db.adapter.connecting.factory.example">
                <title>Использование метода-фабрики адаптеров</title>
                <programlisting language="php"><![CDATA[
// Нам не нужно использовать следующее предложение, поскольку
// файл Zend_Db_Adapter_Pdo_Mysql будет загружен через
// метод-фабрику Zend_Db

// require_once 'Zend/Db/Adapter/Pdo/Mysql.php';

// Автоматически загружает класс Zend_Db_Adapter_Pdo_Mysql
// и создает его экземпляр.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));
]]>
                </programlisting>
            </example>

            <para>
                Если вы создали собственный класс, расширяющий
                Zend_Db_Adapter_Abstract, но не дали ему имя, начинающееся с
                префикса "Zend_Db_Adapter", то можете использовать метод
                <code>factory()</code> для загрузки своего адаптера, указав
                ведущую часть имени класса адаптера с помощью ключа
                'adapterNamespace' в массиве параметров.
            </para>

            <example id="zend.db.adapter.connecting.factory.example2">
                <title>Использование метода-фабрики для пользовательского класса адаптера</title>
                <programlisting language="php"><![CDATA[
// Нам не нужно загружать файл с классом адаптера,
// поскольку он будет загружен через метод-фабрику Zend_Db

// Автоматически загружает класс MyProject_Db_Adapter_Pdo_Mysql
// и создает его экземпляр.
$db = Zend_Db::factory('Pdo_Mysql', array(
    'host'             => '127.0.0.1',
    'username'         => 'webuser',
    'password'         => 'xxxxxxxx',
    'dbname'           => 'test',
    'adapterNamespace' => 'MyProject_Db_Adapter'
));
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.connecting.factory-config">

            <title>Использование Zend_Config с фабрикой Zend_Db</title>

            <para>
                Опционально вы можете заменить оба аргумента метода
                <code>factory()</code> объектом типа
                <link linkend="zend.config">Zend_Config</link>.
            </para>

            <para>
                Если первым аргументом является объект конфигурации, то
                ожидается, что он имеет свойство с именем <code>adapter</code>,
                содержащее строку с базовой частью имени класса адаптера.
                Опционально объект может содержать свойство с именем
                <code>params</code> и "подсвойствами", соответствующими
                параметрам адаптера.
            </para>

            <example id="zend.db.adapter.connecting.factory.example1">
                <title>Использование метода-фабрики адаптеров с объектом Zend_Config</title>
                <para>
                    В примере ниже объект Zend_Config создан из массива. Вы
                    можете также загружать данные из внешнего файла с помощью
                    <link linkend="zend.config.adapters.ini">Zend_Config_Ini</link>
                    или <link linkend="zend.config.adapters.xml">Zend_Config_Xml</link>.
                </para>
                <programlisting language="php"><![CDATA[
$config = new Zend_Config(
    array(
        'database' => array(
            'adapter' => 'Mysqli',
            'params' => array(
                'dbname' => 'test',
                'username' => 'webuser',
                'password' => 'secret',
            )
        )
    )
);

$db = Zend_Db::factory($config->database);
]]>
                </programlisting>
            </example>

            <para>
                Второй аргумент метода <code>factory()</code> может быть
                ассоциативным массивом, содержащим элементы, которые
                соответствуют параметрам адаптера. Этот аргумент является
                опциональным. Если первым аргументом является объект типа
                Zend_Config, то предполагается, что он содержит все необходимые
                параметры, и второй аргумент игнорируется.
            </para>

        </sect3>

        <sect3 id="zend.db.adapter.connecting.parameters">

            <title>Параметры адаптера</title>

            <para>
                Список ниже описывает общие параметры, которые распознаются
                классами адаптеров Zend_Db.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>host</emphasis>:
                        строка, содержащая имя хоста или IP сервера БД. Если
                        база данных размещается на том же хосте, что и
                        приложение PHP, то вы можете использовать 'localhost'
                        или '127.0.0.1'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>username</emphasis>:
                        идентификатор учетной записи для аутентификации подключения к серверу СУРБД.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>password</emphasis>:
                        пароль  учетной записи для аутентификации подключения к
                        серверу СУРБД.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>dbname</emphasis>:
                        имя экземпляра БД на сервере СУРБД.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>port</emphasis>:
                        некоторые сервера СУРБД поддерживают сетевые соединения
                        через указанный администратором порт. Данный параметр
                        дает возможность задать порт, с которым приложение PHP
                        будет устанавливать соединение, он должен
                        соответствовать порту, установленному в сервере СУРБД.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>options</emphasis>:
                        этот параметр является ассоциативным массивом опций,
                        общих для всех классов Zend_Db_Adapter.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>driver_options</emphasis>:
                        этот параметр является ассоциативным массивом
                        дополнительных опций, специфических для данного
                        расширения. Одним из типичных случаев использования
                        этого параметра является установка атрибутов для
                        драйвера PDO.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>adapterNamespace</emphasis>:
                        имя начальной части имени класса для адаптера вместо
                        'Zend_Db_Adapter'. Используйте его, если нужно
                        использовать метод <code>factory()</code> для загрузки
                        "неZend'овского" класса адаптера БД.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.db.adapter.connecting.parameters.example1">
                <title>Передача фабрике опции перевода регистра (case-folding)</title>
                <para>
                    Вы можете установить эту опцию посредством константы
                    <code>Zend_Db::CASE_FOLDING</code>. Она соответствует
                    атрибуту <code>ATTR_CASE</code> в драйверах PDO и IBM DB2, и
                    переводит строковые ключи в результатах запроса в требуемый
                    регистр. Эта опция принимает значения
                    <code>Zend_Db::CASE_NATURAL</code> (значение по умолчанию),
                    <code>Zend_Db::CASE_UPPER</code> и
                    <code>Zend_Db::CASE_LOWER</code>.
                </para>
                <programlisting language="php"><![CDATA[
$options = array(
    Zend_Db::CASE_FOLDING => Zend_Db::CASE_UPPER
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Db2', $params);
]]>
                </programlisting>
            </example>

            <example id="zend.db.adapter.connecting.parameters.example2">
                <title>Передача фабрике опции автоматического заключения в кавычки</title>
                <para>
                    Вы можете задавать эту опцию через константу
                    <code>Zend_Db::AUTO_QUOTE_IDENTIFIERS</code>. Если ее
                    значение установлено в <constant>TRUE</constant> (по умолчанию), то
                    идентификаторы, такие, как имена таблиц, имена столбцов и
                    даже псевдонимы, разграничиваются во всем генерируемом
                    объектом адаптера синтаксисе SQL. Это делает возможным
                    использование идентификаторов, содержащих ключевые слова SQL
                    и специальные символы. Если его значение равно
                    <constant>FALSE</constant>, то автоматическое заключение в кавычки
                    не производится. Если требуется заключение идентификаторов в
                    кавычки, то оно должно производиться самостоятельно с
                    использованием метода <code>quoteIdentifier()</code>.
                </para>
                <programlisting language="php"><![CDATA[
$options = array(
    Zend_Db::AUTO_QUOTE_IDENTIFIERS => false
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'options'        => $options
);

$db = Zend_Db::factory('Pdo_Mysql', $params);
]]>
                </programlisting>
            </example>

            <example id="zend.db.adapter.connecting.parameters.example3">
                <title>Передача фабрике опций драйвера PDO</title>
                <programlisting language="php"><![CDATA[
$pdoParams = array(
    PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => true
);

$params = array(
    'host'           => '127.0.0.1',
    'username'       => 'webuser',
    'password'       => 'xxxxxxxx',
    'dbname'         => 'test',
    'driver_options' => $pdoParams
);

$db = Zend_Db::factory('Pdo_Mysql', $params);

echo $db->getConnection()
        ->getAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY);
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.connecting.getconnection">
            <title>Управление отложенными соединениями</title>

            <para>
                Создание экземпляра класса адаптера не приведет к немедленному
                соединению с сервером СУРБД. Адаптер сохраняет параметры
                соединения и производит подключение, когда нужно произвести
                первый запрос к БД. Это значит, что само по себе создание
                объекта адаптера производится быстро и занимает мало ресурсов.
                Вы можете создавать экземпляр адаптера даже в том случае, если
                не уверены в том, что текущий запрос к вашему приложению
                требует каких-либо действий с БД.
            </para>

            <para>
                Если нужно принудительно создать соединение с СУРБД, то
                используйте метод <code>getConnection()</code>. Этот метод
                возвращает объект соединения в представлении соответствующего
                расширения PHP для баз данных. Например, если вы используете
                какой-либо класс адаптера для драйверов PDO, то
                <code>getConnection()</code> возвращает объект PDO после того,
                как он будет инициирован им в качестве "живого" соединения с
                определенной БД.
            </para>

            <para>
                Принудительное создание соединения может быть полезным, когда вы
                хотите отлавливать все исключения, которые бросаются из-за
                неправильных параметров доступа или других ошибок соединения с
                сервером СУРБД. Эти исключения не бросаются до тех пор, пока не
                создается соединение, поэтому можно упростить
                код приложения, обрабатывая исключения в одном
                месте вместо того, чтобы делать это каждый раз, когда
                производится первый запрос к БД.
            </para>

            <example id="zend.db.adapter.connecting.getconnection.example">
                <title>Обработка исключений при соединении</title>
                <programlisting language="php"><![CDATA[
try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // возможно, неправильные параметры соединения или СУРБД не запущена
} catch (Zend_Exception $e) {
    // возможно, попытка загрузки требуемого класса адаптера потерпела неудачу
}
]]>
                </programlisting>
            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.adapter.example-database">

        <title>Пример базы данных</title>

        <para>
            В документации к классам Zend_Db мы использовали набор простых
            таблиц для того, чтобы проиллюстрировать использование классов и их
            методов. Эти таблицы должны были хранить информацию для отслеживания
            ошибок в проекте разработки ПО. База данных содержит четыре таблицы:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>accounts</emphasis> (учетные записи)
                    хранит информацию о всех пользователях системы отслеживания
                    ошибок.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>products</emphasis> (продукты)
                    хранит информацию обо всех программных продуктах, для
                    которых могут отслеживаться ошибки.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>bugs</emphasis> (ошибки) хранит
                    информацию об ошибках, включая текущее состояние ошибки,
                    лицо, сообщившее об ошибке, лицо, которому назначено
                    устранение ошибки и лицо, которому назначена проверка
                    устранения ошибки.
                </para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>bugs_products</emphasis> хранит
                    связи между ошибками и продуктами. Она реализует связь
                    "многие-ко-многим", потому что одна ошибка может относиться
                    к нескольким продуктам, и один продукт может иметь множество
                    ошибок.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Следующий псевдокод для определения данных SQL описывает таблицы в
            этой базе данных. Это таблицы интенсивно используются в unit-тестах
            для Zend_Db.
        </para>

        <programlisting language="sql"><![CDATA[
CREATE TABLE accounts (
  account_name      VARCHAR(100) NOT NULL PRIMARY KEY
);

CREATE TABLE products (
  product_id        INTEGER NOT NULL PRIMARY KEY,
  product_name      VARCHAR(100)
);

CREATE TABLE bugs (
  bug_id            INTEGER NOT NULL PRIMARY KEY,
  bug_description   VARCHAR(100),
  bug_status        VARCHAR(20),
  reported_by       VARCHAR(100) REFERENCES accounts(account_name),
  assigned_to       VARCHAR(100) REFERENCES accounts(account_name),
  verified_by       VARCHAR(100) REFERENCES accounts(account_name)
);

CREATE TABLE bugs_products (
  bug_id            INTEGER NOT NULL REFERENCES bugs,
  product_id        INTEGER NOT NULL REFERENCES products,
  PRIMARY KEY       (bug_id, product_id)
);
]]>
        </programlisting>

        <para>
            Также обратите внимание, что таблица <code>bugs</code> содержит
            несколько внешних ключей, ссылающихся на таблицу
            <code>accounts</code>. Для одной ошибки эти внешние ключи могут
            ссылаться на разные строки в таблице <code>accounts</code>.
        </para>

        <para>
            Диаграмма ниже иллюстрирует физическую модель данных для этой базы
            данных.
        </para>

        <para>
            <inlinegraphic width="387" scale="100" align="center" valign="middle"
                fileref="figures/zend.db.adapter.example-database.png" format="PNG" />
        </para>

    </sect2>

    <sect2 id="zend.db.adapter.select">

        <title>Чтение результатов запроса</title>

        <para>
            Этот раздел описывает методы класса адаптера, с помощью которых вы
            можете производить запросы SELECT и извлекать их результаты.
        </para>

        <sect3 id="zend.db.adapter.select.fetchall">

            <title>Извлечение полного набора результатов</title>

            <para>
                Вы можете запустить запрос SELECT и извлечь его результаты за
                один шаг, используя метод <code>fetchAll()</code>.
            </para>

            <para>
                Первым аргументом этого метода должна быть строка, содержащая
                оператор SELECT. Также первым аргументом может быть объект
                класса <link linkend="zend.db.select">Zend_Db_Select</link>.
                Адаптер автоматически преобразует этот объект в строковое
                представление оператора SELECT.
            </para>

            <para>
                Вторым аргументом <code>fetchAll()</code> должен быть массив
                значений для подстановки вместо меток заполнения (placeholders)
                в операторе SQL.
            </para>

            <example id="zend.db.adapter.select.fetchall.example">
                <title>Использование fetchAll()</title>
                <programlisting language="php"><![CDATA[
$sql = 'SELECT * FROM bugs WHERE bug_id = ?';

$result = $db->fetchAll($sql, 2);
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.select.fetch-mode">

            <title>Изменение режима извлечения</title>

            <para>
                По умолчанию <code>fetchAll()</code> возвращает массив строк,
                каждая из которых представлена ассоциативным
                массивом. Ключами ассоциативных массивов являются имена столбцов
                или псевдонимы столбцов, определенные в данном запросе на
                выборку.
            </para>

            <para>
                Вы можете задать другой стиль извлечения результатов, используя
                метод <code>setFetchMode()</code>. Поддерживаемые режимы
                идентифицируются константами:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>Zend_Db::FETCH_ASSOC</emphasis>:
                        возвращает данные в массиве ассоциативных массивов.
                        Ключами массива являются имена столбцов в виде строк.
                        Это режим извлечения, используемый по умолчанию в
                        классах Zend_Db_Adapter.
                    </para>
                    <para>
                        Обратите внимание, что если ваш список выборки содержит
                        столбцы с одинаковыми именами, например, если они из
                        разных таблиц в JOIN-е, то в ассоциативном массиве может
                        быть только одна запись для этого имени. Если вы
                        используете режим FETCH_ASSOC, то должны задавать
                        псевдонимы столбцов в своем запросе SELECT для того,
                        чтобы для всех столбцов были свои уникальные ключи.
                    </para>
                    <para>
                        По умолчанию эти строки возвращаются так же, как если бы
                        они были возвращены драйвером БД. Как правило, это
                        синтаксис столбцов для данного сервера СУРБД. Вы можете
                        задать регистр для этих строк, используя опцию.
                        <code>Zend_Db::CASE_FOLDING</code>. Задавайте его во
                        время инстанцирования адаптера. См.
                        <xref linkend="zend.db.adapter.connecting.parameters.example1" />.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Zend_Db::FETCH_NUM</emphasis>:
                        возвращает данные в массиве массивов. Массив
                        индексируется целочисленными значениями в соответствии с
                        позицией данного поля в списке выборки запроса.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Zend_Db::FETCH_BOTH</emphasis>:
                        возвращает данные в массиве массивов. Ключами массива
                        являются как строки, так и целочисленные значения. Число
                        элементов в массиве получается в два раза больше, чем
                        если бы использовались FETCH_ASSOC или FETCH_NUM.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Zend_Db::FETCH_COLUMN</emphasis>:
                        возвращает данные в массиве значений. Значение в каждом
                        массиве является значением, возвращенным из одного
                        столбца результата выборки. По умолчанию это первый
                        столбец, индексированный нулем.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>Zend_Db::FETCH_OBJ</emphasis>:
                        возвращает данные в массиве объектов. По умолчанию
                        используется встроенный в PHP класс stdClass. Столбцы
                        результата выборки доступны в качестве открытых свойств
                        этого объекта.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.db.adapter.select.fetch-mode.example">
                <title>Использование setFetchMode()</title>
                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAll('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result является массивом объектов
echo $result[0]->bug_description;
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.select.fetchassoc">

            <title>Извлечение результатов выборки в виде ассоциативного массива</title>

            <para>
                Метод <code>fetchAssoc()</code> возвращает данные в массиве
                ассоциативных массивов безотносительно того, какое значение вы
                установили для режима извлечения.
            </para>

            <example id="zend.db.adapter.select.fetchassoc.example">
                <title>Использование fetchAssoc()</title>
                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAssoc('SELECT * FROM bugs WHERE bug_id = ?', 2);

// $result является массивом ассоциативных массивов, независимо
// от установленного режима извлечения
echo $result[0]['bug_description'];
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.select.fetchcol">

            <title>Извлечение единственного столбца из результатов выборки</title>

            <para>
                Метод <code>fetchCol()</code> возвращает данные в массиве
                значений безотносительно того, какое значение вы
                установили для режима извлечения. Он возвращает только первый
                столбец из возвращенных запросом. Все остальные столбцы,
                возвращенные запросом, не учитываются. Если вам нужно извлечь
                столбец, отличный от первого, то см.
                <xref linkend="zend.db.statement.fetching.fetchcolumn" />.
            </para>

            <example id="zend.db.adapter.select.fetchcol.example">
                <title>Использование fetchCol()</title>
                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchCol(
    'SELECT bug_description, bug_id FROM bugs WHERE bug_id = ?', 2);

// содержит bug_description; bug_id не возвращается
echo $result[0];
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.select.fetchpairs">

            <title>Извлечение пар ключ-значение из результатов выборки</title>

            <para>
                Метод <code>fetchPairs()</code> возвращает данные в массиве пар
                ключ-значение,
                Ключ ассоциативного массива берется из первого столбца,
                возвращенного запросом SELECT. Значение берется из второго
                столбца, возвращенного запросом SELECT. Все остальные столбцы,
                возвращенные запросом, не учитываются.
            </para>

            <para>
                Вы должны строить запрос SELECT так, чтобы первый из
                возвращенных столбцов имел уникальные значения. Если в нем
                имеются повторяющиеся значения, то записи в ассоциативном
                массиве будут перезаписываться.
            </para>

            <example id="zend.db.adapter.select.fetchpairs.example">
                <title>Использование fetchPairs()</title>
                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchPairs('SELECT bug_id, bug_status FROM bugs');

echo $result[2];
]]>
                </programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchrow">

            <title>Извлечение единственной строки из результатов выборки</title>

            <para>
                Метод <code>fetchRow()</code> возвращает данные с использованием
                текущего режима извлечения, но возвращает только первую строку
                из результатов выборки.
            </para>

            <example id="zend.db.adapter.select.fetchrow.example">
                <title>Использование fetchRow()</title>
                <programlisting language="php"><![CDATA[
$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchRow('SELECT * FROM bugs WHERE bug_id = 2');

// обратите внимание, что $result - единственный объект, а не массив объектов
echo $result->bug_description;
]]>
                </programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.adapter.select.fetchone">

            <title>Извлечение единственного скалярного значения из результатов выборки</title>

            <para>
                Метод <code>fetchOne()</code> является как бы комбинацией
                методов <code>fetchRow()</code> и <code>fetchCol()</code> - он
                возвращает значение первого столбца в первой строке из
                результатов выборки. Таким образом, он возвращает одно скалярное
                значение, а не массив или объект.
            </para>

            <example id="zend.db.adapter.select.fetchone.example">
                <title>Использование fetchOne()</title>
                <programlisting language="php"><![CDATA[
$result = $db->fetchOne('SELECT bug_status FROM bugs WHERE bug_id = 2');

// это единственное строковое значение
echo $result;
]]>
                </programlisting>
            </example>
        </sect3>

    </sect2>

    <sect2 id="zend.db.adapter.write">

        <title>Изменение данных в БД</title>

        <para>
            Вы можете использовать класс адаптера для добавления новых данных
            или изменения существующих в своей базе данных. В данном разделе
            описываются методы для произведения этих операций.
        </para>

        <sect3 id="zend.db.adapter.write.insert">

            <title>Добавление данных</title>

            <para>
                Вы можете добавлять новые строки в таблицы в своей базе данных,
                используя метод  <code>insert()</code>. Первым аргументом этого
                метода является строка с именем таблицы, а вторым аргументом -
                ассоциативный массив с именами столбцов и соответствующими им
                значениями.
            </para>

            <example id="zend.db.adapter.write.insert.example">
                <title>Добавление в таблицу</title>
                <programlisting language="php"><![CDATA[
$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
]]>
                </programlisting>
            </example>

            <para>
                Те столбцы, которые не были включены в массив данных, не
                передаются базе данных. Таким образом, они следуют тем же
                правилам, что и SQL-оператор INSERT: если столбец имеет
                предложение DEFAULT, то он принимает это значение в созданной
                строке, иначе остается в состоянии NULL.
            </para>

            <para>
                По умолчанию значения в вашем массиве данных добавляются с
                использованием параметров. Это сокращает некоторые риски
                безопасности. Вам не нужно будет применять к значениям в массиве
                данных такие действия, как взятие в кавычки или экранирование.
            </para>

            <para>
                Иногда бывает необходимо, чтобы часть значений в массиве данных
                трактовалась как SQL-выражения, в этом случае они не должны
                заключаться в кавычки. По умолчанию все данные, переданные в
                виде строк, трактуются как строковые литералы. Для того, чтобы
                указать, что данное значение является SQL-выражением (а
                значит, не должно заключаться в кавычки), передавайте его в
                массиве данных в виде объекта типа Zend_Db_Expr вместо простой
                строки.
            </para>

            <example id="zend.db.adapter.write.insert.example2">
                <title>Добавление выражений в таблицу</title>
                <programlisting language="php"><![CDATA[
$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.write.lastinsertid">

            <title>Получение сгенерированного значения</title>

            <para>
                Некоторые СУРБД поддерживают автоинкремент первичных ключей.
                Таблица, описанная определенным образом, автоматически
                генерирует значение первичного ключа во время добавления новой
                строки.
                Возвращаемое методом <code>insert()</code> значение
                <emphasis>не</emphasis> является последним добавленным
                идентификатором, потому что таблица может не иметь
                автоинкрементных столбцов. Вместо этого возвращаемое
                значение является количеством затронутых строк (обычно 1).
            </para>

            <para>
                Если ваша таблица определена с автоинкрементным первичным
                ключом, то вы можете вызывать метод <code>lastInsertId()</code>
                после добавления. Этот метод возвращает последнее значение,
                сгенерированное в области видимости текущего соединения с БД.
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-1">
                <title>Использование lastInsertId() для автоинкрементного ключа</title>
                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// возвращает последнее значение, сгенерированное автоинкрементным столбцом
$id = $db->lastInsertId();
]]>
                </programlisting>
            </example>

            <para>
                Некоторые СУРБД поддерживают объекты последовательностей
                (sequence object), которые генерируют уникальные значения для
                использования в качестве значений первичных ключей. Для
                поддержки последовательностей <code>lastInsertId()</code>
                принимает два необязательных строковых аргумента. Эти аргументы
                служат для передачи имен таблицы и столбца, при этом
                предполагается, что вы следуете соглашению, по которому имя
                последовательности состоит из имен таблицы и столбца, для
                которых эта последовательность генерирует значения, и суффикса
                "_seq". Это соглашение основано на используемом системой
                PostgreSQL при именовании последовательностей для столбцов
                SERIAL. Например, таблица "bugs" с первичным ключом "bug_id"
                должна использовать последовательность с именем
                "bugs_bug_id_seq".
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-2">
                <title>Использование lastInsertId() для последовательности</title>
                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// возвращает последнее значение, сгенерированное
// последовательностью 'bugs_bug_id_seq'
$id = $db->lastInsertId('bugs', 'bug_id');

// альтернативно, возвращает последнее значение, сгенерированное
// последовательностью 'bugs_seq'.
$id = $db->lastInsertId('bugs');
]]>
                </programlisting>
            </example>

            <para>
                Если имя вашего объекта последовательности не следует этому
                соглашению по именованию, то используйте метод
                <code>lastSequenceId()</code>. Этот метод принимает один
                строковой аргумент, через который передается точное имя
                последовательности
            </para>

            <example id="zend.db.adapter.write.lastinsertid.example-3">
                <title>Использование lastSequenceId()</title>
                <programlisting language="php"><![CDATA[
$db->insert('bugs', $data);

// возвращает последнее значение, сгенерированное
// последовательностью 'bugs_id_gen'.
$id = $db->lastSequenceId('bugs_id_gen');
]]>
                </programlisting>
            </example>

            <para>
                Для тех СУРБД, которые не поддерживают последовательности,
                включая MySQL, Microsoft SQL Server и SQLite, аргументы метода
                lastInsertId() игнорируются, и возвращается самое последнее
                значение, сгенерированное для любой таблицы через оператор
                INSERT в течение данного соединения. Для этих типов СУРБД метод
                lastSequenceId() всегда будет возвращать <constant>NULL</constant>.
            </para>

            <note>
                <title>Почему не используется "SELECT MAX(id) FROM table"?</title>
                <para>
                    Иногда этот запрос возвращает последнее значение первичного
                    ключа, добавленное в таблицу. Однако этот способ небезопасен
                    в условиях, когда несколько клиентов добавляют записи в базу
                    данных. Может случиться (и должно происходить в конечном
                    итоге) так, что другой клиент добавляет другую строку в
                    короткий промежуток времени между добавлением строки,
                    производимым вашим приложением-клиентом БД, и вашим запросом
                    для получения значения MAX(id). Таким образом, это
                    возвращаемое значение не будет соответствовать добавленной
                    вами строке, вместо этого оно будет соответствовать строке,
                    добавленной другим клиентом. Нет способа определить,
                    когда это происходит.
                </para>
                <para>
                    Использование высокого уровня изоляции транзакций, такого,
                    как "repeatable read", может уменьшить этот риск, но
                    некоторые СУРБД не поддерживают требуемую для этого изоляцию
                    транзакций, либо намеренно используется более низкий уровень
                    изоляции транзакций в приложении.
                </para>
                <para>
                    Использование выражения наподобие "MAX(id)+1" для генерации
                    нового значения первичного ключа тоже небезопасно, так как
                    два клиента могут сделать этот запрос одновременно, и оба
                    будут использовать одно и то же полученное значение для
                    своей последующей операции INSERT.
                </para>
                <para>
                    Все СУРБД предоставляют механизмы для генерации уникальных
                    значений и возвращения последних сгенерированных значений.
                    Эти механизмы работают вне области видимости транзакций,
                    поэтому нет вероятности того, что оба клиента сгенерируют
                    одно и то же значение, или что значение, сгенерированное
                    другим клиентом, будет возвращено вашему клиенту как
                    последнее сгенерированное им в его соединении.
                </para>
            </note>

        </sect3>

        <sect3 id="zend.db.adapter.write.update">
            <title>Обновление данных</title>

            <para>
                Вы можете обновлять строки в таблице БД, используя метод
                <code>update()</code> адаптера. Этот метод принимает три
                аргумента: первый является имением таблицы, второй -
                ассоциативным массивом столбцов, которые требуется изменить, и
                значений, которые требуется присвоить этим столбцам.
            </para>

            <para>
                Значения в массиве данных интерпретируются как строковые
                константы. Информацию об использовании выражений SQL в массиве
                данных см. в разделе
                <xref linkend="zend.db.adapter.write.insert" />.
            </para>

            <para>
                Третий аргумент является строкой, содержащей выражение SQL,
                которое используется в качестве условия, при выполнении которого
                строка должна изменяться. Значения и идентификаторы в этом
                аргументе не заключаются в кавычки и не экранируются. Вы
                ответственны за то, чтобы все динамическое содержимое было
                безопасным образом включено в эту строку. Информацию о методах,
                которые помогут вам в этом, см. в разделе
                <xref linkend="zend.db.adapter.quoting" />.
            </para>

            <para>
                Возвращаемое значение является числом строк, затронутых в
                операции обновления.
            </para>

            <example id="zend.db.adapter.write.update.example">
                <title>Обновление строк</title>
                <programlisting language="php"><![CDATA[
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$n = $db->update('bugs', $data, 'bug_id = 2');
]]>
                </programlisting>
            </example>

            <para>
                Если вы опустите третий аргумент, то все строки в таблице БД
                будут обновлены со значениями, указанными в массиве данных.
            </para>

            <para>
                Если вы передадите массив строк в качестве третьего аргумента,
                то эти строки будут объединены как термы выражения, разделенные
                операторами <code>AND</code>.
            </para>

            <example id="zend.db.adapter.write.update.example-array">
                <title>Обновление строк с использованием массива выражений</title>
                <programlisting language="php"><![CDATA[
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

$where[] = "reported_by = 'goofy'";
$where[] = "bug_status = 'OPEN'";

$n = $db->update('bugs', $data, $where);

// Результирующий SQL:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')
]]>
                </programlisting>
            </example>

        </sect3>

        <sect3 id="zend.db.adapter.write.delete">
            <title>Удаление данных</title>
            <para>
                Вы можете удалять строки из таблицы БД, используя метод
                <code>delete()</code>. Этот метод принимает два аргумента,
                первый из них является строкой с именем таблицы.
            </para>

            <para>
                Второй аргумент является строкой, содержащей выражение SQL,
                который используется в качестве условия, при выполнении которого
                строка удаляется. Значения и идентификаторы в этом аргументе не
                заключаются в кавычки и не экранируются. Вы ответственны за то,
                чтобы весь динамический контент был безопасным образом включен в
                эту строку. Информацию о методах, которые помогут вам в этом,
                см. в разделе <xref linkend="zend.db.adapter.quoting" />.
            </para>

            <para>
                Возвращаемое значение является числом строк, задействованных в
                операции удаления.
            </para>

            <example id="zend.db.adapter.write.delete.example">
                <title>Удаление строк</title>
                <programlisting language="php"><![CDATA[
$n = $db->delete('bugs', 'bug_id = 3');
]]>
                </programlisting>
            </example>

            <para>
                Если вы опустите второй аргумент, то в результате
                все строки в таблице БД будут удалены.
            </para>

            <para>
                Если вы передадите массив строк в качестве второго аргумента, то
                эти строки будут объединены как термы выражения, разделенные
                операторами <code>AND</code>.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.db.adapter.quoting">

        <title>Заключение в кавычки значений и идентификаторов</title>

        <para>
            При построении запросов SQL часто требуется включить значения
            переменных PHP в выражения SQL. Это несет в себе дополнительный
            риск, потому что если значение в строке PHP содержит определенные
            символы, такие, как символы кавычек, то в результате может
            получиться недопустимый код SQL. Например, обратите внимание на
            несоответствие кавычек в следующем запросе:
            <programlisting language="php"><![CDATA[
$name = "O'Reilly";
$sql = "SELECT * FROM bugs WHERE reported_by = '$name'";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O'Reilly'
]]>
            </programlisting>
        </para>

        <para>
            Еще серьезнее риск того, что такие ошибки в коде могут быть
            целенаправленно использованы тем, кто пытается получить управление
            вашим веб-приложением. Если он может указать значение переменной
            PHP, используя параметры HTTP или другой механизм, то может
            заставить ваши SQL-запросы выполнять действия, для которых они не
            предназначены - например, возвращение данных, на чтение которых лицо
            не имеет прав. Это серьезное и широко распространенное нарушение
            безопасности приложения, известное под названием "SQL-инъекции"
            (см. <ulink url="http://ru.wikipedia.org/wiki/%D0%98%D0%BD%D1%8A%D0%B5%D0%BA%D1%86%D0%B8%D1%8F_SQL">http://ru.wikipedia.org/wiki/Инъекция_SQL</ulink>).
        </para>

        <para>
            Класс адаптера Zend_Db предоставляет удобные функции для того, чтобы
            уменьшить уязвимость приложения к SQL-инъекциям. Решение
            состоит в том, чтобы экранировать специальные символы, такие, как
            кавычки в значениях PHP, до того, как они будут включены в строки
            запросов SQL. Это защищает как от случайных, так и от
            целенаправленных манипуляций строками SQL через переменные PHP,
            содержащие специальные символы.
        </para>

        <sect3 id="zend.db.adapter.quoting.quote">

            <title>Использование <code>quote()</code></title>

            <para>
                Метод <code>quote()</code> принимает единственный аргумент -
                скалярное строковое значение. Он возвращает значение с
                специальными символами, экранированными соответствующим образом
                для используемой вами СУРБД, и окруженным ограничителями
                строковых значений. Стандартным ограничителем строковых значений
                в SQL является одинарная кавычка (<code>'</code>).
            </para>

            <example id="zend.db.adapter.quoting.quote.example">
                <title>Использование quote()</title>
                <programlisting language="php"><![CDATA[
$name = $db->quote("O'Reilly");
echo $name;
// 'O\'Reilly'

$sql = "SELECT * FROM bugs WHERE reported_by = $name";

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'
]]>
                </programlisting>
            </example>

            <para>
                Обратите внимание, что возвращаемое методом <code>quote()</code>
                значение включает в себя окружающие кавычки. Этим
                метод отличается от некоторых функций, которые экранируют
                специальные символы, но не добавляют кавычки, например,
                <ulink url="http://www.php.net/mysqli_real_escape_string">mysql_real_escape_string()</ulink>.
            </para>

            <para>
                Данные могут требовать или не требовать заключения в кавычки в
                зависимости от того, в каком контексте типа данных SQL они
                используются. Например, в некоторых СУРБД целочисленное
                значение не должно заключаться в кавычки, если оно
                сравнивается со столбцом или выражением целочисленного типа.
                Другими словами, следующий запрос является ошибочным в некоторых
                реализациях SQL, если столбец <code>intColumn</code> имеет
                целочисленный тип данных <code>INTEGER</code>.

                <programlisting language="php"><![CDATA[
SELECT * FROM atable WHERE intColumn = '123'
]]>
                </programlisting>
            </para>

            <para>
                Вы можете использовать необязательный второй аргумент метода
                <code>quote()</code> для избирательного заключения в кавычки
                тех типов данных SQL, которые вы укажете.
            </para>

            <example id="zend.db.adapter.quoting.quote.example-2">
                <title>Использование quote() с указанием типа SQL</title>
                <programlisting language="php"><![CDATA[
$value = '1234';
$sql = 'SELECT * FROM atable WHERE intColumn = '
     . $db->quote($value, 'INTEGER');
]]>
                </programlisting>
            </example>

            <para>
                Каждый класс Zend_Db_Adapter имеет закодированные имена типов
                данных SQL для соответствующих СУРБД. Вы можете также
                использовать константы <code>Zend_Db::INT_TYPE</code>,
                <code>Zend_Db::BIGINT_TYPE</code> и
                <code>Zend_Db::FLOAT_TYPE</code> для написания еще более
                независимого от типа используемой СУРБД кода.
            </para>

            <para>
                Zend_Db_Table автоматически указывает типы SQL для метода
                <code>quote()</code> при генерации SQL-запросов, ссылающихся на
                ключевые столбцы таблицы.
            </para>

        </sect3>

        <sect3 id="zend.db.adapter.quoting.quote-into">

            <title>Использование <code>quoteInto()</code></title>

            <para>
                Наиболее типичным случаем использования операции заключения в
                кавычки является добавление переменной PHP в выражение или
                оператор SQL. Вы можете использовать метод
                <code>quoteInto()</code> для того, чтобы выполнить это за один
                шаг. Этот метод принимает два аргумента: первый аргумент
                является строкой, содержащей символ метки заполнения
                (<code>?</code>), а второй аргумент - значением или
                переменной PHP, которая должна быть подставлена вместо этой
                метки заполнения.
            </para>

            <para>
                Символ метки заполнения одинаковый в многих СУРБД для
                позиционных параметров, но метод <code>quoteInto()</code> только
                эмулирует параметры запроса. Этот метод просто добавляет
                значение в строку, экранируя специальные символы и заключая его
                в кавычки. В случае настоящих параметров запроса сохраняется
                разделение между строкой SQL и параметрами, поскольку строка
                запроса анализируется сервером СУРБД.
            </para>

            <example id="zend.db.adapter.quoting.quote-into.example">
                <title>Использование quoteInto()</title>
                <programlisting language="php"><![CDATA[
$sql = $db->quoteInto("SELECT * FROM bugs WHERE reported_by = ?", "O'Reilly");

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'
]]>
                </programlisting>
            </example>

            <para>
                Вы можете использовать опциональный третий параметр метода
                <code>quoteInto()</code> для указания типа данных SQL. Числовые
                типы данных не заключаются в кавычки, остальные заключаются.
            </para>

            <example id="zend.db.adapter.quoting.quote-into.example-2">
                <title>Использование quoteInto() с указанием типа SQL</title>
                <programlisting language="php"><![CDATA[
$sql = $db->quoteInto("SELECT * FROM bugs WHERE bug_id = ?", '1234', 'INTEGER');

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 1234
]]>
                </programlisting>
            </example>

        </sect3>
        <sect3 id="zend.db.adapter.quoting.quote-identifier">

            <title>Использование <code>quoteIdentifier()</code></title>

            <para>
                Значения являются не единственной частью синтаксиса SQL, которая
                может изменяться. Если вы используете переменные PHP для имен
                таблиц, столбцов и других идентификаторов в своих операторах
                SQL, то эти строки тоже следует заключать в кавычки. По
                умолчанию идентификаторы в SQL следуют тем же правилам
                синтаксиса, что есть в PHP и других языках программирования.
                Например, идентификаторы не должны содержать пробелы,
                определенные знаки препинания, специальные символы или
                международные символы. Также в синтаксисе SQL зарезервированы
                некоторые слова, и они не должны использоваться в качестве
                идентификаторов.
            </para>

            <para>
                Тем не менее, в SQL есть возможность, которая называется
                <emphasis>идентификаторы с ограничителями</emphasis> (delimited
                identifiers), она дает б<emphasis>о</emphasis>льшие возможности
                выбора идентификаторов. Если вы заключите идентификатор SQL в
                кавычки требуемого типа, то можете использовать те
                идентификаторы, которые были бы недопустимыми без кавычек.
                Идентификаторы с ограничителями могут содержать пробелы, знаки
                препинания и международные символы. Вы можете также использовать
                зарезервированные слова SQL, если заключите их в ограничители
                идентификаторов.
            </para>

            <para>
                <code>quoteIdentifier()</code> работает так же, как
                <code>quote()</code>, но он применяет символы ограничителей
                идентификаторов к строке в соответствии с типом используемой
                СУРБД. Например, стандартный SQL использует двойные кавычки
                (<code>"</code>) в качестве ограничителей идентификаторов и
                большинство типов СУРБД использует именно их. MySQL по умолчанию
                использует обратные кавычки (<code>`</code>). Метод
                <code>quoteIdentifier()</code> также экранирует специальные
                символы в строковом аргументе.
            </para>

            <example id="zend.db.adapter.quoting.quote-identifier.example">
                <title>Использование quoteIdentifier()</title>
                <programlisting language="php"><![CDATA[
// мы можем иметь имя таблицы,
// которое является зарезервированным в SQL словом
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"
]]>
                </programlisting>
            </example>

            <para>
                Идентификаторы с ограничителями в SQL являются чувствительными к
                регистру, в отличие от не заключенных в кавычки. Поэтому, если
                вы используете идентификаторы с ограничителями, то должны
                использовать в точности то же написание идентификаторов, как и в
                схеме БД, включая регистр букв.
            </para>

            <para>
                В большинстве случаев, когда SQL генерируется в классах Zend_Db,
                все идентификаторы по умолчанию автоматически заключаются в
                ограничители. Вы можете изменить это поведение с помощью опции
                <code>Zend_Db::AUTO_QUOTE_IDENTIFIERS</code>. Указывайте ее при
                инстанцировании объекта адаптера. См.
                <xref linkend="zend.db.adapter.connecting.parameters.example2" />.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.db.adapter.transactions">

        <title>Управление транзакциями</title>

        <para>
            Базы данных описывают транзакции как логические единицы работы,
            которые могут фиксироваться или откатываться как одно изменение,
            даже если они затрагивают несколько таблиц. Все запросы к БД
            выполняются в контексте транзакций, даже если драйвер баз данных
            работает с ними неявным образом. Это называется режимом
            <emphasis>автоматической фиксации</emphasis>, в котором драйвера БД
            создают транзакции для каждого выполняемого SQL-оператора. По
            умолчанию все классы адаптеров Zend_Db функционируют в режиме
            автоматической фиксации.
        </para>

        <para>
            Вы можете также задавать начало и конец транзакции, и таким образом
            контролировать число SQL-запросов в группе, которая фиксируется (или
            откатывается) как одна операция.
            Используйте метод <code>beginTransaction()</code> для инициирования
            транзакции. Последующие SQL-операторы будут выполняться в контексте
            этой транзакции до тех пор, пока вы не завершите ее явным образом.
        </para>

        <para>
            Для завершения транзакции используйте методы <code>commit()</code>
            или <code>rollBack()</code>. Метод <code>commit()</code> помечает
            изменения, произведенные в течение данной транзакции, как
            зафиксированные, это означает, что результаты этих изменений будут
            видны в запросах, выполняемых в других транзакциях.
        </para>

        <para>
            Метод <code>rollBack()</code> делает обратное - он не учитывает
            изменения, произведенные в течение транзакции. Изменения будут
            эффективно отменены, и состояние данных вернется к тому, в котором
            они были до того, как была начата транзакция. Тем не менее, откат
            транзакции не повлияет на изменения, произведенные другими
            транзакциями, запущенными в это же время.
        </para>

        <para>
            После того, как вы завершите транзакцию,
            <code>Zend_Db_Adapter</code> вернется в режим автоматической
            фиксации до того, как вы не вызовете <code>beginTransaction()</code> снова.
        </para>

        <example id="zend.db.adapter.transactions.example">
            <title>Управление транзакциями для обеспечения согласованности данных</title>
            <programlisting language="php"><![CDATA[
// Старт транзакции явным образом
$db->beginTransaction();

try {
    // Попытка произвести один или несколько запросов
    $db->query(...);
    $db->query(...);
    $db->query(...);

    // Если все запросы были произведены успешно, то транзакция фиксируется,
    // и все изменения фиксируются одновременно
    $db->commit();

} catch (Exception $e) {
    // Если какой-либо из этих запросов прошел неудачно, то вся транзакция
    // откатывается, при этом все изменения отменяются, даже те, которые были
    // произведены успешно.
    // Таким образом, все изменения либо фиксируются, либо не фиксируется вместе.
    $db->rollBack();
    echo $e->getMessage();
}
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.db.adapter.list-describe">

        <title>Листинг и описание таблиц</title>

        <para>
            Метод <code>listTables()</code> возвращает массив имен всех
            таблиц в текущей базе данных.
        </para>

        <para>
            Метод <code>describeTable()</code> возвращает ассоциативный массив
            метаданных таблицы. Указывайте имя таблицы в качестве первого
            аргумента этого метода. Второй аргумент является опциональным, и
            обозначает схему, в которой существует эта таблица.
        </para>

        <para>
            Ключами возвращаемого ассоциативного массива являются имена столбцов
            таблицы. Значения, соответствующие этим столбцам, также являются
            ассоциативными массивами со следующими ключами и значениями:
        </para>

        <table frame="all" cellpadding="5" id="zend.db.adapter.list-describe.metadata">
            <title>Поля метаданных, возвращаемых методом describeTable()</title>
            <tgroup cols="3" align="left" colsep="1" rowsep="1">
                <thead>
                    <row>
                        <entry>Ключ</entry>
                        <entry>Тип</entry>
                        <entry>Описание</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>SCHEMA_NAME</entry>
                        <entry>(string)</entry>
                        <entry>Имя схемы БД, в которой находится эта таблица.</entry>
                    </row>
                    <row>
                        <entry>TABLE_NAME</entry>
                        <entry>(string)</entry>
                        <entry>Имя таблицы, которой принадлежит данный столбец.</entry>
                    </row>
                    <row>
                        <entry>COLUMN_NAME</entry>
                        <entry>(string)</entry>
                        <entry>Имя столбца</entry>
                    </row>
                    <row>
                        <entry>COLUMN_POSITION</entry>
                        <entry>(integer)</entry>
                        <entry>Порядковый номер столбца в таблице.</entry>
                    </row>
                    <row>
                        <entry>DATA_TYPE</entry>
                        <entry>(string)</entry>
                        <entry>Имя типа данных столбца, используемое в данной СУРБД</entry>
                    </row>
                    <row>
                        <entry>DEFAULT</entry>
                        <entry>(string)</entry>
                        <entry>Значение по умолчанию, если есть.</entry>
                    </row>
                    <row>
                        <entry>NULLABLE</entry>
                        <entry>(boolean)</entry>
                        <entry>TRUE, если столбец допускает значение NULL, иначе FALSE.</entry>
                    </row>
                    <row>
                        <entry>LENGTH</entry>
                        <entry>(integer)</entry>
                        <entry>Длина или значение столбца, сообщаемое СУРБД.</entry>
                    </row>
                    <row>
                        <entry>SCALE</entry>
                        <entry>(integer)</entry>
                        <entry>Масштаб для типа данных NUMERIC или DECIMAL.</entry>
                    </row>
                    <row>
                        <entry>PRECISION</entry>
                        <entry>(integer)</entry>
                        <entry>Точность для типа данных NUMERIC или DECIMAL.</entry>
                    </row>
                    <row>
                        <entry>UNSIGNED</entry>
                        <entry>(boolean)</entry>
                        <entry>TRUE, если целочисленный тип объявлен как UNSIGNED (беззнаковое число).</entry>
                    </row>
                    <row>
                        <entry>PRIMARY</entry>
                        <entry>(boolean)</entry>
                        <entry>TRUE, если столбец является частью первичного ключа этой таблицы.</entry>
                    </row>
                    <row>
                        <entry>PRIMARY_POSITION</entry>
                        <entry>(integer)</entry>
                        <entry>Порядковый номер (начинается с 1) данного столбца в первичном ключе.</entry>
                    </row>
                    <row>
                        <entry>IDENTITY</entry>
                        <entry>(boolean)</entry>
                        <entry>TRUE, если данный столбец использует автоматически генерируемые значения.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Если таблица, соответствующая заданным имени таблицы и имени схемы
            (опционально), не существует, то <code>describeTable()</code>
            возвращает пустой массив.
        </para>

        <note>
            <title>Как поле метаданных IDENTITY соотносится с типом СУРБД</title>
            <para>
                Поле метаданных IDENTITY было выбрано в качестве
                "идиоматического" термина для представления связи с
                суррогатными ключами. Это поле обычно знакомо под следующими
                именами:
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        <code>IDENTITY</code> - DB2, MSSQL
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>AUTO_INCREMENT</code> - MySQL
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>SERIAL</code> - PostgreSQL
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <code>SEQUENCE</code> - Oracle
                    </para>
                </listitem>
            </itemizedlist>
        </note>

    </sect2>

    <sect2 id="zend.db.adapter.closing">

        <title>Закрытие соединения</title>

        <para>
            Обычно нет необходимости в том, чтобы закрывать соединение с БД.
            PHP автоматически очищает все ресурсы в конце запроса. Расширения
            PHP для баз данных спроектированы таким образом, чтобы они закрывали
            соединение, когда удаляется ссылка на объект ресурса.
        </para>

        <para>
            Тем не менее, если у вас есть скрипт PHP длительного времени
            выполнения, который инициирует множество соединений с БД, то может
            потребоваться закрывать соединения, чтобы избежать снижения
            производительности сервера СУРБД. Вы можете использовать метод
            адаптера <code>closeConnection()</code> для явного закрытия лежащего
            в основе соединения с БД.
        </para>

        <example id="zend.db.adapter.closing.example">
            <title>Закрытие соединения с БД</title>
            <programlisting language="php"><![CDATA[
$db->closeConnection();
]]>
            </programlisting>
        </example>

        <note>
            <title>Поддерживает ли Zend_Db постоянные соединения?</title>
            <para>
                Использование постоянных соединений не поддерживается или
                рекомендуется в Zend_Db.
            </para>
            <para>
                Использование постоянных соединений может привести к избытку
                неиспользуемых соединений на сервере СУРБД, что приносит больше
                проблем, чем дает выигрыша в производительности, достигаемого
                путем уменьшения накладных расходов на установку соединений.
            </para>
            <para>
                Соединения с БД имеют свое состояние, т.е. некоторые объекты на
                сервере СУРБД существуют в области видимости сессии. Примером
                являются блокировки, пользовательские переменные, временные
                таблицы и информация о последних выполненных запросах, такая,
                как количество затронутых строк и последнее сгенерированное
                значение. Если вы используете постоянные соединения, то ваше
                приложение может получать неверные или привилегированные данные,
                созданные в предыдущем PHP-запросе.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.db.adapter.other-statements">

        <title>Запуск других операторов БД</title>

        <para>
            Может потребоваться получить прямой доступ к
            объекту соединения в том виде, в котором он предоставляется
            расширением PHP для баз данных. Некоторые из этих расширений могут
            предоставлять функционал, который не поддерживается методами
            Zend_Db_Adapter_Abstract.
        </para>

        <para>
            Например, все операторы SQL, запускаемые через Zend_Db,
            подготавливаются перед выполнением. Однако некоторый функционал баз
            данных несовместим с подготовленными операторами. Операторы DDL,
            такие, как CREATE и ALTER, не могут подготавливаться в MySQL. Также
            операторы SQL не дают выигрыша от
            <ulink url="http://dev.mysql.com/doc/refman/5.1/en/query-cache-how.html">кэширования запросов MySQL</ulink> в версиях MySQL до 5.1.17.
        </para>

        <para>
            Большинство расширений PHP для баз данных предоставляет метод для
            выполнения операторов SQL без их подготовки. Например, в PDO таким
            методом является <code>exec()</code>. Вы можете обратиться напрямую
            к объекту соединения в расширении PHP, используя getConnection().
        </para>

        <example id="zend.db.adapter.other-statements.example">
            <title>Запуск неподготовленного оператора в адаптере PDO</title>
            <programlisting language="php"><![CDATA[
$result = $db->getConnection()->exec('DROP TABLE bugs');
]]>
            </programlisting>
        </example>

        <para>
            Так же вы можете получить доступ к другим методам или свойствам,
            специфическим для данного расширения. Тем не менее, следует
            учитывать, что, делая это, вы можете ограничить ваше приложение
            интерфейсом, предоставляемым расширением для определенной
            СУРБД.
        </para>

        <para>
            В будущих версиях Zend_Db будет возможность добавить точки входа
            методов для функционала, который является общим для поддерживаемых
            расширений PHP. Это не нарушит обратную совместимость.
        </para>

    </sect2>

    <sect2 id="zend.db.adapter.adapter-notes">

        <title>Примечания к отдельным адаптерам</title>

        <para>
            В данный разделе описываются различия между классами адаптеров, о
            которых следует знать.
        </para>

        <sect3 id="zend.db.adapter.adapter-notes.ibm-db2">
            <title>IBM DB2</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Db2'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширение ibm_db2.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        IBM DB2 поддерживает как последовательности, так и
                        автоинкрементные ключи. Поэтому аргументы для
                        <code>lastInsertId()</code> являются опциональными. Если
                        вы не передадите аргументы, то адаптер вернет последнее
                        значение, сгенерированное для автоинкрементного ключа.
                        Если вы передадите аргументы, то адаптер вернет
                        последнее значение, сгенерированное последовательностью,
                        имя которой удовлетворяет соглашению
                        '<emphasis>таблица</emphasis>_<emphasis>имя</emphasis>_seq'.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.mysqli">
            <title>MySQLi</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Mysqli'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширение mysqli.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        MySQL не поддерживает последовательности, поэтому
                        <code>lastInsertId()</code> игнорирует переданные
                        аргументы и всегда возвращает последнее значение,
                        сгенерированное для автоинкрементного ключа. Метод
                        <code>lastSequenceId()</code> возвращает
                        <constant>NULL</constant>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.oracle">
            <title>Oracle</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Oracle'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширение oci8.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Oracle не поддерживает автоинкрементные ключи, поэтому
                        вы должны указывать имя последовательности для
                        <code>lastInsertId()</code> или
                        <code>lastSequenceId()</code>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Расширение Oracle не поддерживает позиционные параметры.
                        Вы должны использовать именованные параметры.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        На данный момент опция
                        <code>Zend_Db::CASE_FOLDING</code> не поддерживается
                        адаптером Oracle. Для того, чтобы применять эту опцию с
                        Oracle, вам нужно использовать адаптер PDO OCI.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-ibm">
            <title>PDO для IBM DB2 и Informix Dynamic Server (IDS)</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Ibm'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_ibm.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Вы должны использовать расширение PDO_IBM версии не ниже
                        1.2.2. Если вы используете более раннюю версию этого
                        расширения, то должны обновить расширение PDO_IBM из
                        PECL.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-mssql">
            <title>PDO Microsoft SQL Server</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Mssql'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_mssql.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Microsoft SQL Server не поддерживает последовательности,
                        поэтому <code>lastInsertId()</code> игнорирует
                        переданные аргументы и всегда возвращает последнее
                        значение, сгенерированное для автоинкрементного ключа.
                        Метод <code>lastSequenceId()</code> возвращает
                        <constant>NULL</constant>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Zend_Db_Adapter_Pdo_Mssql устанавливает
                        <code>QUOTED_IDENTIFIER ON</code> сразу после соединения
                        с сервером баз данных. Это заставляет драйвер
                        использовать стандартные символы-ограничители
                        идентификаторов (<code>"</code>) вместо квадратных
                        скобок, которые SQL Server использует в качестве
                        ограничителей идентификаторов.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Вы можете указывать <code>pdoType</code> в качестве
                        ключа в массиве опций. Возможными значениями могут быть
                        "mssql" (по умолчанию),
                        "dblib", "freetds" или "sybase". Эта опция влияет на
                        префикс DSN, который используется адаптером, когда
                        строится строка DSN. "Freetds" и "sybase" подразумевают
                        префикс "sybase:", который используется для набора
                        библиотек <ulink url="http://www.freetds.org/">FreeTDS</ulink>. Более
                        подробную информацию о префиксах, используемых в этих
                        драйверах, читайте на
                        <ulink url="http://www.php.net/manual/en/ref.pdo-dblib.connection.php">
                        http://www.php.net/manual/en/ref.pdo-dblib.connection.php</ulink>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-mysql">
            <title>PDO MySQL</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Mysql'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_mysql.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        MySQL не поддерживает последовательности,
                        поэтому <code>lastInsertId()</code> игнорирует
                        переданные аргументы и всегда возвращает последнее
                        значение, сгенерированное для автоинкрементного ключа.
                        Метод <code>lastSequenceId()</code> возвращает
                        <constant>NULL</constant>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-oci">
            <title>PDO Oracle</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Oci'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_oci.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Oracle не поддерживает автоинкрементные ключи, поэтому
                        вы должны указывать имя последовательности для
                        <code>lastInsertId()</code> или
                        <code>lastSequenceId()</code>.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-pgsql">
            <title>PDO PostgreSQL</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Pgsql'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_pgsql.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        PostgreSQL поддерживает как последовательности, так и
                        автоинкрементные ключи. Поэтому аргументы для
                        <code>lastInsertId()</code> являются опциональными. Если
                        вы не передадите аргументы, то адаптер вернет последнее
                        значение, сгенерированное для автоинкрементного ключа.
                        Если вы передадите аргументы, то адаптер вернет
                        последнее значение, сгенерированное последовательностью,
                        имя которой удовлетворяет соглашению
                        '<emphasis>таблица</emphasis>_<emphasis>имя</emphasis>_seq'.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.pdo-sqlite">
            <title>PDO SQLite</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Для установки этого адаптера через метод factory() используйте строку 'Pdo_Sqlite'.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширения pdo и pdo_sqlite.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        SQLite не поддерживает последовательности,
                        поэтому <code>lastInsertId()</code> игнорирует
                        переданные аргументы и всегда возвращает последнее
                        значение, сгенерированное для автоинкрементного ключа.
                        Метод <code>lastSequenceId()</code> возвращает
                        <constant>NULL</constant>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Для того, чтобы соединится с базой данных SQLite2,
                        указывайте <code>'sqlite2'=>true</code> в массиве
                        параметров при создании экземпляра адаптера Pdo_Sqlite.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Для соединения с базой данных SQLite в памяти указывайте
                        <code>'dbname'=>':memory:'</code> в массиве параметров
                        при создании экземпляра адаптера Pdo_Sqlite.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Старые версии драйвера SQLite для PHP могут не
                        поддерживать команды PRAGMA, необходимые для обеспечения
                        использования коротких имен столбцов в результатах. Если
                        имеются проблемы с тем, что результаты возвращаются с
                        ключами в виде "tablename.columnname", когда производится запрос с объединением таблиц, то следует обновить PHP до текущей версии.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.adapter.adapter-notes.firebird">
            <title>Firebird/Interbase</title>
            <itemizedlist>
                <listitem>
                    <para>
                        Этот адаптер использует PHP-расширение php_interbase.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Firebird/interbase  не поддерживает автоинкрементные
                        ключи, поэтому вы должны указывать имя
                        последовательности для
                        <code>lastInsertId()</code> или
                        <code>lastSequenceId()</code>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        На данный момент опция
                        <code>Zend_Db::CASE_FOLDING</code> не поддерживается
                        адаптером Firebird/interbase. Не заключенные в кавычки
                        идентификаторы автоматически возвращаются в верхнем
                        регистре..
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->