Zend_Form - Mitchell Hashimoto

Zend_Form
{zone-data}

{zone-data:proposer-list}
[Mitchell Hashimoto|mailto:xmitchx@gmail.com]
{zone-data}

{zone-data:overview}
Zend_Form is a component to simplify the process of form validation, data filtering, and data storage. It will also allow forms to consist of multiple pages and maintain the data across those pages.
{zone-data}

{zone-data:references}
* [Zend_Form - Jurriën Stutterheim|http://framework.zend.com/wiki/pages/viewpage.action?pageId=36061]
* [Zend_Form - Simon Mundy|http://framework.zend.com/wiki/pages/viewpage.action?pageId=3596]
{zone-data}

* This component *will* allow instances of forms, fields, and pages to be reused within other forms.
* This component *will not* provide helpers for modifying the view.
{zone-data}

{zone-data:dependencies}
* Zend_Exception
* Zend_Session
* Zend_Validate_*
* Zend_Filter_*
{zone-data}

{zone-data:operation}
# The programmer creates an instance of Zend_Form.
# Pages are added to the instance of Zend_Form (optional). If no pages are added, a default page is used for a single-page form.
# Fields are added to the Zend_Form_Page instance returned from adding a new page, or directly to Zend_Form if it is a single-page form.
# Validators and Filters are added to the Zend_Form_Field instance returned from adding a field.
# The data source and other configuration data is set on the Zend_Form instance.
# Validation and data filtering occurs in the order they are added. Methods are available to modify the ordering of these actions. Data validation occurs only for the fields of the submitted page, if part of a multi-page form.
# If valid and is a single-page form, the programmer saves the filtered data. If it is a multi-page form, the form moves on to the next page, otherwise the programmer saves the data.
# If invalid, the user is directed back to the form page and is shown the errors he or she must correct to move on.

The added pages, fields, and validator/filters are added to their own contextual flows. A flow is just a chain of items which occur in a particular order. Pages are seen in order, fields are validating in a particular order, and the validators/filters are run in a particular order. The reason a flow needs to be identified is for branching and reusability. Flows can contain conditionals so that forms may branch to different pages under the circumstance a certain option is set, for example. Additionally, field validation can contain conditionals also, such as certain validations only being run if a condition is met, such as another field being valid. Visual examples of this are available in the use cases.
{zone-data}

{zone-data:milestones}
Describe some intermediate state of this component in terms of design notes, additional material added to this page, and / code. Note any significant dependencies here, such as, "Milestone #3 can not be completed until feature Foo has been added to ZF component XYZ." Milestones will be required for acceptance of future proposals. They are not hard, and many times you will only need to think of the first three below.
* Milestone 1: Proposal
* Milestone 2: Implementing single-page form with fields, validators, and filters.
* Milestone 3: Implementing conditionals to validators/filters.
* Milestone 4: Implementing multi-page form with Zend_Session temporary storage.
* Milestone 5: Implementing page conditionals
* Milestone 6: Unit Tests
* Milestone 7: Done
{zone-data}

{zone-data:class-list}
* Zend_Form
* Zend_Form_Element (abstract)
* Zend_Form_Element_Field
* Zend_Form_Element_Page
* Zend_Form_Element_Branch
* Zend_Form_Element_Exception
* Zend_Form_Flow
* Zend_Form_Flow_Conditional (abstract)
* Zend_Form_Flow_Conditional_Valid
* Zend_Form_Flow_Conditional_Value
* Zend_Form_Flow_Conditional_Exception
* Zend_Form_Storage (abstract)
* Zend_Form_Storage_Session
* Zend_Form_Storage_Exception
* Zend_Form_Exception
{zone-data}

{zone-data:use-cases}
{composition-setup}

$form->addField('username')
->addFilter('trim')
->addValidator('Alnum')

if ($form->isValid())
{
$this->_redirect('/success', array('exit' => true));
}

// Rerender form
{code}
{card}
{card:label=Conditional Flow}
Assuming we are continuing on to UC-01, this use case shows the addition of a new field password_confirmation. The change here is that I only want to validate that this field matches the password field if the password field itself is valid, so I use a conditional flow. Remember that validators/filters are run in the order they are added, so the flow we copy from password will run as normal, but the matches validator will not run unless password is valid.
{code}
// Assume UC-01 is being continued

->addValidator('matches', 'password');
{code}
{card}
{card:label=Dynamic Methods}
Assuming we are continuing on to UC-01, this use case adds a new field last_name and its various validators and filters using dynamic methods. Dynamic methods are an easy way to control the order of your pages, fields, validators, and filters.
{code}
// Assume UC-01 is being continued
$form->addFieldBeforePassword('last_name')
->addValidator('StringLength', array(5,12))
->addValidatorBeforeLength('Alnum')
->addFilterBeforeAlnum('trim');

// The above will make the order of filters/validators:
// trim() -> check alphanumeric (Alnum) -> check length
//
// and the field last_name will be processed before the password field
{code}

$page = $form->addPage('required_info');
$page->addField('username')

if ($form->isValid())
{
// Does it have another page?
if ($form->nextPage())

{
// Done! Save data!
}
}
{code}
{card}
{card:label=Page Branching}
This use case showcases the use of page branching with conditionals with a multi-page form. Some forms' pages only need to be shown under certain conditions, and using conditionals and branching, this is possible.
{code}
$form = new Zend_Form();
$form->addPage('login_or_signup')
->addField('choice');

$branch = $form->addBranch('signup', 'value', array('choice', 1));
$branch->addPage('signup')
->addField('password')
->addFilter('md5');
$branch->addPage('optional_info')
->addField('profile')
->addValidator('Alnum');

$form->addPage('global_page')
->addField('favorite_cookie');

/**
* The page structure looks like this:
* /-- signup -- optional_info --\
* login_or_signup -- | |-- global_page
* \-----------------------------/
*/
{code}
{card}
{card:label=Error Handling}
This use case shows how easy it is to assign error messages to your view, and also how easy it is to create custom error messages for your validations. This example is based on a multi-page form, but it would be the same for a single page. The '%s' when adding custom error messages is a placeholder for the field name.
{code}
$form = new Zend_Form();
$page = $form->addPage('required_info');

)))
->addFilter('md5');
$page_two = $form->addPage('optional_info');
$page_two->addField('first_name');

if ($form->isValid())
{
// Save data, redirect if on the last page
}
else
{
$this->view->errors = $form->getMessages();

{deck}
{zone-data}

{card:label=Zend_Form}
{code}
/**
* A component to simplify the process of form validation, data filtering, and
* data storage. It will also allow forms to consist of multiple pages and maintain
* the data across those pages.
*
* @category Zend
* @package Zend_Form
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form
{
/**
* The flow holding the root-level pages. Or if it is
* a single-page form, it will have a Zend_Form_Page
*

* Associative array containing the error messages.
*
* @var array
*/
protected $_messages = array();

/**
* Temporary persistent storage container for multi-page forms.
*
* @var Zend_Form_Storage
*/
protected $_storage = null;

/**
* Raw data, unfiltered and unvalidated.
*
* @var array
*/
protected $_rawData = null;

/**
* Validated data, filtered.
*
* @var array
*/
protected $_data = null;

/**
* Default page ID
*
* @var string
*/
const DEFAULT_PAGE = 'default';

* the default page is already being used (single-page form).
*
* @param string $id A unique identifier for the page.

*/
public function addPage($id, $parent = null, $relation = null)
{}

*

*/
public function addField($id, $parent = null, $relation = null)
{}

{}

{}

/**
* Set the temporary persistent storage container for multi-page
* forms. Throws an exception if invalid data type.
*

*/
public function setStorage($container, $options = null)
{}

* @throws Zend_Form_Exception
*/
public function &getStorage()
{}

{}

* parameter to rerun validations.
*
* @param boolean $rerun OPTIONAL If true, it will rerun validations if they
* have already been run.
* @return boolean
* @throws Zend_Form_Exception
*/
public function isValid($rerun = false)
{}

* @return Zend_Form
* @throws Zend_Form_Exception
*/
public function setDataSource($source)
{}

/**
* Retrieve validated and filtered data. If validations haven't been
* run yet, it will throw an exception.
*
* @return array
* @throws Zend_Form_Exception
*/
public function getData()
{}

{}

/**
* Magic method __call() used for dynamic methods.
*/

{card}
{card:label=Zend_Form_Element}
{code}
/**
* A piece of the Zend_Form.
*
* @category Zend
* @package Zend_Form
* @subpackage Element
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Element
{
/**
* The unique ID of the element.
*
* @var string
*/
protected $_id = null;

/**
* The array of items in the flow.
*
* @var Zend_Form_Flow
*/
protected $_items = null;

* @return Zend_Form_Element
*/
public function __construct($id)
{}

*/

{card}
{card:label=Zend_Form_Element_Field}
{code}
/**
* A field in a Zend_Form_Element_Page.
*
* @category Zend
* @package Zend_Form
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Element_Field extends Zend_Form_Element
{
/**
* Add a validator to the field.
*
* @param mixed $item The validator to add to the flow.
* @param mixed $options OPTIONAL Options for the validator.
* @param string|mixed $position OPTIONAL Where to put this new item, if not at

{}

/**
* Add a filter to the field.

{}

/**
* Add a conditional to the field.

{}

{}

{}

{}

{}

{}
}
{code}
{card}
{card:label=Zend_Form_Element_Page}
{code}
/**
* A page in a Zend_Form.
*
* @category Zend
* @package Zend_Form
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Element_Page extends Zend_Form_Element
{
/**
* Add a field to the page.
*
* @param mixed $item The field to add to the flow.
* @param string|mixed $position OPTIONAL Where to put this new item, if not at
* the end of the flow.
* @param int $relation Where to put this item in relation to $position.
* @return Zend_Form_Page
* @throws Zend_Form_Element_Exception
*/
public function addField($item, $position = null, $relation = Zend_Form_Flow::INSERT_AFTER)
{}

/**
* Gets a page's field.
*
* @return Zend_Form_Element_Field
* @throws Zend_Form_Element_Exception
*/
public function &getField($id)
{}

/**
* Gets the fields.
*
* @return Zend_Form_Flow
* @throws Zend_Form_Element_Exception
*/
public function getFields()
{}
}
{code}
{card}
{card:label=Zend_Form_Element_Branch}
{code}
/**
* A conditional branch in a Zend_Form.
*
* @category Zend
* @package Zend_Form
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Element_Branch extends Zend_Form_Element
{
/**
* Conditional
*
* @var Zend_Form_Flow_Conditional
*/
protected $_conditional = null;

/**
* Overloaded constructor to specify conditional for branch.
*/
public function __construct($id, $conditional, $options = null)
{}

/**
* Check if the conditional is true.
*
* @param Zend_Form &$form The Zend_Form object.
* @return Zend_Form_Element_Page
* @throws Zend_Form_Element_Exception
*/
public function is(&$form)
{}

/**
* Add a page to the page flow. Throws an exception if
* the ID is already taken, the parent does not exist, or
* the default page is already being used (single-page form).
*
* @param string $id A unique identifier for the page.
* @param string|Zend_Form_Page $parent OPTIONAL Parent page, the added page
* will go after this.
* @return Zend_Form_Element_Page
* @throws Zend_Form_Element_Exception
*/
public function addPage($id, $parent = null, $relation = null)
{}

/**
* Get a page from the branch by ID.
*
* @param string $id A unique identifier for the page.
* @return Zend_Form_Element_Page
* @throws Zend_Form_Element_Exception
*/
public function &getPage($id)
{}

/**
* Get the pages in the branch.
*
* @return Zend_Form_Flow
* @throws Zend_Form_Element_Exception
*/
public function getPages()
{}
}
{code}
{card}
{card:label=Zend_Form_Flow}
{code}
/**
* A basic flow, with no type checking.
*
* Flows are used to represent reusable ordered objects.
*
* @category Zend
* @package Zend_Form
* @subpackage Flow
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Flow implements Zend_Form_Flow_Interface
{
/**
* The array of items in the flow.
*
* @var array
*/
protected $_items = array();

/**
* Get the array of flow items.
*
* @return array
* @throws Zend_Form_Flow_Exception
*/
public function getItems()
{}

/**
* Check if an element in the flow has the ID specified.
*
* @param string $id The ID to check for.
* @return boolean
*/
public function itemExists($id)
{}

/**
* Add an item to the flow.
*
* @param mixed $item The field to add to the flow.
* @param string|mixed $position OPTIONAL Where to put this new item, if not at
* the end of the flow.
* @param int $relation Where to put this item in relation to $position.
* @return mixed
* @throws Zend_Form_Flow_Exception
*/
public function addItem($item, $position = null, $relation = self::INSERT_AFTER)
{}

/**
* Append another flow to this flow.
*
* @param Zend_Form_Flow $flow The flow to add.
* @return Zend_Form_Flow
* @throws Zend_Form_Flow_Exception
*/
public function addFlow($flow)
{}
}
{code}
{card}
{card:label=Zend_Form_Flow_Conditional}
{code}
/**
* Abstract class for creating flow conditionals.
*
* @category Zend
* @package Zend_Form
* @subpackage Flow_Conditional
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
abstract class Zend_Form_Flow_Conditional
{
/**
* A reference to the root form.
*
* @var Zend_Form
*/
protected $_form = null;

/**
* Sets the root form by reference.
*
* @param Zend_Form $form The root form.
* @return Zend_Form_Flow_Conditional
* @throws Zend_Form_Flow_Conditional_Exception
*/
public function setForm(&$form)
{}

/**
* Checks whether the conditional is true.
*
* @return boolean
*/
abstract public function is();
}
{code}
{card}
{deck}

{deck:id=SkeletonsMore}
{card:label=Zend_Form_Flow_Conditional_Valid}
{code}
/**
* A conditional which checks the value of another
* field.
*
* @category Zend
* @package Zend_Form
* @subpackage Flow
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Flow_Conditional_Valid extends Zend_Form_Flow_Conditional
{
/**
* The field to check.
*
* @var string
*/
var $_field = null;

/**
* Create a conditional which checks a field is valid.
*
* @param string $field The field ID on the form.
* @return Zend_Form_Flow_Conditional_Valid
* @throws Zend_Form_Flow_Exception
*/
public function __construct($field)
{
$this->_field = $field;
}

/**
* Returns true if the set field is equal to the desired value.
*
* @return boolean
*/
public function is()
{
return !$this->_form->hasErrors($this->_field);
}
}
{code}
{card}
{card:label=Zend_Form_Flow_Conditional_Value}
{code}
/**
* A conditional which checks the value of another
* field.
*
* @category Zend
* @package Zend_Form
* @subpackage Flow
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Flow_Conditional_Value extends Zend_Form_Flow_Conditional
{
/**
* The field to check.
*
* @var string
*/
var $_field = null;

/**
* The desired value
*
* @var mixed
*/
var $_desired = null;

/**
* Create a new conditional object which checks the value of a field.
*
* @param string $field The id of the field you wish to check.
* @param string $desired The desired value.
* @return Zend_Form_Flow_Interface
* @throws Zend_Form_Flow_Exception
*/
public function __construct($field, $desired)
{}

/**
* Returns true if the set field is equal to the desired value.
*
* @return boolean
*/
public function is()
{}
}
{code}
{card}
{card:label=Zend_Form_Storage}
{code}
/**
* Abstract class for temporary persistent storage mechanisms.
*
* @category Zend
* @package Zend_Form
* @subpackage Storage
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
abstract class Zend_Form_Storage
{
/**
* Sets a key-value pair, or array of key values.
*
* @param array|string $key Either an array of pairs or just a key.
* @param string $value OPTIONAL An optional value.
* @return Zend_Form_Storage
* @throws Zend_Form_Storage_Exception
*/
abstract public function set($key, $value = null);

/**
* Gets a value for a given key, or gets all values.
*
* @param string $key OPTIONAL The specific key to receive.
* @return string|array
* @throws Zend_Form_Storage_Exception
*/
abstract public function get($key = null);
}
{code}
{card}
{card:label=Zend_Form_Storage_Session}
{code}
/**
* Temporary storage by use of sessions.
*
* @category Zend
* @package Zend_Form
* @subpackage Storage
* @copyright Copyright (c) 2005-2007 Zend Technologies USA Inc. (http://www.zend.com)
* @license http://www.zend.com/license/3_0.txt PHP License 3.0
*/
class Zend_Form_Storage_Session extends Zend_Form_Storage
{
/**
* The namespace name of the session.
*
* @var string
*/
protected $_namespace = '';

/**
* The session.
*
* @var Zend_Session_Namespace
*/
protected $_session = null;

/**
* Creates a storage session object. Set the namespace key using
* the parameter.
*
* @param string $namespace The session namespace to use.
* @return Zend_Form_Storage_Session
*/
public function __construct($namespace)
{}

/**
* Set data within the namespace.
*
* @param array|string $key Either an array of pairs or just a key.
* @param string $value OPTIONAL An optional value.
* @return Zend_Form_Storage
* @throws Zend_Form_Storage_Exception
*/
public function set($key, $value = null)
{}

/**
* Gets a value for a given key, or gets all values.
*
* @param string $key OPTIONAL The specific key to receive.
* @return string|array
* @throws Zend_Form_Storage_Exception
*/
public function get($key = null)
{}
}
{code}
{card}
{deck}