PHP5

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

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

$db = new Zend_Db_Adapter_Pdo_Mysql(array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
));
                

Вместо непосредственного использования конструктора адаптера можно создавать экземпляры адаптера, применяя статический метод Zend_Db::factory(). Этот метод динамически загружает файл класса адаптера, используя Zend_Loader::loadClass().

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

<?php
require_once 'Zend/Db.php';

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

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

<?php
require_once 'Zend/Db.php';

// Автоматически загружает класс 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'
));
                

Опционально вы можете заменить оба аргумента метода factory() объектом типа Zend_Config.

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

<?php
require_once 'Zend/Config.php';
require_once 'Zend/Db.php';

$config = new Zend_Config(
    array(
        'database' => array(
            'adapter' => 'Mysqli',
            'params' => array(
                'dbname' => 'test',
                'username' => 'webuser',
                'password' => 'secret',
            )
        )
    )
);

$db = Zend_Db::factory($config->database);
                

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

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

<?php
$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);
                

<?php
$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);
                

<?php
$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);
                

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

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

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

<?php
try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // возможно, неправильные параметры соединения или СУРБД не запущена
} catch (Zend_Exception $e) {
    // возможно, попытка загрузки требуемого класса адаптера потерпела неудачу
}
                

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

Первым аргументом этого метода должна быть строка, содержащая оператор SELECT. Также первым аргументом может быть объект класса Zend_Db_Select. Адаптер автоматически преобразует этот объект в строковое представление оператора SELECT.

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

<?php
$sql = 'SELECT * FROM bugs WHERE bug_id = ?';

$result = $db->fetchAll($sql, 2);
                

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

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

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

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

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

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

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

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

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

Метод fetchCol() возвращает данные в массиве значений безотносительно того, какое значение вы установили для режима извлечения. Он возвращает только первый столбец из возвращенных запросом. Все остальные столбцы, возвращенные запросом, не учитываются. Если вам нужно извлечь столбец, отличный от первого, то см. Раздел 10.2.3.4, «Извлечение одного столбца из набора результатов».

<?php
$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];
                

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

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

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

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

echo $result[2];
                

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

<?php
$db->setFetchMode(Zend_Db::FETCH_OBJ);

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

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

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

<?php
$result = $db->fetchOne('SELECT bug_status FROM bugs WHERE bug_id = 2');

// это единственное строковое значение
echo $result;
                

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

<?php
$data = array(
    'created_on'      => '2007-03-22',
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
                

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

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

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

<?php
$data = array(
    'created_on'      => new Zend_Db_Expr('CURDATE()'),
    'bug_description' => 'Something wrong',
    'bug_status'      => 'NEW'
);

$db->insert('bugs', $data);
                

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

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

<?php
$db->insert('bugs', $data);

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

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

<?php
$db->insert('bugs', $data);

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

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

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

<?php
$db->insert('bugs', $data);

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

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

Почему не используется "SELECT MAX(id) FROM table"?

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

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

Значения в массиве данных интерпретируются как строковые константы. Информацию об использовании выражений SQL в массиве данных см. в разделе Раздел 10.1.4.1, «Добавление данных».

Третий аргумент является строкой, содержащей выражение SQL, которое используется в качестве условия, при выполнении которого строка должна изменяться. Значения и идентификаторы в этом аргументе не заключаются в кавычки и не экранируются. Вы ответственны за то, чтобы все динамическое содержимое было безопасным образом включено в эту строку. Информацию о методах, которые помогут вам в этом, см. в разделе Раздел 10.1.5, «Заключение в кавычки значений и идентификаторов».

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

<?php
$data = array(
    'updated_on'      => '2007-03-23',
    'bug_status'      => 'FIXED'
);

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

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

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

<?php
$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')
                

Вы можете удалять строки из таблицы БД, используя метод delete(). Этот метод принимает два аргумента, первый из них является строкой с именем таблицы.

Второй аргумент является строкой, содержащей выражение SQL, который используется в качестве условия, при выполнении которого строка удаляется. Значения и идентификаторы в этом аргументе не заключаются в кавычки и не экранируются. Вы ответственны за то, чтобы весь динамический контент был безопасным образом включен в эту строку. Информацию о методах, которые помогут вам в этом, см. в разделе Раздел 10.1.5, «Заключение в кавычки значений и идентификаторов».

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

<?php
$n = $db->delete('bugs', 'bug_id = 3');
                

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

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

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

<?php
$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'
                

Обратите внимание, что возвращаемое методом quote() значение включает в себя окружающие кавычки. Этим метод отличается от некоторых функций, которые экранируют специальные символы, но не добавляют кавычки, например, mysql_real_escape_string().

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

SELECT * FROM atable WHERE intColumn = '123'
                

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

<?php
$value = '1234';
$sql = 'SELECT * FROM atable WHERE intColumn = '
     . $db->quote($value, 'INTEGER');

                

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

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

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

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

<?php
$sql = $db->quoteInto("SELECT * FROM bugs WHERE reported_by = ?", "O'Reilly");

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 'O\'Reilly'
                

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

<?php
$sql = $db->quoteInto("SELECT * FROM bugs WHERE bug_id = ?", '1234', 'INTEGER');

echo $sql;
// SELECT * FROM bugs WHERE reported_by = 1234
                

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

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

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

<?php
// мы можем иметь имя таблицы, которое является зарезервированным в SQL словом
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"
                

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

В большинстве случаев, когда SQL генерируется в классах Zend_Db, все идентификаторы по умолчанию автоматически заключаются в ограничители. Вы можете изменить это поведение с помощью опции Zend_Db::AUTO_QUOTE_IDENTIFIERS. Указывайте ее при инстанцировании объекта адаптера. См. Пример 10.6, «Передача фабрике опции автоматического заключения в кавычки».