Using the Domain Model

Zupal's domain objects are a framework for data interchange. They are not required to be used, but they do encapsulate a lot of handy functionality.

Using domain objects begins with creating a pair of name-related objects, one for the table class and one for the domain class itself:

<?php

class Zupal_Users 
extends Zupal_Domain
{

	/* @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ __construct @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ */
	
	public function __construct ($pID = NULL)
	{
		parent::__construct($pID);
	}

/* @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ table_class @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ */
		
	/**
	 * @see Zupal_Domain::get_table_class()
	 * note -- this bolerplate can be used as is to find the matching table class.
	 * It also can be overridden to fetch your table class from a pre-existing codebase
	 * no matter what its name. 
	 */
	protected function get_table_class ()
	{
		return preg_replace('~^Zupal_~', 'Zupal_Table_', __CLASS__);
	}
	
/* @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ get @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ */
	/**
	 * @see Zupal_Domain::get()
	 *
	 * @param unknown_type $pID
	 * @return Zupal_Domain
	 * this method is a factory for its own objects; it is a component of the find methods. 
       */
	public function get ($pID)
	{
	     return new Zupal_Users($pID);
	}

/* @@@@@@@@@@@@@@@@@@@@@@@@@@@@@ identity @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ */
	/**
	 * This is not a required method but it is a handy one to render out a domain object
	 * for test purposes during scaffolding. 
	 */
	public function __toString()
	{
		try {
		if (!$this->loaded()) return '(unloaded)';
		return $this->identity() . ': ' . $this->username;
		} catch (Exception $e)
		{
			return $e->__toString();
		}
	}

}

The bound table class,

<?php

/**
 * Zupal_Table_Formset
 *  
 * @author daveedelhart
 * @version 
 */

class Zupal_Table_Users extends Zupal_Table_Abstract
{
	/**
	 * The default table name 
	 */
	protected $_name = 'users';
	protected $_id_field = 'userid';
	
}

It is not much more than a decorator that exposes the name and id field properties to the methods of Zupal_Table_Abstract that return them.

Using Domain Objects

Domain objects can be used much as Zend_DB_Table_Records, that have the ability to save themselves. Setting their fields passes through magically to a bound and cloaked data repository (a Zend_Db_Table_Record) , as does save commands.

$u = new Zupal_Users();

$u->username = "fred";
$u->password = "fl1intstone";

$u->save();
 

However they also have factory and query functionality:

$stub = new Zupal_Users(Zupal_Domain::STUB); // makes the stub "sterile" and impossible to save

$freds = $stub->find(array('username' => 'fred')); // returns an array of Zupal_Users -- actually an array of a single user.

$fred = $stub->find_one(array('username' => 'fred')); // note returns a single domain object, not an array

Also, there are built in test methods that determine if a given record exists:

$might_be_fred = new Zupal_Users(100);

if ($might_be_fred->is_saved()):

...

endif;

One of the great uses of Domain objects is to enable unit tests. Domain objects accept stdClass (generic) objects as data sources, and the table class is designed to import test data in INI format to create a "faux database" of information.

Note that there are a few foreign hooks left in the codebase of the domains; as Zupal becomes more fleshed out these will present in a much more uniform fashion.