Tables have relationships to each other in a relational database. An entity in one table can be linked to one or more entities in another table by using referential integrity constraints defined in the database schema.

The Zend_Db_Table_Row class has methods for querying related rows in other tables.

In this section, we use an example database that shows several types of relationships between tables. This database tracks bugs in a software development project. The database contains three tables:

The following SQL data definition language pseudocode describes the tables in this example database.

CREATE TABLE accounts (
  account_id        PRIMARY KEY,
  name              VARCHAR
);

CREATE TABLE products (
  product_id        PRIMARY KEY,
  product_name      VARCHAR
);

CREATE TABLE bugs (
  bug_id            PRIMARY KEY,
  product_id        FOREIGN KEY REFERENCES products(product_id),
  reported_by       FOREIGN KEY REFERENCES accounts(account_id),
  assigned_to       FOREIGN KEY REFERENCES accounts(account_id),
  verified_by       FOREIGN KEY REFERENCES accounts(account_id),
  bug_description   VARCHAR,
  bug_status        VARCHAR
);
        

The products table has a one-to-many relationship to the bugs table. The accounts table also has a one-to-many relationship to the bugs table. Thus the products table has a many-to-many relationship to the accounts table.

Also notice that the bugs table contains multiple foreign key references to the accounts table. Each of these foreign keys may reference a different row in the accounts table for a given bug.

Define classes for each of these tables, extending the abstract class Zend_Db_Table_Abstract, as described in ???. In the class file for each child table, declare the reference relationships in the protected $_referenceMap and protected $_dependentTables array variables.

Below are the PHP class definitions for these tables:

<?php

class Accounts extends Zend_Db_Table_Abstract
{
    protected $_name            = 'accounts';
    protected $_primary         = array('account_id');
    protected $_dependentTables = array('Bugs');
}

class Products extends Zend_Db_Table_Abstract
{
    protected $_name            = 'products';
    protected $_primary         = array('product_id');
    protected $_dependentTables = array('Bugs');
}

class Bugs extends Zend_Db_Table_Abstract
{
    protected $_name            = 'bugs';
    protected $_referenceMap    = array(
        'Reporter' => array(
            'columns'           => 'reported_by',
            'refTableClass'     => 'Accounts',
            'refColumns'        => 'account_id'
        ),
        'Engineer' => array(
            'columns'           => 'assigned_to',
            'refTableClass'     => 'Accounts',
            'refColumns'        => 'account_id'
        ),
        'Verifier' => array(
            'columns'           => array('verified_by'),
            'refTableClass'     => 'Accounts',
            'refColumns'        => array('account_id')
        ),
        'Product' => array(
            'columns'           => array('product_id'),
            'refTableClass'     => 'Products',
            'refColumns'        => array('product_id')
        )
    );
}

?>
        

Declare the $_dependentTables array in the class for the parent table. List the class name for each dependent table. Use the class name, not the physical name of the SQL table.

Declare the $_referenceMap array in the class for each dependent table. This is an associative array of reference "rules". A reference rule identifies which table is the parent table in the relationship, and also lists which columns in the dependent table reference which columns in the parent table.

The rule key is a string used as an index to the $_referenceMap array. This rule key is used to identify each reference relationship. Choose a descriptive name for this rule key. It's best to use a string that can be part of a PHP method name, as you will see later.

In the example PHP code above, the rule keys are: 'Reporter', 'Engineer', 'Verifier', and 'Product'.

The value of each rule entry in the $_referenceMap array is also an associative array. The elements of this rule entry are described below:

If you have a Row object as the result of a query on a parent table, you can fetch rows from dependent tables that reference the current row. Use the method:

$row->findDependentRowset($table, [$rule])

        

This method returns a Zend_Db_Table_Rowset_Abstract object, containing a set of rows from the dependent table $table that refer to the row identified by the $row object.

The first argument $table can be a string that specifies the dependent table by its class name. You can also specify the dependent table by using an object of that table class.

<?php

$accountsTable      = new Accounts();
$accountsRowset     = $accountsTable->find(1234);
$user1234           = $accountsRowset->current();

$bugsReportedByUser = $user1234->findDependentRowset('Bugs');

?>
            

The second argument $rule is optional. It is a string that names the rule key in the $_referenceMap array of the dependent table class. If you don't specify a rule, the first rule in the array that references the parent table is used. If you need to use a rule other than the first, you need to specify the key.

In the example code above, the rule key is not specified, so the rule used by default is the first one that matches the parent table. This is the rule 'Reporter'.

<?php

$accountsTable      = new Accounts();
$accountsRowset     = $accountsTable->find(1234);
$user1234           = $accountsRowset->current();

$bugsAssignedToUser = $user1234->findDependentRowset('Bugs', 'Engineer');

?>
            

Alternatively, you can query rows from a dependent table using a special mechanism called a "magic method". Zend_Db_Table_Row_Abstract invokes the method: findDependentRowset('<TableClass>', '<Rule>') if you invoke a method on the Row object matching either of the following patterns:

In the patterns above, <TableClass> and <Rule> are strings that correspond to the class name of the dependent table, and the dependent table's rule key that references the parent table.

	Nota
	Some application frameworks, such as Ruby on Rails, use a mechanism called "inflection" to allow the spelling of identifiers to change depending on usage. For simplicity, Zend_Db_Table_Row does not provide any inflection mechanism. The table identity and the rule key named in the method call must match the spelling of the class and rule key exactly.

<?php

$accountsTable    = new Accounts();
$accountsRowset   = $accountsTable->find(1234);
$user1234         = $accountsRowset->current();

// Use the default reference rule
$bugsReportedBy   = $user1234->findBugs();

// Specify the reference rule
$bugsAssignedTo   = $user1234->findBugsByEngineer();

?>
            

If you have a Row object as the result of a query on a dependent table, you can fetch the row in the parent to which the dependent row refers. Use the method:

$row->findParentRow($table, [$rule])

        

There always should be exactly one row in the parent table referenced by a dependent row, therefore this method returns a Row object, not a Rowset object.

The first argument $table can be a string that specifies the parent table by its class name. You can also specify the parent table by using an object of that table class.

<?php

$bugsTable         = new Bugs();
$bugsRowset        = $bugsTable->fetchAll('bug_status = ?', 'NEW');
$bug1              = $bugsRowset->current();

$reporter          = $bug1->findParentRow('Accounts');

?>
            

The second argument $rule is optional. It is a string that names the rule key in the $_referenceMap array of the dependent table class. If you don't specify a rule, the first rule in the array that references the parent table is used. If you need to use a rule other than the first, you need to specify the key.

In the example above, the rule key is not specified, so the rule used by default is the first one that matches the parent table. This is the rule 'Reporter'.

<?php

$bugsTable         = new Bugs();
$bugsRowset        = $bugsTable->fetchAll('bug_status = ?', 'NEW');
$bug1              = $bugsRowset->current();

$engineer          = $bug1->findParentRow('Accounts', 'Engineer');

?>
            

Alternatively, you can query rows from a parent table using a "magic method". Zend_Db_Table_Row_Abstract invokes the method: findParentRow('<TableClass>', '<Rule>') if you invoke a method on the Row object matching either of the following patterns:

In the patterns above, <TableClass> and <Rule> are strings that correspond to the class name of the parent table, and the dependent table's rule key that references the parent table.

	Nota
	The table identity and the rule key named in the method call must match the spelling of the class and rule key exactly.

<?php

$bugsTable         = new Bugs();
$bugsRowset        = $bugsTable->fetchAll('bug_status = ?', 'NEW');
$bug1              = $bugsRowset->current();

// Use the default reference rule
$reporter          = $bug1->findParentAccounts();

// Specify the reference rule
$engineer          = $bug1->findParentAccountsByEngineer();

?>
            

If you have a Row object as the result of a query on one table in a many-to-many relationship (for purposes of the example, call this the "origin" table), you can fetch corresponding rows in the other table (call this the "destination" table) via an intersection table. Use the method:

$row->findManyToManyRowset($table, $intersectionTable, [$rule1, [$rule2]])

        

This method returns a Zend_Db_Table_Rowset_Abstract containing rows from the table $table, satisfying the many-to-many relationship. The current Row object $row from the origin table is used to find rows in the intersection table, and that is joined to the destination table.

The first argument $table can be a string that specifies the destination table in the many-to-many relationship by its class name. You can also specify the destination table by using an object of that table class.

The second argument $intersectionTable can be a string that specifies the intersection table between the two tables in the the many-to-many relationship by its class name. You can also specify the intersection table by using an object of that table class.

<?php

$accountsTable    = new Accounts();
$accountsRowset   = $accountsTable->find(1234);
$user1234         = $accountsRowset->current();

$productsRowset   = $user1234->findManyToManyRowset('Products', 'Bugs');

?>
            

The third and fourth arguments $rule1 and $rule2 are optional. These are strings that name the rule keys in the $_referenceMap array of the intersection table.

The $rule1 key names the rule for the relationship from the intersection table to the origin table. In this example, this is the relationship from Bugs to Accounts.

The $rule2 key names the rule for the relationship from the intersection table to the destination table. In this example, this is the relationship from Bugs to Products.

Similarly to the methods for finding parent and dependent rows, if you don't specify a rule, the method uses the first rule in the $_referenceMap array that matches the tables in the relationship. If you need to use a rule other than the first, you need to specify the key.

In the example code above, the rule key is not specified, so the rules used by default are the first ones that match. In this case, $rule1 is 'Reporter' and $rule2 is 'Product'.

<?php

$accountsTable    = new Accounts();
$accountsRowset   = $accountsTable->find(1234);
$user1234         = $accountsRowset->current();

$productsRowset   = $user1234->findManyToManyRowset('Products', 'Bugs', 'Engineer');

?>
            

Alternatively, you can query rows from the destination table in a many-to-many relationship using a "magic method." Zend_Db_Table_Row_Abstract invokes the method: findManyToManyRowset('<TableClass>', '<IntersectionTableClass>', '<Rule1>', '<Rule2>') if you invoke a method matching any of the following patterns:

In the patterns above, <TableClass> and <IntersectionTableClass> are strings that correspond to the class names of the destination table and the intersection table, respectively. <Rule1> and <Rule2> are strings that correspond to the rule keys in the intersection table that reference the origin table and the destination table, respectively.

	Nota
	The table identities and the rule keys named in the method call must match the spelling of the class and rule key exactly.

<?php

$accountsTable     = new Accounts();
$accountsRowset    = $accountsTable->find(1234);
$user1234          = $accountsRowset->current();

// Use the default reference rule
$productsReporting = $user1234->findProductsViaBugs();

// Specify the reference rule
$productsFixing    = $user1234->findProductsViaBugsByEngineer();

?>
            

Declare DRI in the database:

Declaring cascading operations in Zend_Db_Table is intended only for RDBMS brands that do not support declarative referential integrity (DRI). For example, if you use MySQL's MyISAM storage engine, or SQLite, these solutions do not support DRI. You may find it helpful to declare the cascading operations with Zend_Db_Table. If your RDBMS implements DRI and the ON DELETE and ON UPDATE clauses, you should declare these clauses in your database schema, instead of using the cascading feature in Zend_Db_Table. Declaring cascading DRI rules in the RDBMS is better for database performance, consistency, and integrity. Most importantly, do not declare cascading operations both in the RDBMS and in your Zend_Db_Table class.

You can declare cascading operations to execute against a dependent table when you apply an UPDATE or a DELETE to a row in a parent table.

<?php

$productsTable  = new Products();
$productsRowset = $productsTable->find(1234);
$product1234    = $productsRowset->current();

$product1234->delete();
// Automatically cascades to Bugs table
// and deletes dependent rows.

?>
            

Similarly, if you use UPDATE to change the value of a primary key in a parent table, you may want the value in foreign keys of dependent tables to be updated automatically to match the new value, so that such references are kept up to date.

It's usually not necessary to update the value of a primary key that was generated by a sequence or other mechanism. But if you use a natural key that may change value occasionally, it is more likely that you need to apply cascading updates to dependent tables.

To declare a cascading relationship in the Zend_Db_Table, edit the rules in the $_referenceMap. Set the associative array keys 'onDelete' and 'onUpdate' to the string 'cascade' (or the constant self::CASCADE). Before a row is deleted from the parent table, or its primary key values updated, any rows in the dependent table that refer to the parent's row are deleted or updated first.

<?php

class Bugs extends Zend_Db_Table_Abstract
{
    ...
    protected $_referenceMap    = array(
        'Product' => array(
            'columns'           => array('product_id'),
            'refTableClass'     => 'Products',
            'refColumns'        => array('product_id'),
            'onDelete'          => self::CASCADE,
            'onUpdate'          => self::RESTRICT
        ),
        ...
    );
}

?>