コンストラクタを使用して、アダプタのインスタンスを作成することができます。 アダプタのコンストラクタが受け取る引数はひとつで、 接続を確立するために必要なパラメータを配列で渡します。

<?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() でそのアダプタを読み込むことはできません。 自分でクラスを読み込み、 コンストラクタを使用してインスタンスを作成する必要があります。

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);

アダプタクラスのインスタンスを作成した時点では、 まだ RDBMS サーバへの接続は行われません。 接続用のパラメータを内部で保持しておき、 実際にクエリを実行することになった時点で初めて接続を確立します。 これにより、アダプタオブジェクトをすばやく作成できるようになっています。 つまり、そのリクエストの中で 実際にデータベースクエリを発行するかどうかが確定していなくても、 とりあえずアダプタのインスタンスを作成しておくということもできます。

強制的に RDBMS との接続を確立する必要がある場合は、 getConnection() メソッドを使用します。 このメソッドは、対応する PHP 拡張モジュール用の接続オブジェクトを返します。 たとえば、PDO ドライバ系のアダプタクラスを使った場合は、 getConnection() は データベースとの接続を確立してから PDO オブジェクトを返します。

データベースへの接続時に発生する例外、 すなわち ID やパスワードの間違いなどを捕捉したい場合に、 これは役立つでしょう。 実際に接続を行うまで例外はスローされないので、 どこか一か所に例外処理をまとめておいたほうが アプリケーションがシンプルになって便利でしょう。

<?php

try {
    $db = Zend_Db::factory('Pdo_Mysql', $parameters);
    $db->getConnection();
} catch (Zend_Db_Adapter_Exception $e) {
    // ID かパスワードが間違っている、あるいは RDBMS が起動していないなど……
} catch (Zend_Exception $e) {
    // factory() が指定したアダプタクラスを読み込めなかったなど……
}

SQL の SELECT クエリの実行とその結果の取得を一度に行うには fetchAll() メソッドを使用します。

このメソッドの最初の引数には、SELECT 文を文字列で指定します。 あるいは、文字列ではなく Zend_Db_Select クラスのオブジェクトを指定することもできます。 オブジェクトを渡した場合は、アダプタの内部でそれを自動的に SELECT 文の文字列に変換します。

fetchAll() でその次に指定する引数は、 SQL 文中のパラメータプレースホルダを置換する値の配列となります。

<?php

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

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

デフォルトでは、fetchAll() は行の配列を返します。各行のデータは連想配列となります。 連署配列のキーは、列名かあるいは SELECT クエリで指定した列の別名となります。

返り値の形式を別のものにするには 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() メソッドは、 フェッチモードの設定にかかわらず、 結果のデータを値の配列で返します。 これは、クエリの最初のカラムのみを返します。 それ以外のカラムの内容は破棄されます。 別のカラムが必要な場合は 項9.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 クエリをうまく設計し、最初のカラムの値が一意になるようにしなければなりません。 もし最初のカラムに重複する値があれば、連想配列のエントリが上書きされてしまいます。 overwritten.

<?php

$db->setFetchMode(Zend_Db::FETCH_OBJ);

$result = $db->fetchAAssocssoc('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');

// this is a single string value
echo $result;

You can add new rows to a table in your database using the insert() method. The first argument is a string that names the table, and the second argument is an associative array, mapping column names to data values.

<?php

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

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

Columns you exclude from the array of data are not specified to the database. Therefore, they follow the same rules that an SQL INSERT statement follows: if the column has a DEFAULT clause, the column takes that value in the row created, otherwise the column is left in a NULL state.

By default, the values in your data array are inserted using parameters. This reduces risk of some types of security issues. You don't need to apply escaping or quoting to values in the data array.

You might need values in the data array to be treated as SQL expressions, in which case they should not be quoted. By default, all data values passed as strings are treated as string literals. To specify that the value is an SQL expression and therefore should not be quoted, pass the value in the data array as an object of type Zend_Db_Expr instead of a plain string.

<?php

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

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

Some RDBMS brands support auto-incrementing primary keys. A table defined this way generates a primary key value automatically during an INSERT of a new row. The return value of the insert() method is not the last inserted ID, because the table might not have an auto-incremented column. Instead, the return value is the number of rows affected (usually 1).

If your table is defined with an auto-incrementing primary key, you can call the lastInsertId() method after the insert. This method returns the last value generated in the scope of the current database connection.

<?php

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

// return the last value generated by an auto-increment column
$id = $db->lastInsertId();

Some RDBMS brands support a sequence object, which generates unique values to serve as primary key values. To support sequences, the lastInsertId() method accepts two optional string arguments. These arguments name the table and the column, assuming you have followed the convention that a sequence is named using the table and column names for which the sequence generates values, and a suffix "_seq". This is based on the convention used by PostgreSQL when naming sequences for SERIAL columns. For example, a table "bugs" with primary key column "bug_id" would use a sequence named "bugs_bug_id_seq".

<?php

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

// return the last value generated by sequence 'bugs_bug_id_seq'.
$id = $db->lastInsertId('bugs', 'bug_id');

// alternatively, return the last value generated by sequence 'bugs_seq'.
$id = $db->lastInsertId('bugs');

If the name of your sequence object does not follow this naming convention, use the lastSequenceId() method instead. This method takes a single string argument, naming the sequence literally.

<?php

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

// return the last value generated by sequence 'bugs_id_gen'.
$id = $db->lastSequenceId('bugs_id_gen');

For RDBMS brands that don't support sequences, including MySQL, Microsoft SQL Server, and SQLite, the arguments to the lastInsertId() method are ignored, and the value returned is the most recent value generated for any table by INSERT operations during the current connection. For these RDBMS brands, the lastSequenceId() method always returns null.

Why not use "SELECT MAX(id) FROM table"?

Sometimes this query returns the most recent primary key value inserted into the table. However, this technique is not safe to use in an environment where multiple clients are inserting records to the database. It is possible, and therefore is bound to happen eventually, that another client inserts another row in the instant between the insert performed by your client application and your query for the MAX(id) value. Thus the value returned does not identify the row you inserted, it identifies the row inserted by some other client. There is no way to know when this has happened. Using a strong transaction isolation mode such as "repeatable read" can mitigate this risk, but some RDBMS brands don't support the transaction isolation required for this, or else your application may use a lower transaction isolation mode by design. Furthermore, using an expression like "MAX(id)+1" to generate a new value for a primary key is not safe, because two clients could do this query simultaneously, and then both use the same calculated value for their next INSERT operation. All RDBMS brands provide mechanisms to generate unique values, and to return the last value generated. These mechanisms necessarily work outside of the scope of transaction isolation, so there is no chance of two clients generating the same value, and there is no chance that the value generated by another client could be reported to your client's connection as the last value generated.

You can update rows in a database table using the update() method of an Adapter. This method takes three arguments: the first is the name of the table; the second is an associative array mapping columns to change to new values to assign to these columns.

The values in the data array are treated as string literals. See 項9.1.4.1. 「Inserting Data」 for information on using SQL expressions in the data array.

The third argument is a string containing an SQL expression that is used as criteria for the rows to change. The values and identifiers in this argument are not quoted or escaped. You are responsible for ensuring that any dynamic content is interpolated into this string safely. See 項9.1.5. 「Quoting Values and Identifiers」 for methods to help you do this.

The return value is the number of rows affected by the update operation.

<?php

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

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

If you omit the third argument, then all rows in the database table are updated with the values specified in the data array.

If you provide an array of strings as the third argument, these strings are joined together as terms in an expression separated by AND operators.

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

// Resulting SQL is:
//  UPDATE "bugs" SET "update_on" = '2007-03-23', "bug_status" = 'FIXED'
//  WHERE ("reported_by" = 'goofy') AND ("bug_status" = 'OPEN')

You can delete rows from a database table using the delete() method. This method takes two arguments: the first is a string naming the table.

The second argument is a string containing an SQL expression that is used as criteria for the rows to delete. The values and identifiers in this argument are not quoted or escaped. You are responsible for ensuring that any dynamic content is interpolated into this string safely. See 項9.1.5. 「Quoting Values and Identifiers」 for methods to help you do this.

The return value is the number of rows affected by the delete operation.

<?php

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

If you omit the second argument, the result is that all rows in the database table are deleted.

If you provide an array of strings as the second argument, these strings are joined together as terms in an expression separated by AND operators.

The quote() method accepts a single argument, a scalar string value. It returns the value with special characters escaped in a manner appropriate for the RDBMS you are using, and surrounded by string value delimiters. The standard SQL string value delimiter is the single-quote (').

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

Note that the return value of quote() includes the quote delimiters around the string. This is different from some functions that escape special characters but do not add the quote delimiters, for example mysql_real_escape_string().

The most typical usage of quoting is to interpolate a PHP variable into a SQL expression or statement. You can use the quoteInto() method to do this in one step. This method takes two arguments: the first argument is a string containing a placeholder symbol (?), and the second argument is a value or PHP variable that should be substituted for that placeholder.

The placeholder symbol is the same symbol used by many RDBMS brands for positional parameters, but the quoteInto() method only emulates query parameters. The method simply interpolates the value into the string, escapes special characters, and applies quotes around it. True query parameters maintain the separation between the SQL string and the parameters as the statement is parsed in the RDBMS server.

<?php

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

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

Values are not the only part of SQL syntax that might need to be variable. If you use PHP variables to name tables, columns, or other identifiers in your SQL statements, you might need to quote these strings too. By default, SQL identifiers have syntax rules like PHP and most other programming languages. For example, identifiers should not contain spaces, certain punctuation or special characters, or international characters. Also certain words are reserved for SQL syntax, and should not be used as identifiers.

However, SQL has a feature called delimited identifiers, which allows broader choices for the spelling of identifiers. If you enclose a SQL identifier in the proper types of quotes, you can use identifiers with spellings that would be invalid without the quotes. Delimited identifiers can contain spaces, punctuation, or international characters. You can also use SQL reserved words if you enclose them in identifier delimiters.

The quoteIdentifier() method works like quote(), but it applies the identifier delimiter characters to the string according to the type of Adapter you use. For example, standard SQL uses double-quotes (") for identifier delimiters, and most RDBMS brands use that symbol. MySQL uses back-quotes (`) by default. The quoteIdentifier() method also escapes special characters within the string argument.

<?php

// we might have a table name that is an SQL reserved word
$tableName = $db->quoteIdentifier("order");

$sql = "SELECT * FROM $tableName";

echo $sql
// SELECT * FROM "order"

SQL delimited identifiers are case-sensitive, unlike unquoted identifiers. Therefore, if you use delimited identifiers, you must use the spelling of the identifier exactly as it is stored in your schema, including the case of the letters.

In most cases where SQL is generated within Zend_Db classes, the default is that all identifiers are delimited automatically. You can change this behavior with the option Zend_Db::AUTO_QUOTE_IDENTIFIERS. Specify this when instantiating the Adapter. See 例 9.4. 「ファクトリでの自動クォートオプションの指定」.