# Zend_Db_Table_Definition

## Introduction

Zend_Db_Table_Definition is a class that can be used to describe the relationships and configuration options that should be used when Zend_Db_Table is used via concrete instantiation.

## Basic Usage

For all of the same options that are available when configuring an extended Zend_Db_Table_Abstract class, those options are also available when describing a definition file. This definition file should be passed to the class at instantiation time so that it can know the full definition of all tables in said definition.

Below is a definition that will describe the table names and relationships between table objects. Note: if 'name' is left out of the definition, it will be taken as the key of the defined table (an example of this is in the 'genre' section in the example below.)

Describing the Definition of a Database Data Model

    $definition = new Zend_Db_Table_Definition(array(
        'author' => array(
            'name' => 'author',
            'dependentTables' => array('book')
            ),
        'book' => array(
            'name' => 'book',
            'referenceMap' => array(
                'author' => array(
                    'columns' => 'author_id',
                    'refTableClass' => 'author',
                    'refColumns' => 'id'
                    )
                )
            ),
        'genre' => null,
        'book_to_genre' => array(
            'referenceMap' => array(
                'book' => array(
                    'columns' => 'book_id',
                    'refTableClass' => 'book',
                    'refColumns' => 'id'
                    ),
                'genre' => array(
                    'columns' => 'genre_id',
                    'refTableClass' => 'genre',
                    'refColumns' => 'id'
                    )
                )
            )
        ));

As you can see, the same options you'd generally see inside of an extended Zend_Db_Table_Abstract class are documented in this array as well. When passed into Zend_Db_Table constructor, this definition is persisted to any tables it will need to create in order to return the proper rows.

Below is an example of the primary table instantiation as well as the findDependentRowset() and findManyToManyRowset() calls that will correspond to the data model described above:

Interacting with the described definition

    $authorTable = new Zend_Db_Table('author', $definition);
    $authors = $authorTable->fetchAll();

    foreach ($authors as $author) {
        echo $author->id
           . ': '
           . $author->first_name
           . ' '
           . $author->last_name
           . PHP_EOL;
        $books = $author->findDependentRowset('book');
        foreach ($books as $book) {
            echo '    Book: ' . $book->title . PHP_EOL;
            $genreOutputArray = array();
            $genres = $book->findManyToManyRowset('genre', 'book_to_genre');
            foreach ($genres as $genreRow) {
                $genreOutputArray[] = $genreRow->name;
            }
            echo '        Genre: ' . implode(', ', $genreOutputArray) . PHP_EOL;
        }
    }

## Advanced Usage

Sometimes you want to use both paradigms for defining and using the table gateway: both by extension and concrete instantiation. To do this simply leave out any table configurations out of the definition. This will allow Zend_Db_Table to look for the actual refered class instead of the definition key.

Building on the example above, we will allow for one of the table configurations to be a Zend_Db_Table_Abstract extended class, while keeping the rest of the tables as part of the definition. We will also show how one would interact with this new definition.

Interacting A Mixed Use Zend_Db_Table Definition

    class MyBook extends Zend_Db_Table_Abstract
    {
        protected $_name = 'book';
        protected $_referenceMap = array(
            'author' => array(
                'columns' => 'author_id',
                'refTableClass' => 'author',
                'refColumns' => 'id'
                )
            );
    }

    $definition = new Zend_Db_Table_Definition(array(
        'author' => array(
            'name' => 'author',
            'dependentTables' => array('MyBook')
            ),
        'genre' => null,
        'book_to_genre' => array(
            'referenceMap' => array(
                'book' => array(
                    'columns' => 'book_id',
                    'refTableClass' => 'MyBook',
                    'refColumns' => 'id'
                    ),
                'genre' => array(
                    'columns' => 'genre_id',
                    'refTableClass' => 'genre',
                    'refColumns' => 'id'
                    )
                )
            )
        ));

    $authorTable = new Zend_Db_Table('author', $definition);
    $authors = $authorTable->fetchAll();

    foreach ($authors as $author) {
        echo $author->id
           . ': '
           . $author->first_name
           . ' '
           . $author->last_name
           . PHP_EOL;
        $books = $author->findDependentRowset(new MyBook());
        foreach ($books as $book) {
            echo '    Book: ' . $book->title . PHP_EOL;
            $genreOutputArray = array();
            $genres = $book->findManyToManyRowset('genre', 'book_to_genre');
            foreach ($genres as $genreRow) {
                $genreOutputArray[] = $genreRow->name;
            }
            echo '        Genre: ' . implode(', ', $genreOutputArray) . PHP_EOL;
        }
    }