Crear un objeto de formulario es muy simple: solo instancíe Zend_Form

$form = new Zend_Form;

Para casos de uso avanzados, es posible desee crear una subclase de Zend_Form , pero para formularios simples, puede programar la creación de un formulario usando un objeto Zend_Form

Si desea especificar el action y method del formulario (siempre buenas ideas), puede hacer uso de los accesos setAction() y setMethod() :

$form->setAction('/resource/process')
     ->setMethod('post');

El código de arriba establece el action del formulario a la URL parcial "/resource/process" y como method HTTP POST. Esto se mostrará en la presentación final.

Usted puede establecer atributos HTML adicionales para la etiqueta <form> mediante el uso de los métodos setAttrib() o setAttribs(). Por ejemplo, si desea especificar el id establezca el atributo "id":

$form->setAttrib('id', 'login');

Un formulario no es nada sin sus elementos. Zend_Form contiene de manera predeterminada algunos elementos que generan XHTML vía auxiliares Zend_View . Son los siguientes:

Tiene dos opciones para añadir elementos a un formulario; puede instanciar elementos concretos y pasarlos como objetos, o simplemente puede pasar el tipo de elemento y Zend_Form instaciará por usted un objeto del tipo correspondiente.

Algunos ejemplos:

// Instanciando un elemento y pasandolo al objeto form:
$form->addElement(new Zend_Form_Element_Text('username'));

// Pasando el tipo de elemento del formulario al objeto form:
$form->addElement('text', 'username');

De manera predeterminada, éstos no tienen validadores o filtros. Esto significa que tendrá que configurar sus elementos con un mínimo de validadores, y potencialmente filtros. Puede hacer esto (a) antes de pasar el elemento al formulario, (b) vía opciones de configuración pasadas cuando crea un elemento a través de Zend_Form , o (c) recuperar el elemento del objeto form y configurándolo posteriormente.

Veamos primero la creación de validadores para la instancia de un elemento concreto. Puede pasar objetos Zend_Validate_* o el nombre de un validador para utilizar:

$username = new Zend_Form_Element_Text('username');

// Pasando un objeto Zend_Validate_*:
$username->addValidator(new Zend_Validate_Alnum());

// Pasando el nombre de un validador:
$username->addValidator('alnum');

Cuando se utiliza esta segunda opción, si el constructor del validador acepta argumentos, se pueden pasar en un array como tercer parámetro:

// Pasando un patrón
$username->addValidator('regex', false, array('/^[a-z]/i'));

(El segundo parámetro se utiliza para indicar si el fallo debería prevenir la ejecución de validadores posteriores o no; por defecto, el valor es FALSE.)

Puede también desear especificar un elemento como requerido. Esto puede hacerse utilizando un método de acceso o pasando una opción al crear el elemento. En el primer caso:

// Hace este elemento requerido:
$username->setRequired(true);

Cuando un elemento es requerido, un validador 'NotEmpty' (NoVacio) es añadido a la parte superior de la cadena de validaciones, asegurando que el elemento tenga algún valor cuando sea requerido.

Los filtros son registrados básicamente de la misma manera que los validadores. Para efectos ilustrativos, vamos a agregar un filtro para poner en minúsculas el valor final:

$username->addFilter('StringtoLower');

Entonces, la configuración final de nuestro elemento queda así:

$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]/'))
         ->setRequired(true)
         ->addFilter('StringToLower');

// o, de manera más compacta:
$username->addValidators(array('alnum',
        array('regex', false, '/^[a-z]/i')
    ))
    ->setRequired(true)
    ->addFilters(array('StringToLower'));

Tan simple como esto, realizarlo para cada uno de los elementos del formulario puede resultar un poco tedioso. Intentemos la opción (b) arriba mencionada. Cuando creamos un nuevo elemento utilizando Zend_Form::addElement() como fábrica, opcionalmente podemos pasar las opciones de configuración. Éstas pueden incluir validadores y los filtros que se van a utilizar. Por lo tanto, para hacer todo lo anterior implícitamente, intente lo siguiente:

$form->addElement('text', 'username', array(
    'validators' => array(
        'alnum',
        array('regex', false, '/^[a-z]/i')
    ),
    'required' => true,
    'filters'  => array('StringToLower'),
));

Generar un formulario es simple. La mayoría de los elementos utilizan un auxiliar de Zend_View para generarse a sí mismos, por lo tanto necesitan un objeto vista con el fin de generarse. Además, tiene dos opciones: usar el método render() del formulario, o simplemente mostrarlo con echo.

// Llamando a render()  explicitamente, y pasando un objeto vista opcional:
echo $form->render($view);

// Suponiendo un objeto vista ha sido previamente establecido vía setView():
echo $form;

De manera predeterminada, Zend_Form y Zend_Form_Element intentarán utilizar el objeto vista inicializado en el ViewRenderer , lo que significa que no tendrá que establecer la vista manualmente cuando use el MVC de Zend Framework. Generar un formulario en un script vista es tan simple como:

<?php echo $this->form

Detrás del telón, Zend_Form utiliza "decoradores" (decorators) para generar la salida. Estos decoradores pueden reemplazar, añadir o anteponer contenido, y tienen plena introspección al elemento que les es pasado. Como resultado, puede combinar múltiples decoradores para lograr efectos personalizados. Predeterminadamente, Zend_Form_Element actualmente combina cuatro decoradores para obtener su salida; la configuración sería como sigue:

$element->addDecorators(array(
    'ViewHelper',
    'Errors',
    array('HtmlTag', array('tag' => 'dd')),
    array('Label', array('tag' => 'dt')),
));

(Donde <HELPERNAME> es el nombre de un view helper que utilizar, y varía según el elemento)

Lo anterior crea una salida como la siguiente:

<dt><label for="username" class="required">Username</dt>
<dd>
    <input type="text" name="username" value="123-abc" />
    <ul class="errors">
        <li>'123-abc' has not only alphabetic and digit characters</li>
        <li>'123-abc' does not match against pattern '/^[a-z]/i'</li>
    </ul>
</dd>

(Aunque no con el mismo formato.)

Puede cambiar los decoradores usados para un elemento si desea tener diferente salida; véase la sección sobre decoradores para mayor información.

El propio formulario simplemente itera sobre los elementos y los cubre en un <form> HTML. El action y method que proporcionó cuando definió el formulario se pasan a la etiqueta <form> , como cualquier atributo que establezca vía setAttribs() y familia.

Elementos son desplegados en el orden en el que fueron registrados, o, si el elemento contienen un atributo de orden, ese orden será utilizado. Usted puede fijar el orden de un elemento usando:

$element->setOrder(10);

O, cuando crea un elemento, pasándolo como una opción:

$form->addElement('text', 'username', array('order' => 10));

Después que un formulario es enviado, necesitará comprobar y ver si pasa las validaciones. Cada elemento es valuado contra los datos provistos; si una clave no está presente y el campo fue marcado como requerido, la validación se ejecuta contra un valor NULL.

¿De dónde provienen los datos?. Puede usar $_POST o $_GET , o cualquier otra fuente de datos que tenga a mano (solicitud de un servicio web, por ejemplo):

if ($form->isValid($_POST)) {
    // ¡Correcto!
} else {
    // ¡Fallo!
}

Con solicitudes AJAX , a veces puede ignorar la validación de un solo elemento, o grupo de elementos. isValidPartial() validará parcialmente el formulario. A diferencia de isValid() , que como sea, si alguna clave no esta presente, no ejecutará las validaciones para ese elemento en particular.

if ($form->isValidPartial($_POST)) {
    // de los elementos presentes, todos pasaron las validaciones
} else {
    // uno u más elementos probados no pasaron las validaciones
}

Un método adicional, processAjax() , puede también ser usado para validar formularios parciales. A diferencia de isValidPartial() , regresa una cadena en formato JSON -formatted conteniendo mensajes de error en caso de fallo.

Asumiendo que sus validaciones han pasado, ahora puede obtener los valores filtrados:

$values = $form->getValues();

Si necesita los valores sin filtrar en algún punto, utilice:

$unfiltered = $form->getUnfilteredValues();

If you on the other hand need all the valid and filtered values of a partially valid form, you can call:

$values = $form->getValidValues($_POST);

Entonces, ¿su formulario no es válido? En la mayoría de los casos, simplemente puede generar el formulario nuevamente y los errores se mostrarán cuando se usen los decoradores predeterminados:

if (!$form->isValid($_POST)) {
    echo $form;

    // o asigne al objeto vista y genere una vista...
    $this->view->form = $form;
    return $this->render('form');
}

Si quiere inspeccionar los errores, tiene dos métodos. getErrors() regresa una matriz asociativa de nombres / códigos de elementos (donde códigos es una matriz de códigos de error). getMessages() regresa una matriz asociativa de nombres / mensajes de elementos (donde mensajes es una matriz asociativa de pares código de error / mensaje de error). Si un elemento no tiene ningún error, no será incluido en la matriz.

Construyamos un simple formulario de login. Necesitaremos elementos que representen:

Para nuestros propósitos, vamos a suponer que un usuario válido cumplirá con tener solo caracteres alfanuméricos, comenzar con una letra, tener una longitud mínima de 6 caracteres y una longitud máxima de 20 caracteres; se normalizarán en minúsculas. Las contraseñas deben tener un mínimo de 6 caracteres. Cuando se procese vamos simplemente a mostrar el valor, por lo que puede permanecer inválido.

Usaremos el poder de la opciones de configuración de Zend_Form para crear el formulario:

$form = new Zend_Form();
$form->setAction('/user/login')
     ->setMethod('post');

// Crea un y configura el elemento username
$username = $form->createElement('text', 'username');
$username->addValidator('alnum')
         ->addValidator('regex', false, array('/^[a-z]+/'))
         ->addValidator('stringLength', false, array(6, 20))
         ->setRequired(true)
         ->addFilter('StringToLower');

// Crea y configura el elemento password:
$password = $form->createElement('password', 'password');
$password->addValidator('StringLength', false, array(6))
         ->setRequired(true);

// Añade los elementos al formulario:
$form->addElement($username)
     ->addElement($password)
     // uso de addElement() como fábrica para crear el botón 'Login':
     ->addElement('submit', 'login', array('label' => 'Login'));

A continuación, vamos a crear un controlador para manejar esto:

class UserController extends Zend_Controller_Action
{
    public function getForm()
    {
        // crea el formulario como se indicó arriba
        return $form;
    }

    public function indexAction()
    {
        // genera user/form.phtml
        $this->view->form = $this->getForm();
        $this->render('form');
    }

    public function loginAction()
    {
        if (!$this->getRequest()->isPost()) {
            return $this->_forward('index');
        }
        $form = $this->getForm();
        if (!$form->isValid($_POST)) {
            // Falla la validación; Se vuelve a mostrar el formulario
            $this->view->form = $form;
            return $this->render('form');
        }

        $values = $form->getValues();
        // ahora intenta y autentica...
    }
}

Y un script para la vista que muestra el formulario:

<h2>Please login:</h2>
<?php echo $this->form

Como notará en el código del controlador, hay más trabajo por hacer: mientras la información enviada sea válida, necesitará todavía realizar la autenticación usando Zend_Auth , por ejemplo.

Todas las clases Zend_Form son configurables mediante Zend_Config ; puede incluso pasar un objeto al constructor o pasarlo a través de setConfig() . Veamos cómo podemos crear el formulario anterior usando un archivo INI . Primero, vamos a seguir las recomendaciones, y colocaremos nuestras configuraciones dentro de secciones reflejando su objetivo y y enfocándonos en la sección 'development'. A continuación, pondremos en una sección de configuración para el controlador dado ('user'), y una clave para el formulario ('login'):

[development]
; metainformación general del formulario
user.login.action = "/user/login"
user.login.method = "post"

; elemento username
user.login.elements.username.type = "text"
user.login.elements.username.options.validators.alnum.validator = "alnum"
user.login.elements.username.options.validators.regex.validator = "regex"
user.login.elements.username.options.validators.regex.options.pattern = "/^[a-z]/i"
user.login.elements.username.options.validators.strlen.validator = "StringLength"
user.login.elements.username.options.validators.strlen.options.min = "6"
user.login.elements.username.options.validators.strlen.options.max = "20"
user.login.elements.username.options.required = true
user.login.elements.username.options.filters.lower.filter = "StringToLower"

; elemento password
user.login.elements.password.type = "password"
user.login.elements.password.options.validators.strlen.validator = "StringLength"
user.login.elements.password.options.validators.strlen.options.min = "6"
user.login.elements.password.options.required = true

; elemento submit
user.login.elements.submit.type = "submit"

Entonces puede pasarlo al constructor del formulario:

$config = new Zend_Config_Ini($configFile, 'development');
$form   = new Zend_Form($config->user->login);

y el formulario entero será definido.

Esperamos que después de este pequeño tutorial sea capaz de descubrir el poder y flexibilidad de Zend_Form . Continúe leyendo para profundizar más en el tema.