そのクラスが定義しているデータベースのテーブルを定義するには、 protected な変数 $_name を使用します。 これは文字列で、データベースでのテーブル名を指定する必要があります。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
}

テーブル名を指定しなかった場合のデフォルトは、クラス名となります。 このデフォルトを使用する場合は、クラス名をデータベースでのテーブル名と一致させる必要があります。

class bugs extends Zend_Db_Table_Abstract
{
    // テーブル名とクラス名が一致します
}

テーブルのスキーマについても、protected 変数 $_schema で宣言できます。 あるいは $_name プロパティでテーブル名の前にスキーマ名をつなげて指定することもできます。 $_name で指定したスキーマのほうが、 $_schema プロパティで指定したスキーマよりも優先されます。 RDBMS によってはスキーマのことを「データベース」や「表領域」 などということもありますが、同じように使用できます。 スキーマを、テーブル名の一部として宣言することもできます。

// 一つ目の方法
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_schema = 'bug_db';
    protected $_name   = 'bugs';
}

// 二つ目の方法
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_db.bugs';
}

// スキーマを $_name と $_schema の両方で指定した場合は、
// $_name で指定したものが優先されます

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name   = 'bug_db.bugs';
    protected $_schema = 'ignored';
}

スキーマ名とテーブル名は、コンストラクタの設定ディレクティブでも指定できます。 これは、$_name や $_schema といったプロパティで設定したデフォルト値を上書きします。 name ディレクティブで指定したスキーマ名は、 schema オプションで指定したスキーマ名より優先されます。

class Bugs extends Zend_Db_Table_Abstract
{
}

// 最初の方法

$tableBugs = new Bugs(array('name' => 'bugs', 'schema' => 'bug_db'));

// もうひとつの方法

$tableBugs = new Bugs(array('name' => 'bug_db.bugs'));

// スキーマを 'name' と 'schema' の両方で指定した場合は、
// 'name' で指定したものが優先されます

$tableBugs = new Bugs(array('name' => 'bug_db.bugs',
                            'schema' => 'ignored'));

スキーマ名を指定しなかった場合のデフォルトは、 そのデータベースアダプタが接続しているスキーマとなります。

すべてのテーブルは主キーを持たなければなりません。 主キーカラムを宣言するには、protected 変数 $_primary を使用します。 これは、単一のカラムの名前を表す文字列か、 もし主キーが複合キーの場合はカラム名の配列となります。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
    protected $_primary = 'bug_id';
}

主キーを指定しなかった場合は、Zend_Db_Table_Abstract は describeTable() メソッドの情報に基づいて主キーを見つけます。

テーブルクラスのインスタンスを作成する際に、 コンストラクタ内でいくつかの protected メソッドをコールします。 これにより、テーブルのメタデータを初期化します。 これらのメソッドを拡張して、メタデータを明示的に定義することも可能です。 その場合は、メソッドの最後で親クラスの同名のメソッドをコールすることを忘れないようにしましょう。

class Bugs extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        $this->_name = 'bugs';
        parent::_setupTableName();
    }
}

オーバーライドできるメソッドは、次のとおりです。

テーブルクラスの作成時にアプリケーション固有のロジックを初期化したい場合は、 その作業を init() メソッドで行います。 これは、テーブルのメタデータがすべて処理された後にコールされます。 メタデータを変更するつもりがないのなら、__construct メソッドよりもこちらを使用することを推奨します。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_observer;

    public function init()
    {
        $this->_observer = new MyObserverClass();
    }
}

データベースアダプタをテーブルクラスに指定する最初の方法は、 Zend_Db_Adapter_Abstract 型のオブジェクトをオプションの配列で渡すことです。 配列のキーは 'db' となります。

$db = Zend_Db::factory('PDO_MYSQL', $options);

$table = new Bugs(array('db' => $db));

データベースアダプタをテーブルクラスに指定する二番目の方法は、 デフォルトのデータベースアダプタとして Zend_Db_Adapter_Abstract 型のオブジェクトを宣言することです。そのアプリケーション内で、 これ以降に作成したテーブルインスタンスについてこれが用いられます。 これを行うには、静的メソッド Zend_Db_Table_Abstract::setDefaultAdapter() を使用します。引数は、Zend_Db_Adapter_Abstract 型のオブジェクトとなります。

$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Db_Table_Abstract::setDefaultAdapter($db);

// その後...

$table = new Bugs();

これは、たとえば起動ファイルなどでデータベースアダプタオブジェクトを作成し、 それをデフォルトのアダプタとして保存しておく場合などに便利です。 これにより、アプリケーション全体で共通のアダプタを使用することが保証されます。 しかし、デフォルトのアダプタのインスタンスは、ひとつだけしか設定できません。

データベースアダプタをテーブルクラスに指定する三番目の方法は、 文字列ををオプションの配列で渡すことです。 配列のキーは、この場合も 'db' となります。 この文字列は、静的な Zend_Registry インスタンスのキーとして使用します。 このキーのエントリが Zend_Db_Adapter_Abstract 型のオブジェクトとなります。

$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Registry::set('my_db', $db);

// その後...

$table = new Bugs(array('db' => 'my_db'));

デフォルトアダプタの指定と同様、これにより、 アプリケーション全体で共通のアダプタを使用することが保証されます。 レジストリには複数のアダプタインスタンスを保存できるため、 より柔軟に使用できます。指定したアダプタインスタンスは 特定の RDBMS やデータベースインスタンスに固有のものとなります。 複数のデータベースにアクセスする必要がある場合は、 複数のアダプタが必要です。

自動インクリメントの主キーは、SQL の INSERT 文で主キー列を省略した場合に一意な整数値を生成します。

Zend_Db_Table_Abstract で protected 変数 $_sequence の値を boolean の TRUE にすると、そのテーブルは自動インクリメントの主キーを持つものとみなされます。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    // これは Zend_Db_Table_Abstract クラスのデフォルト設定です。
    // 特に定義する必要はありません。
    protected $_sequence = true;
}

MySQL、Microsoft SQL Server そして SQLite などの RDBMS が、主キーの自動インクリメントをサポートしています。

PostgreSQL の SERIAL 記法を使用すると、 テーブル名とカラム名をもとにして暗黙的にシーケンスを定義します。 新しい行を作成した際にはこのシーケンスを用いてキーの値を生成します。 IBM DB2 には、これと同等の動作をする IDENTIFY という記法があります。 これらの記法を使用する場合は、Zend_Db_Table クラスで $_sequence を TRUE と設定し、 自動インクリメントを有効にしてください。

シーケンスとはデータベースのオブジェクトの一種で、 一意な値を生成するものです。これを、 ひとつあるいは複数のテーブルの主キーの値として使用できます。

$_sequence に文字列を設定すると、 Zend_Db_Table_Abstract は、それがデータベースの シーケンスオブジェクトの名前であるとみなします。 シーケンスを実行して新しい値を生成し、その値を INSERT 操作で使用します。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    protected $_sequence = 'bug_sequence';
}

Oracle、PostgreSQL そして IBM DB2 などの RDBMS が、 データベースでのシーケンスオブジェクトをサポートしています。

PostgreSQL および IBM DB2 は、 暗黙的にシーケンスを定義してカラムに関連付ける構文もサポートしています。 この記法を使う場合は、 そのテーブルで自動インクリメントキーのカラムを使用するようにします。 シーケンスのキーの次の値を取得することがある場合にのみ シーケンス名を文字列で定義します。

自然キーを持つテーブルもあります。自然キーとは、 テーブルやシーケンスによって自動生成されるもの以外のキーということです。 この場合は、主キーの値を指定する必要があります。

$_sequence の値を boolean の FALSE にすると、Zend_Db_Table_Abstract はそのテーブルが自然キーを持つものとみなします。 insert() メソッドを使用する際には、 主キーカラムの値をデータの配列で指定する必要があります。 指定しなかった場合、このメソッドは Zend_Db_Table_Exception をスローします。

class BugStatus extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_status';

    protected $_sequence = false;
}

/**
 * 行セットを取得します
 */
$rows = $table->fetchAll(
    'bug_status = "NEW"',
    'bug_id ASC',
    10,
    0
    );
$rows = $table->fetchAll(
    $table->select()
        ->where('bug_status = ?', 'NEW')
        ->order('bug_id ASC')
        ->limit(10, 0)
    );
// またはバインディングを用いて
$rows = $table->fetchAll(
    $table->select()
        ->where('bug_status = :status')
        ->bind(array(':status'=>'NEW')
        ->order('bug_id ASC')
        ->limit(10, 0)
    );

/**
 * 単一の行を取得します
 */
$row = $table->fetchRow(
    'bug_status = "NEW"',
    'bug_id ASC'
    );
$row = $table->fetchRow(
    $table->select()
        ->where('bug_status = ?', 'NEW')
        ->order('bug_id ASC')
    );
// またはバインディングを用いて
$row = $table->fetchRow(
    $table->select()
        ->where('bug_status = :status')
        ->bind(array(':status'=>'NEW')
        ->order('bug_id ASC')
    );

Zend_Db_Table_Select オブジェクトは Zend_Db_Select を継承したものであり、 クエリにはいくつか制限があります。追加された機能や制限事項を以下にまとめます。

$table = new Bugs();

$select = $table->select();
$select->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);

このコンポーネントでは「流れるようなインターフェイス」 を実装しているので、この例はもっと省略して書くこともできます。

$table = new Bugs();

$rows =
    $table->fetchAll($table->select()->where('bug_status = ?', 'NEW'));

主キーの値以外を条件として行のセットを問い合わせるには、 テーブルクラスの fetchAll() メソッドを使用します。 このメソッドは、Zend_Db_Table_Rowset_Abstract 型のオブジェクトを返します。

$table = new Bugs();

$select = $table->select()->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);

ORDER BY での並べ替えの条件句やオフセットを表す整数値を指定して、 クエリの返す結果を絞りこむことができます。 これらの値は LIMIT 句で用いられます。 LIMIT 構文をサポートしていない RDBMS では、それと同等のロジックで用いられます。

$table = new Bugs();

$order  = 'bug_id';

// 21 番目から 30 番目の行を返します
$count  = 10;
$offset = 20;

$select = $table->select()->where('bug_status = ?', 'NEW')
                          ->order($order)
                          ->limit($count, $offset);

$rows = $table->fetchAll($select);

これらのオプションはどれも、必須ではありません。 ORDER 句を省略した場合は、結果セットに複数の行が含まれる場合の並び順は予測不可能です。 LIMIT 句を省略した場合は、WHERE 句にマッチするすべての行を取得することになります。

リクエストの内容をより明確に指定して最適化するために、 行/行セットが返すカラムの数を絞り込みたいこともあるでしょう。 これは、select オブジェクトの FROM 句で行います。 FROM 句の最初の引数は Zend_Db_Select オブジェクトと同じですが、 さらに Zend_Db_Table_Abstract のインスタンスを渡すこともでき、テーブル名を自動的に検出します。

$table = new Bugs();

$select = $table->select();
$select->from($table, array('bug_id', 'bug_description'))
       ->where('bug_status = ?', 'NEW');

$rows = $table->fetchAll($select);

FROM 句で式を指定すると、その結果を readOnly の行/行セット として返します。この例では、bugs テーブルを検索して 個人別のバグの報告件数を取得しています。 GROUP 句に注目しましょう。これで、返される行に 'count' というカラムが含まれるようになり、 スキーマの他のカラムと同じようにアクセスできるようになります。

$table = new Bugs();

$select = $table->select();
$select->from($table,
              array('COUNT(reported_by) as `count`', 'reported_by'))
       ->where('bug_status = ?', 'NEW')
       ->group('reported_by');

$rows = $table->fetchAll($select);

クエリの一部にルックアップテーブルを使用し、 より絞り込んで取得することもできます。 この例では、検索時に accounts テーブルを使用して 'Bob' が報告したすべてのバグを探しています。

$table = new Bugs();

// join する際には、from 部を指定して取得するのが重要です
$select = $table->select(Zend_Db_Table::SELECT_WITH_FROM_PART);
$select->setIntegrityCheck(false)
       ->where('bug_status = ?', 'NEW')
       ->join('accounts', 'accounts.account_name = bugs.reported_by')
       ->where('accounts.account_name = ?', 'Bob');

$rows = $table->fetchAll($select);

Zend_Db_Table_Select の主な使用目的は、 制約を強要して正しい形式の SELECT クエリを作成することです。 しかし時には、Zend_Db_Table_Row の柔軟性が必要であって 行を更新したり削除したりすることはないということもあります。 そんな場合には、setIntegrityCheck に FALSE を渡して行/行セットを取得できます。 この場合に返される行/行セットは 'ロックされた' 行 (save()、delete() やフィールドの設定用メソッドを実行すると例外が発生する) となります。

$table = new Bugs();

$select = $table->select(Zend_Db_Table::SELECT_WITH_FROM_PART)
                ->setIntegrityCheck(false);
$select->where('bug_status = ?', 'NEW')
       ->join('accounts',
              'accounts.account_name = bugs.reported_by',
              'account_name')
       ->where('accounts.account_name = ?', 'Bob');

$rows = $table->fetchAll($select);

メタデータのキャッシュをより高速にするために、 メタデータをハードコーディングすることもできます。 しかし、そうすると、 テーブルのスキーマが変わるたびにコードを変更しなければならなくなります。 この方法をおすすめできるのは、 実運用環境で最適化が必要となった場合のみです。

メタデータの構造は次のようになります。

protected $_metadata = array(
    '<column_name>' => array(
        'SCHEMA_NAME'      => <string>,
        'TABLE_NAME'       => <string>,
        'COLUMN_NAME'      => <string>,
        'COLUMN_POSITION'  => <int>,
        'DATA_TYPE'        => <string>,
        'DEFAULT'          => NULL|<value>,
        'NULLABLE'         => <bool>,
        'LENGTH'           => <string - length>,
        'SCALE'            => NULL|<value>,
        'PRECISION'        => NULL|<value>,
        'UNSIGNED'         => NULL|<bool>,
        'PRIMARY'          => <bool>,
        'PRIMARY_POSITION' => <int>,
        'IDENTITY'         => <bool>,
    ),
    // さらなるカラム...
);

適切な値を知るには、メタデータキャッシュを使用するのが簡単でしょう。 キャッシュに格納された値をデシリアライズするのです。

この最適化を無効にするには、 metadataCacheInClass フラグをオフにします。

// インスタンス作成時
$bugs = new Bugs(array('metadataCacheInClass' => false));

// その後
$bugs->setMetadataCacheInClass(false);

このフラグはデフォルトで有効になっています。この場合は、 $_metadata 配列はインスタンスの作成時にのみ作成されます。

デフォルトでは、テーブルクラスが返す行セットは 具象クラス Zend_Db_Table_Rowset のインスタンスであり、 行セットには具象クラス Zend_Db_Table_Row のインスタンスの集合が含まれます。 これらのいずれについても、別のクラスを使用することが可能です。 しかし、使用するクラスはそれぞれ Zend_Db_Table_Rowset_Abstract および Zend_Db_Table_Row_Abstract を継承したものでなければなりません。

行クラスおよび行セットクラスを指定するには、 テーブルのコンストラクタのオプション配列を使用します。 対応するキーは、それぞれ 'rowClass' および 'rowsetClass' となります。 ここには、クラスの名前を文字列で指定します。

class My_Row extends Zend_Db_Table_Row_Abstract
{
    ...
}

class My_Rowset extends Zend_Db_Table_Rowset_Abstract
{
    ...
}

$table = new Bugs(
    array(
        'rowClass'    => 'My_Row',
        'rowsetClass' => 'My_Rowset'
    )
);

$where = $table->getAdapter()->quoteInto('bug_status = ?', 'NEW')

// My_Rowset 型のオブジェクトを返します。
// その中には My_Row 型のオブジェクトの配列が含まれます。
$rows = $table->fetchAll($where);

クラスを変更するには、setRowClass() メソッドおよび setRowsetClass() メソッドを使用します。 これは、それ以降に作成される行および行セットに適用されます。 すでに出来上がっている行オブジェクトや行セットオブジェクトには 何の影響も及ぼしません。

$table = new Bugs();

$where = $table->getAdapter()->quoteInto('bug_status = ?', 'NEW')

// Zend_Db_Table_Rowset 型のオブジェクトを返します。
// その中には Zend_Db_Table_Row 型のオブジェクトの配列が含まれます。
$rowsStandard = $table->fetchAll($where);

$table->setRowClass('My_Row');
$table->setRowsetClass('My_Rowset');

// My_Rowset 型のオブジェクトを返します。
// その中には My_Row 型のオブジェクトの配列が含まれます。
$rowsCustom = $table->fetchAll($where);

// $rowsStandard オブジェクトはまだ存在しますが、なにも変更されていません

行クラスおよび行セットクラスについての詳細は 「Zend_Db_Table_Row(日本語)」 および 「Zend_Db_Table_Rowset(日本語)」 を参照ください。

テーブルクラスの insert() メソッドや update() メソッドをオーバーライドできます。 これにより、データベース操作の前に実行される独自のコードを実装できます。 最後に親クラスのメソッドをコールすることを忘れないようにしましょう。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    public function insert(array $data)
    {
        // タイムスタンプを追加します
        if (empty($data['created_on'])) {
            $data['created_on'] = time();
        }
        return parent::insert($data);
    }

    public function update(array $data, $where)
    {
        // タイムスタンプを追加します
        if (empty($data['updated_on'])) {
            $data['updated_on'] = time();
        }
        return parent::update($data, $where);
    }
}

delete() メソッドをオーバーライドすることもできます。

もし特定の条件によるテーブルの検索を頻繁に行うのなら、 独自の検索メソッドをテーブルクラスで実装できます。 大半の問い合わせは fetchAll() を用いて書くことができますが、 アプリケーション内の複数の箇所でクエリを実行する場合には 問い合わせ条件を指定するコードが重複してしまいます。 そんな場合は、テーブルクラスでメソッドを実装し、 よく使う問い合わせを定義しておいたほうが便利です。

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    public function findByStatus($status)
    {
        $where = $this->getAdapter()->quoteInto('bug_status = ?', $status);
        return $this->fetchAll($where, 'bug_id');
    }
}

テーブルのクラス名を RDBMS のテーブル名とあわせるために、 inflection (語尾変化) と呼ばれる文字列変換を使用することを好む方もいます。

たとえば、テーブルのクラス名が "BugsProducts" だとすると、クラスのプロパティ $_name を明示的に宣言しなかった場合は データベース内の物理的なテーブル "bugs_products" にマッチします。この関連付けでは、 "CamelCase" 形式のクラス名が小文字に変換され、単語の区切りがアンダースコアに変わります。

データベースのテーブル名を、クラス名とは独立したものにすることもできます。 その場合は、テーブルクラスのプロパティ $_name に、そのクラス名を指定します。

Zend_Db_Table_Abstract は、クラス名とテーブル名を関連付けるための語尾変化は行いません。 テーブルクラスで $_name の宣言を省略すると、 そのクラス名に正確に一致する名前のテーブルと関連付けられます。

データベースの識別子を変換することは、適切ではありません。 なぜなら、それは不明確な状態を引き起こし、 時には識別子にアクセスできなくなってしまうからです。 SQL の識別子をデータベース内にあるそのままの形式で扱うことで、 Zend_Db_Table_Abstract はシンプルで柔軟なものになっています。

語尾変化を行いたい場合は、その変換を独自に実装しなければなりません。そのためには テーブルクラスで _setupTableName() メソッドをオーバーライドします。 これを行うひとつの方法としては、Zend_Db_Table_Abstract を継承した抽象クラスを作成し、さらにそれを継承したテーブルクラスを作成するという方法があります。

abstract class MyAbstractTable extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        if (!$this->_name) {
            $this->_name = myCustomInflector(get_class($this));
        }
        parent::_setupTableName();
    }
}

class BugsProducts extends MyAbstractTable
{
}

語尾変化を行う関数を書くのはあなたの役割です。 Zend Framework にはそのような関数はありません。