repo_zf1/documentation/manual/en/module_specs/Zend_Db_Table.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.db.table">

    <title>Zend_Db_Table</title>

    <sect2 id="zend.db.table.introduction">

        <title>Introduction</title>

        <para>
            The <classname>Zend_Db_Table</classname> class is an object-oriented interface to database tables. It provides
            methods for many common operations on tables. The base class is extensible, so you can
            add custom logic.
        </para>

        <para>
            The <classname>Zend_Db_Table</classname> solution is an implementation of the
            <ulink url="http://www.martinfowler.com/eaaCatalog/tableDataGateway.html">Table Data
            Gateway</ulink> pattern. The solution also includes a class that implements the
            <ulink url="http://www.martinfowler.com/eaaCatalog/rowDataGateway.html">Row Data
            Gateway</ulink> pattern.
        </para>

    </sect2>

    <sect2 id="zend.db.table.defining">

        <title>Defining a Table Class</title>

        <para>
            For each table in your database that you want to access, define a class that extends
            <classname>Zend_Db_Table_Abstract</classname>.
        </para>

        <sect3 id="zend.db.table.defining.table-schema">

            <title>Defining the Table Name and Schema</title>

            <para>
                Declare the database table for which this class is defined, using the protected
                variable <code>$_name</code>. This is a string, and must contain the name of the
                table spelled as it appears in the database.
            </para>

            <example id="zend.db.table.defining.table-schema.example1">

                <title>Declaring a table class with explicit table name</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
}
]]></programlisting>

            </example>

            <para>
                If you don't specify the table name, it defaults to the name of the class. If you
                rely on this default, the class name must match the spelling of the table name as
                it appears in the database.
            </para>

            <example id="zend.db.table.defining.table-schema.example">

                <title>Declaring a table class with implicit table name</title>

                <programlisting role="php"><![CDATA[
class bugs extends Zend_Db_Table_Abstract
{
    // table name matches class name
}
]]></programlisting>

            </example>

            <para>
                You can also declare the schema for the table, either with the protected variable
                <code>$_schema</code>, or with the schema prepended to the table name in the
                <code>$_name</code> property. Any schema specified with the <code>$_name</code>
                property takes precedence over a schema specified with the <code>$_schema</code>
                property. In some RDBMS brands, the term for schema is "database" or "tablespace,"
                but it is used similarly.
            </para>

            <example id="zend.db.table.defining.table-schema.example3">

                <title>Declaring a table class with schema</title>

                <programlisting role="php"><![CDATA[
// First alternative:
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_schema = 'bug_db';
    protected $_name   = 'bugs';
}

// Second alternative:
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_db.bugs';
}

// If schemas are specified in both $_name and $_schema, the one
// specified in $_name takes precedence:

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name   = 'bug_db.bugs';
    protected $_schema = 'ignored';
}
]]></programlisting>

            </example>

            <para>
                The schema and table names may also be specified via constructor configuration
                directives, which override any default values specified with the
                <code>$_name</code> and <code>$_schema</code> properties. A schema specification
                given with the <code>name</code> directive overrides any value provided with the
                <code>schema</code> option.
            </para>

            <example id="zend.db.table.defining.table-schema.example.constructor">

                <title>Declaring table and schema names upon instantiation</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
}

// First alternative:

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

// Second alternative:

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

// If schemas are specified in both 'name' and 'schema', the one
// specified in 'name' takes precedence:

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

            </example>

            <para>
                If you don't specify the schema name, it defaults to the schema to which your
                database adapter instance is connected.
            </para>

        </sect3>

        <sect3 id="zend.db.table.defining.primary-key">

            <title>Defining the Table Primary Key</title>

            <para>
                Every table must have a primary key. You can declare the column for the primary key
                using the protected variable <code>$_primary</code>. This is either a string that
                names the single column for the primary key, or else it is an array of column names
                if your primary key is a compound key.
            </para>

            <example id="zend.db.table.defining.primary-key.example">

                <title>Example of specifying the primary key</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';
    protected $_primary = 'bug_id';
}
]]></programlisting>

            </example>

            <para>
                If you don't specify the primary key, <classname>Zend_Db_Table_Abstract</classname> tries to discover the
                primary key based on the information provided by the <code>describeTable()</code>´
                method.
            </para>

            <note>

                <para>
                    Every table class must know which column(s) can be used to address rows
                    uniquely. If no primary key column(s) are specified in the table class
                    definition or the table constructor arguments, or discovered in the table
                    metadata provided by <code>describeTable()</code>, then the table cannot be
                    used with <classname>Zend_Db_Table</classname>.
                </para>

            </note>

        </sect3>

        <sect3 id="zend.db.table.defining.setup">

            <title>Overriding Table Setup Methods</title>

            <para>
                When you create an instance of a Table class, the constructor calls a set of
                protected methods that initialize metadata for the table. You can extend any of
                these methods to define metadata explicitly. Remember to call the method of the
                same name in the parent class at the end of your method.
            </para>

            <example id="zend.db.table.defining.setup.example">

                <title>Example of overriding the _setupTableName() method</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected function _setupTableName()
    {
        $this->_name = 'bugs';
        parent::_setupTableName();
    }
}
]]></programlisting>

            </example>

            <para>
                The setup methods you can override are the following:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <code>_setupDatabaseAdapter()</code> checks that an adapter has been
                        provided; gets a default adapter from the registry if needed. By overriding
                        this method, you can set a database adapter from some other source.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>_setupTableName()</code> defaults the table name to the name of the
                        class. By overriding this method, you can set the table name before this
                        default behavior runs.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>_setupMetadata()</code> sets the schema if the table name contains
                        the pattern "schema.table"; calls <code>describeTable()</code> to get
                        metadata information; defaults the <code>$_cols</code> array to the columns
                        reported by <code>describeTable()</code>. By overriding this method, you
                        can specify the columns.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>_setupPrimaryKey()</code> defaults the primary key columns to those
                        reported by <code>describeTable()</code>; checks that the primary key
                        columns are included in the <code>$_cols</code> array. By overriding this
                        method, you can specify the primary key columns.
                    </para>
                </listitem>
            </itemizedlist>

        </sect3>

        <sect3 id="zend.db.table.initialization">

            <title>Table initialization</title>

            <para>
                If application-specific logic needs to be initialized when a Table class is
                constructed, you can select to move your tasks to the <code>init()</code> method,
                which is called after all Table metadata has been processed. This is recommended
                over the <code>__construct</code> method if you do not need to alter the metadata
                in any programmatic way.

                <example id="zend.db.table.defining.init.usage.example">

                    <title>Example usage of init() method</title>

                    <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_observer;

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

                </example>

            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.constructing">

        <title>Creating an Instance of a Table</title>

        <para>
            Before you use a Table class, create an instance using its constructor. The
            constructor's argument is an array of options. The most important option to a Table
            constructor is the database adapter instance, representing a live connection to an
            RDBMS. There are three ways of specifying the database adapter to a Table class, and
            these three ways are described below:
        </para>

        <sect3 id="zend.db.table.constructing.adapter">

            <title>Specifying a Database Adapter</title>

            <para>
                The first way to provide a database adapter to a Table class is by passing it as an
                object of type <classname>Zend_Db_Adapter_Abstract</classname> in the options array, identified by the key
                <code>'db'</code>.
            </para>

            <example id="zend.db.table.constructing.adapter.example">

                <title>Example of constructing a Table using an Adapter object</title>

                <programlisting role="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);

$table = new Bugs(array('db' => $db));
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.table.constructing.default-adapter">

            <title>Setting a Default Database Adapter</title>

            <para>
                The second way to provide a database adapter to a Table class is by declaring an
                object of type <classname>Zend_Db_Adapter_Abstract</classname> to be a default database adapter for all
                subsequent instances of Tables in your application. You can do this with the static
                method <classname>Zend_Db_Table_Abstract::setDefaultAdapter()</classname>. The argument is an
                object of type <classname>Zend_Db_Adapter_Abstract</classname>.
            </para>

            <example id="zend.db.table.constructing.default-adapter.example">

                <title>Example of constructing a Table using a the Default Adapter</title>

                <programlisting role="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Db_Table_Abstract::setDefaultAdapter($db);

// Later...

$table = new Bugs();
]]></programlisting>

            </example>

            <para>
                It can be convenient to create the database adapter object in a central place of
                your application, such as the bootstrap, and then store it as the default adapter.
                This gives you a means to ensure that the adapter instance is the same throughout
                your application. However, setting a default adapter is limited to a single adapter
                instance.
            </para>

        </sect3>

        <sect3 id="zend.db.table.constructing.registry">

            <title>Storing a Database Adapter in the Registry</title>

            <para>
                The third way to provide a database adapter to a Table class is by passing a string
                in the options array, also identified by the <code>'db'</code> key. The string is
                used as a key to the static <classname>Zend_Registry</classname> instance, where the entry at that key is
                an object of type <classname>Zend_Db_Adapter_Abstract</classname>.
            </para>

            <example id="zend.db.table.constructing.registry.example">

                <title>Example of constructing a Table using a Registry key</title>

                <programlisting role="php"><![CDATA[
$db = Zend_Db::factory('PDO_MYSQL', $options);
Zend_Registry::set('my_db', $db);

// Later...

$table = new Bugs(array('db' => 'my_db'));
]]></programlisting>

            </example>

            <para>
                Like setting the default adapter, this gives you the means to ensure that the same
                adapter instance is used throughout your application. Using the registry is more
                flexible, because you can store more than one adapter instance. A given adapter
                instance is specific to a certain RDBMS brand and database instance. If your
                application needs access to multiple databases or even multiple database brands,
                then you need to use multiple adapters.
            </para>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.insert">

        <title>Inserting Rows to a Table</title>

        <para>
            You can use the Table object to insert rows into the database table on which the Table
            object is based. Use the <code>insert()</code> method of your Table object. The
            argument is an associative array, mapping column names to values.
        </para>

        <example id="zend.db.table.insert.example">

            <title>Example of inserting to a Table</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$table->insert($data);
]]></programlisting>

        </example>

        <para>
            By default, the values in your data array are inserted as literal values, using
            parameters. If you need them to be treated as SQL expressions, you must make sure they
            are distinct from plain strings. Use an object of type <classname>Zend_Db_Expr</classname> to do this.
        </para>

        <example id="zend.db.table.insert.example-expr">

            <title>Example of inserting expressions to a Table</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

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

        </example>

        <para>
            In the examples of inserting rows above, it is assumed that the table has an
            auto-incrementing primary key. This is the default behavior of <classname>Zend_Db_Table_Abstract</classname>,
            but there are other types of primary keys as well. The following sections describe how
            to support different types of primary keys.
        </para>

        <sect3 id="zend.db.table.insert.key-auto">

            <title>Using a Table with an Auto-incrementing Key</title>

            <para>
                An auto-incrementing primary key generates a unique integer value for you if you
                omit the primary key column from your SQL <code>INSERT</code> statement.
            </para>

            <para>
                In <classname>Zend_Db_Table_Abstract</classname>, if you define the protected variable
                <code>$_sequence</code> to be the Boolean value <code>true</code>, then the class
                assumes that the table has an auto-incrementing primary key.
            </para>

            <example id="zend.db.table.insert.key-auto.example">

                <title>Example of declaring a Table with auto-incrementing primary key</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    // This is the default in the Zend_Db_Table_Abstract class;
    // you do not need to define this.
    protected $_sequence = true;
}
]]></programlisting>

            </example>

            <para>
                MySQL, Microsoft SQL Server, and SQLite are examples of RDBMS brands that support
                auto-incrementing primary keys.
            </para>

            <para>
                PostgreSQL has a <code>SERIAL</code> notation that implicitly defines a sequence
                based on the table and column name, and uses the sequence to generate key values
                for new rows. IBM DB2 has an <code>IDENTITY</code> notation that works similarly.
                If you use either of these notations, treat your <classname>Zend_Db_Table</classname> class as having an
                auto-incrementing column with respect to declaring the <code>$_sequence</code>
                member as <code>true</code>.
            </para>

        </sect3>

        <sect3 id="zend.db.table.insert.key-sequence">

            <title>Using a Table with a Sequence</title>

            <para>
                A sequence is a database object that generates a unique value, which can be used
                as a primary key value in one or more tables of the database.
            </para>

            <para>
                If you define <code>$_sequence</code> to be a string, then <classname>Zend_Db_Table_Abstract</classname>
                assumes the string to name a sequence object in the database. The sequence is
                invoked to generate a new value, and this value is used in the <code>INSERT</code>
                operation.
            </para>

            <example id="zend.db.table.insert.key-sequence.example">

                <title>Example of declaring a Table with a sequence</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    protected $_sequence = 'bug_sequence';
}
]]></programlisting>

            </example>

            <para>
                Oracle, PostgreSQL, and IBM DB2 are examples of RDBMS brands that support sequence
                objects in the database.
            </para>

            <para>
                PostgreSQL and IBM DB2 also have syntax that defines sequences implicitly and
                associated with columns. If you use this notation, treat the table as having an
                auto-incrementing key column. Define the sequence name as a string only in cases
                where you would invoke the sequence explicitly to get the next key value.
            </para>

        </sect3>

        <sect3 id="zend.db.table.insert.key-natural">

            <title>Using a Table with a Natural Key</title>

            <para>
                Some tables have a natural key. This means that the key is not automatically
                generated by the table or by a sequence. You must specify the value for the primary
                key in this case.
            </para>

            <para>
                If you define the <code>$_sequence</code> to be the Boolean value
                <code>false</code>, then <classname>Zend_Db_Table_Abstract</classname> assumes that the table has a
                natural primary key. You must provide values for the primary key columns in the
                array of data to the <code>insert()</code> method, or else this method throws a
                <classname>Zend_Db_Table_Exception</classname>.
            </para>

            <example id="zend.db.table.insert.key-natural.example">

                <title>Example of declaring a Table with a natural key</title>

                <programlisting role="php"><![CDATA[
class BugStatus extends Zend_Db_Table_Abstract
{
    protected $_name = 'bug_status';

    protected $_sequence = false;
}
]]></programlisting>

            </example>

            <note>

                <para>
                    All RDBMS brands support tables with natural keys. Examples of tables that are
                    often declared as having natural keys are lookup tables, intersection tables in
                    many-to-many relationships, or most tables with compound primary keys.
                </para>

            </note>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.update">

        <title>Updating Rows in a Table</title>

        <para>
            You can update rows in a database table using the <code>update</code> method of a Table
            class. This method takes two arguments: an associative array of columns to change and
            new values to assign to these columns; and an SQL expression that is used in a
            <code>WHERE</code> clause, as criteria for the rows to change in the
            <code>UPDATE</code> operation.
        </para>

        <example id="zend.db.table.update.example">

            <title>Example of updating rows in a Table</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$where = $table->getAdapter()->quoteInto('bug_id = ?', 1234);

$table->update($data, $where);
]]></programlisting>

        </example>

        <para>
            Since the table <code>update()</code> method proxies to the database adapter
            <link linkend="zend.db.adapter.write.update"><code>update()</code></link> method, the
            second argument can be an array of SQL expressions. The expressions are combined as
            Boolean terms using an <code>AND</code> operator.
        </para>

        <note>

            <para>
                The values and identifiers in the SQL expression are not quoted for you. If you
                have values or identifiers that require quoting, you are responsible for doing
                this. Use the <code>quote()</code>, <code>quoteInto()</code>, and
                <code>quoteIdentifier()</code> methods of the database adapter.
            </para>

        </note>

    </sect2>

    <sect2 id="zend.db.table.delete">

        <title>Deleting Rows from a Table</title>

        <para>
            You can delete rows from a database table using the <code>delete()</code> method. This
            method takes one argument, which is an SQL expression that is used in a
            <code>WHERE</code> clause, as criteria for the rows to delete.
        </para>

        <example id="zend.db.table.delete.example">

            <title>Example of deleting rows from a Table</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

$where = $table->getAdapter()->quoteInto('bug_id = ?', 1235);

$table->delete($where);
]]></programlisting>

        </example>

        <para>
            Since the table <code>delete()</code> method proxies to the database adapter
            <link linkend="zend.db.adapter.write.delete"><code>delete()</code></link> method, the
            argument can also be an array of SQL expressions. The expressions are combined as
            Boolean terms using an <code>AND</code> operator.
        </para>

        <note>

            <para>
                The values and identifiers in the SQL expression are not quoted for you. If you
                have values or identifiers that require quoting, you are responsible for doing
                this. Use the <code>quote()</code>, <code>quoteInto()</code>, and
                <code>quoteIdentifier()</code> methods of the database adapter.
            </para>

        </note>

    </sect2>

    <sect2 id="zend.db.table.find">

        <title>Finding Rows by Primary Key</title>

        <para>
            You can query the database table for rows matching specific values in the primary key,
            using the <code>find()</code> method. The first argument of this method is either a
            single value or an array of values to match against the primary key of the table.
        </para>

        <example id="zend.db.table.find.example">

            <title>Example of finding rows by primary key values</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

// Find a single row
// Returns a Rowset
$rows = $table->find(1234);

// Find multiple rows
// Also returns a Rowset
$rows = $table->find(array(1234, 5678));
]]></programlisting>

        </example>

        <para>
            If you specify a single value, the method returns at most one row, because a primary
            key cannot have duplicate values and there is at most one row in the database table
            matching the value you specify. If you specify multiple values in an array, the method
            returns at most as many rows as the number of distinct values you specify.
        </para>

        <para>
            The <code>find()</code> method might return fewer rows than the number of values you
            specify for the primary key, if some of the values don't match any rows in the database
            table. The method even may return zero rows. Because the number of rows returned is
            variable, the <code>find()</code> method returns an object of type
            <classname>Zend_Db_Table_Rowset_Abstract</classname>.
        </para>

        <para>
            If the primary key is a compound key, that is, it consists of multiple columns, you can
            specify the additional columns as additional arguments to the <code>find()</code>
            method. You must provide as many arguments as the number of columns in the table's
            primary key.
        </para>

        <para>
            To find multiple rows from a table with a compound primary key, provide an array for
            each of the arguments. All of these arrays must have the same number of elements. The
            values in each array are formed into tuples in order; for example, the first element
            in all the array arguments define the first compound primary key value, then the second
            elements of all the arrays define the second compound primary key value, and so on.
        </para>

        <example id="zend.db.table.find.example-compound">

            <title>Example of finding rows by compound primary key values</title>

            <para>
                The call to <code>find()</code> below to match multiple rows can match two rows in
                the database. The first row must have primary key value (1234, 'ABC'), and the
                second row must have primary key value (5678, 'DEF').
            </para>

            <programlisting role="php"><![CDATA[
class BugsProducts extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs_products';
    protected $_primary = array('bug_id', 'product_id');
}

$table = new BugsProducts();

// Find a single row with a compound primary key
// Returns a Rowset
$rows = $table->find(1234, 'ABC');

// Find multiple rows with compound primary keys
// Also returns a Rowset
$rows = $table->find(array(1234, 5678), array('ABC', 'DEF'));
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.db.table.fetch-all">

        <title>Querying for a Set of Rows</title>

        <sect3 id="zend.db.table.fetch-all.select">

            <title>Select API</title>

            <para>

                <warning>

                    <para>
                        The API for fetch operations has been superseded to allow a
                        <classname>Zend_Db_Table_Select</classname> object to modify the query. However, the
                        deprecated usage of the <code>fetchRow()</code> and <code>fetchAll()</code>
                        methods will continue to work without modification.
                    </para>

                    <para>
                        The following statements are all legal and functionally identical, however
                        it is recommended to update your code to take advantage of the new usage
                        where possible.
                    </para>

                    <para>

                        <programlisting role="php"><![CDATA[
// Fetching a rowset
$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));

// Fetching a single row
$row = $table->fetchRow('bug_status = "NEW"', 'bug_id ASC');
$row = $table->fetchRow($table->select()->where('bug_status = ?', 'NEW')
                                        ->order('bug_id ASC'));
]]></programlisting>

                    </para>

                </warning>

            </para>

            <para>
                The <classname>Zend_Db_Table_Select</classname> object is an extension of the
                <classname>Zend_Db_Select</classname> object that applies specific restrictions to
                a query. The enhancements and restrictions are:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        You <emphasis>can</emphasis> elect to return a subset of columns within a
                        fetchRow or fetchAll query. This can provide optimization benefits where
                        returning a large set of results for all columns is not desirable.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        You <emphasis>can</emphasis> specify columns that evaluate expressions from
                        within the selected table. However this will mean that the returned row or
                        rowset will be <property>readOnly</property> and cannot be used for save()
                        operations. A <classname>Zend_Db_Table_Row</classname> with
                        <property>readOnly</property> status will throw an exception if a
                        <code>save()</code> operation is attempted.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        You <emphasis>can</emphasis> allow JOIN clauses on a select to allow
                        multi-table lookups.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        You <emphasis>can not</emphasis> specify columns from a JOINed tabled to be
                        returned in a row/rowset. Doing so will trigger a PHP error. This was done
                        to ensure the integrity of the <classname>Zend_Db_Table</classname> is retained. i.e.
                        A <classname>Zend_Db_Table_Row</classname> should only reference columns derived from
                        its parent table.
                    </para>
                </listitem>
            </itemizedlist>

            <para>

                <example id="zend.db.table.qry.rows.set.simple.usage.example">

                    <title>Simple usage</title>

                    <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>
                Fluent interfaces are implemented across the component, so this can be rewritten
                this in a more abbreviated form.
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.fluent.interface.example">

                    <title>Example of fluent interface</title>

                    <programlisting role="php"><![CDATA[
$table = new Bugs();

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

                </example>

            </para>

        </sect3>

        <sect3 id="zend.db.table.fetch-all.usage">

            <title>Fetching a rowset</title>

            <para>
                You can query for a set of rows using any criteria other than the primary key
                values, using the <code>fetchAll()</code> method of the Table class. This method
                returns an object of type <classname>Zend_Db_Table_Rowset_Abstract</classname>.
            </para>

            <example id="zend.db.table.qry.rows.set.finding.row.example">

                <title>Example of finding rows by an expression</title>

                <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$rows = $table->fetchAll($select);
]]></programlisting>

            </example>

            <para>
                You may also pass sorting criteria in an <code>ORDER BY</code> clause, as well as
                count and offset integer values, used to make the query return a specific subset of
                rows. These values are used in a <code>LIMIT</code> clause, or in equivalent logic
                for RDBMS brands that do not support the <code>LIMIT</code> syntax.
            </para>

            <example id="zend.db.table.fetch-all.example2">

                <title>Example of finding rows by an expression</title>

                <programlisting role="php"><![CDATA[
$table = new Bugs();

$order  = 'bug_id';

// Return the 21st through 30th rows
$count  = 10;
$offset = 20;

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

$rows = $table->fetchAll($select);
]]></programlisting>

            </example>

            <para>
                All of the arguments above are optional. If you omit the ORDER clause, the result
                set includes rows from the table in an unpredictable order. If no LIMIT clause is
                set, you retrieve every row in the table that matches the WHERE clause.
            </para>

        </sect3>

        <sect3 id="zend.db.table.advanced.usage">

            <title>Advanced usage</title>

            <para>
                For more specific and optimized requests, you may wish to limit the number of
                columns returned in a row/rowset. This can be achieved by passing a FROM clause to
                the select object. The first argument in the FROM clause is identical to that of a
                <classname>Zend_Db_Select</classname> object with the addition of being able to pass an instance of
                <classname>Zend_Db_Table_Abstract</classname> and have it automatically determine the table name.
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.retrieving.a.example">

                    <title>Retrieving specific columns</title>

                    <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>

                <important>

                    <para>
                        The rowset contains rows that are still 'valid' - they simply contain a
                        subset of the columns of a table. If a save() method is called on a partial
                        row then only the fields available will be modified.
                    </para>

                </important>

                You can also specify expressions within a FROM clause and have these returned as a
                readOnly row/rowset. In this example we will return a rows from the bugs table that
                show an aggregate of the number of new bugs reported by individuals. Note the GROUP
                clause. The 'count' column will be made available to the row for evaluation and can
                be accessed as if it were part of the schema.
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.retrieving.b.example">

                    <title>Retrieving expressions as columns</title>

                    <programlisting role="php"><![CDATA[
$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);
]]></programlisting>

                </example>

                You can also use a lookup as part of your query to further refine your fetch
                operations. In this example the accounts table is queried as part of a search for
                all new bugs reported by 'Bob'.
            </para>

            <para>

                <example id="zend.db.table.qry.rows.set.refine.example">

                    <title>Using a lookup table to refine the results of fetchAll()</title>

                    <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$rows = $table->fetchAll($select);
]]></programlisting>

                </example>

            </para>

            <para>
                The <classname>Zend_Db_Table_Select</classname> is primarily used to constrain and
                validate so that it may enforce the criteria for a legal SELECT query. However
                there may be certain cases where you require the flexibility of the
                <classname>Zend_Db_Table_Row</classname> component and do not require a writable or deletable row. For
                this specific user case, it is possible to retrieve a row/rowset by passing a false
                value to setIntegrityCheck. The resulting row/rowset will be returned as a 'locked'
                row (meaning the save(), delete() and any field-setting methods will throw an
                exception).
            </para>

            <example id="zend.db.table.qry.rows.set.integrity.example">

                <title>Removing the integrity check on Zend_Db_Table_Select to allow JOINed rows</title>

                <programlisting><![CDATA[
$table = new Bugs();

$select = $table->select()->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);
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.table.fetch-row">

        <title>Querying for a Single Row</title>

        <para>
            You can query for a single row using criteria similar to that of the
            <code>fetchAll()</code> method.
        </para>

        <example id="zend.db.table.fetch-row.example1">

            <title>Example of finding a single row by an expression</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

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

$row = $table->fetchRow($select);
]]></programlisting>

        </example>

        <para>
            This method returns an object of type <classname>Zend_Db_Table_Row_Abstract</classname>. If the search
            criteria you specified match no rows in the database table, then
            <code>fetchRow()</code> returns PHP's <code>null</code> value.
        </para>

    </sect2>

    <sect2 id="zend.db.table.info">

        <title>Retrieving Table Metadata Information</title>

        <para>
            The <classname>Zend_Db_Table_Abstract</classname> class provides some information about its metadata. The
            <code>info()</code> method returns an array structure with information about the table,
            its columns and primary key, and other metadata.
        </para>

        <example id="zend.db.table.info.example">

            <title>Example of getting the table name</title>

            <programlisting role="php"><![CDATA[
$table = new Bugs();

$info = $table->info();

echo "The table name is " . $info['name'] . "\n";
]]></programlisting>

        </example>

        <para>
            The keys of the array returned by the <code>info()</code> method are described below:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis role="strong">name</emphasis> => the name of the table.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">cols</emphasis> => an array, naming the column(s) of
                    the table.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">primary</emphasis> => an array, naming the column(s) in
                    the primary key.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">metadata</emphasis> => an associative array, mapping
                    column names to information about the columns. This is the information returned
                    by the <code>describeTable()</code> method.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">rowClass</emphasis> => the name of the concrete class
                    used for Row objects returned by methods of this table instance. This defaults
                    to <classname>Zend_Db_Table_Row</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">rowsetClass</emphasis> => the name of the concrete
                    class used for Rowset objects returned by methods of this table instance. This
                    defaults to <classname>Zend_Db_Table_Rowset</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">referenceMap</emphasis> => an associative array, with
                    information about references from this table to any parent tables. See
                    <xref linkend="zend.db.table.relationships.defining" />.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">dependentTables</emphasis> => an array of class names
                    of tables that reference this table. See
                    <xref linkend="zend.db.table.relationships.defining" />.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis role="strong">schema</emphasis> => the name of the schema (or
                    database or tablespace) for this table.
                </para>
            </listitem>
        </itemizedlist>

    </sect2>

    <sect2 id="zend.db.table.metadata.caching">

        <title>Caching Table Metadata</title>

        <para>
            By default, <classname>Zend_Db_Table_Abstract</classname> queries the
            underlying database for <link linkend="zend.db.table.info">table
                metadata</link> whenever that data is needed to perform table
            operations. The table object fetches the table metadata from the
            database using the adapter's <code>describeTable()</code> method.
            Operations requiring this introspection include:
        </para>

        <itemizedlist>
            <listitem><para><code>insert()</code></para></listitem>

            <listitem><para><code>find()</code></para></listitem>

            <listitem><para><code>info()</code></para></listitem>
        </itemizedlist>

        <para>
            In some circumstances, particularly when many table objects are instantiated against
            the same database table, querying the database for the table metadata for each instance
            may be undesirable from a performance standpoint. In such cases, users may benefit by
            caching the table metadata retrieved from the database.
        </para>

        <para>
            There are two primary ways in which a user may take advantage of table metadata
            caching:

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis role="strong">Call
                        <classname>Zend_Db_Table_Abstract::setDefaultMetadataCache()</classname></emphasis> - This allows
                        a developer to once set the default cache object to be used for all table
                        classes.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="strong">Configure
                        <classname>Zend_Db_Table_Abstract::__construct()</classname></emphasis> - This allows a developer
                        to set the cache object to be used for a particular table class instance.
                    </para>
                </listitem>
            </itemizedlist>

            In both cases, the cache specification must be either <code>null</code> (i.e., no cache
            used) or an instance of
            <link linkend="zend.cache.frontends.core"><classname>Zend_Cache_Core</classname></link>. The
            methods may be used in conjunction when it is desirable to have both a default metadata
            cache and the ability to change the cache for individual table objects.
        </para>

        <example id="zend.db.table.metadata.caching-default">

            <title>Using a Default Metadata Cache for all Table Objects</title>

            <para>
                The following code demonstrates how to set a default metadata cache to be used for
                all table objects:
            </para>

            <programlisting role="php"><![CDATA[<
// First, set up the Cache
$frontendOptions = array(
    'automatic_serialization' => true
    );

$backendOptions  = array(
    'cache_dir'                => 'cacheDir'
    );

$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);


// Next, set the cache to be used with all table objects
Zend_Db_Table_Abstract::setDefaultMetadataCache($cache);


// A table class is also needed
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}


// Each instance of Bugs now uses the default metadata cache
$bugs = new Bugs();
]]></programlisting>

        </example>

        <example id="zend.db.table.metadata.caching-instance">

            <title>Using a Metadata Cache for a Specific Table Object</title>

            <para>
                The following code demonstrates how to set a metadata cache for a specific table
                object instance:
            </para>

            <programlisting role="php"><![CDATA[
// First, set up the Cache
$frontendOptions = array(
    'automatic_serialization' => true
    );

$backendOptions  = array(
    'cache_dir'                => 'cacheDir'
    );

$cache = Zend_Cache::factory('Core',
                             'File',
                             $frontendOptions,
                             $backendOptions);

// A table class is also needed
class Bugs extends Zend_Db_Table_Abstract
{
    // ...
}

// Configure an instance upon instantiation
$bugs = new Bugs(array('metadataCache' => $cache));
]]></programlisting>

        </example>

        <note>

            <title>Automatic Serialization with the Cache Frontend</title>

            <para>
                Since the information returned from the adapter's describeTable() method is an
                array, ensure that the <code>automatic_serialization</code> option is set to
                <code>true</code> for the <classname>Zend_Cache_Core</classname> frontend.
            </para>

        </note>

        <para>
            Though the above examples use <classname>Zend_Cache_Backend_File</classname>, developers may use
            whatever cache backend is appropriate for the situation. Please see
            <link linkend="zend.cache">Zend_Cache</link> for more information.
        </para>

        <sect3 id="zend.db.table.metadata.caching.hardcoding">
            <title>Hardcoding Table Metadata</title>

            <para>
                To take metadata caching a step further, you can also choose to
                hardcode metadata. In this particular case, however, any changes
                to the table schema will require a change in your code. As such,
                it is only recommended for those who are optimizing for
                production usage.
            </para>

            <para>
                The metadata structure is as follows:
            </para>

            <programlisting role="php"><![CDATA[
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>,
    ),
    // additional columns...
);
]]></programlisting>

            <para>
                An easy way to get the appropriate values is to use the metadata
                cache, and then to deserialize values stored in the cache.
            </para>

            <para>
                You can disable this optimization by turning of the
                <code>metadataCacheInClass</code> flag:
            </para>

            <programlisting role="php"><![CDATA[
// At instantiation:
$bugs = new Bugs(array('metadataCacheInClass' => false));

// Or later:
$bugs->setMetadataCacheInClass(false);
]]></programlisting>

            <para>
                The flag is enabled by default, which ensures that the
                <code>$_metadata</code> array is only populated once per
                instance.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.db.table.extending">

        <title>Customizing and Extending a Table Class</title>

        <sect3 id="zend.db.table.extending.row-rowset">

            <title>Using Custom Row or Rowset Classes</title>

            <para>
                By default, methods of the Table class return a Rowset in instances of the concrete
                class <classname>Zend_Db_Table_Rowset</classname>, and Rowsets contain a collection of instances of the
                concrete class <classname>Zend_Db_Table_Row</classname> You can specify an alternative class to use for
                either of these, but they must be classes that extend <classname>Zend_Db_Table_Rowset_Abstract</classname>
                and <classname>Zend_Db_Table_Row_Abstract</classname>, respectively.
            </para>

            <para>
                You can specify Row and Rowset classes using the Table constructor's options array,
                in keys <code>'rowClass'</code> and <code>'rowsetClass'</code> respectively.
                Specify the names of the classes using strings.
            </para>

            <example id="zend.db.table.extending.row-rowset.example">

                <title>Example of specifying the Row and Rowset classes</title>

                <programlisting role="php"><![CDATA[
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')

// Returns an object of type My_Rowset,
// containing an array of objects of type My_Row.
$rows = $table->fetchAll($where);
]]></programlisting>

            </example>

            <para>
                You can change the classes by specifying them with the <code>setRowClass()</code>
                and <code>setRowsetClass()</code> methods. This applies to rows and rowsets created
                subsequently; it does not change the class of any row or rowset objects you have
                created previously.
            </para>

            <example id="zend.db.table.extending.row-rowset.example2">

                <title>Example of changing the Row and Rowset classes</title>

                <programlisting role="php"><![CDATA[
$table = new Bugs();

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

// Returns an object of type Zend_Db_Table_Rowset
// containing an array of objects of type Zend_Db_Table_Row.
$rowsStandard = $table->fetchAll($where);

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

// Returns an object of type My_Rowset,
// containing an array of objects of type My_Row.
$rowsCustom = $table->fetchAll($where);

// The $rowsStandard object still exists, and it is unchanged.
]]></programlisting>

            </example>

            <para>
                For more information on the Row and Rowset classes, see
                <xref linkend="zend.db.table.row" /> and <xref linkend="zend.db.table.rowset" />.
            </para>

        </sect3>

        <sect3 id="zend.db.table.extending.insert-update">

            <title>Defining Custom Logic for Insert, Update, and Delete</title>

            <para>
                You can override the <code>insert()</code> and <code>update()</code> methods in
                your Table class. This gives you the opportunity to implement custom code that is
                executed before performing the database operation. Be sure to call the parent class
                method when you are done.
            </para>

            <example id="zend.db.table.extending.insert-update.example">

                <title>Custom logic to manage timestamps</title>

                <programlisting role="php"><![CDATA[
class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name = 'bugs';

    public function insert(array $data)
    {
        // add a timestamp
        if (empty($data['created_on'])) {
            $data['created_on'] = time();
        }
        return parent::insert($data);
    }

    public function update(array $data, $where)
    {
        // add a timestamp
        if (empty($data['updated_on'])) {
            $data['updated_on'] = time();
        }
        return parent::update($data, $where);
    }
}
]]></programlisting>

            </example>

            <para>
                You can also override the <code>delete()</code> method.
            </para>

        </sect3>

        <sect3 id="zend.db.table.extending.finders">

            <title>Define Custom Search Methods in Zend_Db_Table</title>

            <para>
                You can implement custom query methods in your Table class, if you have frequent
                need to do queries against this table with specific criteria. Most queries can be
                written using <code>fetchAll()</code>, but this requires that you duplicate code to
                form the query conditions if you need to run the query in several places in your
                application. Therefore it can be convenient to implement a method in the Table
                class to perform frequently-used queries against this table.
            </para>

            <example id="zend.db.table.extending.finders.example">

                <title>Custom method to find bugs by status</title>

                <programlisting role="php"><![CDATA[
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');
    }
}
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.table.extending.inflection">

            <title>Define Inflection in Zend_Db_Table</title>

            <para>
                Some people prefer that the table class name match a table name in the RDBMS by
                using a string transformation called <emphasis>inflection</emphasis>.
            </para>

            <para>
                For example, if your table class name is "<code>BugsProducts</code>", it would
                match the physical table in the database called "<code>bugs_products</code>," if
                you omit the explicit declaration of the <code>$_name</code> class property. In
                this inflection mapping, the class name spelled in "CamelCase" format would be
                transformed to lower case, and words are separated with an underscore.
            </para>

            <para>
                You can specify the database table name independently from the class name by
                declaring the table name with the <code>$_name</code> class property in each of
                your table classes.
            </para>

            <para>
                <classname>Zend_Db_Table_Abstract</classname> performs no inflection to map the class name to the table
                name. If you omit the declaration of <code>$_name</code> in your table class, the
                class maps to a database table that matches the spelling of the class name exactly.
            </para>

            <para>
                It is inappropriate to transform identifiers from the database, because this can
                lead to ambiguity or make some identifiers inaccessible. Using the SQL identifiers
                exactly as they appear in the database makes <classname>Zend_Db_Table_Abstract</classname> both simpler
                and more flexible.
            </para>

            <para>
                If you prefer to use inflection, then you must implement the transformation
                yourself, by overriding the <code>_setupTableName()</code> method in your Table
                classes. One way to do this is to define an abstract class that extends
                <classname>Zend_Db_Table_Abstract</classname>, and then the rest of your tables extend your new abstract
                class.
            </para>

            <example id="zend.db.table.extending.inflection.example">

                <title>Example of an abstract table class that implements inflection</title>

                <programlisting role="php"><![CDATA[
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
{
}
]]></programlisting>

            </example>

            <para>
                You are responsible for writing the functions to perform inflection transformation.
                Zend Framework does not provide such a function.
            </para>

        </sect3>

    </sect2>

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