repo_zf1/documentation/manual/es/module_specs/Zend_Validate.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20115 -->
    <!-- Reviewed: no -->
<sect1 id="zend.validate.introduction">

    <title>Introducción</title>

    <para> Cuando se necesita validar algún tipo de dato, el componente
            <classname>Zend_Validate</classname> ofrece un conjunto de
        validadores, como así también un sencillo mecanismo de encadenado de
        validaciones por el cual múltiples validadores pueden aplicarse a un
        dato en un orden definido por el usuario. </para>

    <sect2 id="zend.validate.introduction.definition">

        <title>¿Qué es un validador?</title>

        <para> Un validador examina su entrada con respecto a algunos
            requerimientos y produce un resultado booleano si la entrada valida
            satisfactoriamente con los requisitos. Si la entrada no cumple los
            requisitos, un validador también podrá proporcionar información
            adicional sobre que requisito(s) no son satisfechos. </para>

        <para> Por ejemplo, una aplicación web podría requerir que un usuario
            ingrese su nombre, de entre seis y doce caracteres de longitud y que
            sólo puede contener caracteres alfanuméricos. Se puede usar un
            validador para asegurar que los usuarios cumplan estos requisitos.
            Si el nombre de usuario elegido no cumple con uno o ambos de los
            requisitos, sería útil saber cuál de estos requisitos no se cumple. </para>

    </sect2>

    <sect2 id="zend.validate.introduction.using">

        <title>Uso básico de validadores</title>

        <para> Habiendo definido la validación de esta manera, Zend Framework
            nos proporciona el fundamento para
                <classname>Zend_Validate_Interface</classname> que define dos
            métodos, <methodname>isValid()</methodname> y
                <methodname>getMessages()</methodname> . El método
                <methodname>isValid()</methodname> realiza la validación del
            valor, devolviendo <constant>TRUE</constant> si y sólo si el valor
            pasa contra el criterio de validación. </para>

        <para> Si <methodname>isValid()</methodname> devuelve
                <constant>FALSE</constant> , la función
                <methodname>getMessages()</methodname> devuelve un array de
            mensajes explicando el motivo(s) del fracaso de la validación. Las
            claves del array son strings cortos que identifican las razones por
            las cuales fracasó la validación, y los valores del array son los
            correspondientes mensajes para ser leídos por un ser humano. Las
            claves y los valores son dependientes de la clase; cada clase de
            validación define su propio conjunto de mensajes de validación
            fallidas y las claves únicas que las identifican. Cada clase tiene
            también una definición constante que hace corresponder a cada
            identificador con una causa del fallo de validación. </para>

        <note>
            <para> El método <methodname>getMessages()</methodname> devuelve
                información del fracaso de la validación sólo para la llamada
                más reciente a <methodname>isValid()</methodname> . Cada llamada
                a <methodname>isValid()</methodname> borra los mensajes y
                errores causados por una llamada anterior
                    <methodname>isValid()</methodname> , porque es probable que
                cada llamada a <methodname>isValid()</methodname> se refiera al
                valor de una entrada diferente. </para>
        </note>

        <para> El siguiente ejemplo ilustra la validación de una dirección de
            e-mail: </para>
        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    // email parece ser válido
} else {
    // email es inválido; muestre la razones
    foreach ($validator->getMessages() as $messageId => $message) {
        echo "Falla de validación '$messageId': $message\n";
    }
}
]]></programlisting>

    </sect2>

    <sect2 id="zend.validate.introduction.messages">

        <title>Personalizar los mensajes</title>

        <para> Para validar las clases se proporciona un método
                <methodname>setMessage()</methodname> con el que se puede
            especificar el formato de un mensaje devuelto por
                <methodname>getMessages()</methodname> en caso de fallo de
            validación. El primer argumento de este método es un string que
            contiene el mensaje de error. Usted puede incluir tokens en este
            array que serán sustituidos con datos relevantes al validador. El
            token <emphasis>%value%</emphasis> es aceptado por todos los
            validadores, que es sustituido por el valor que pasó a
                <methodname>isValid()</methodname> . Cada clase de validación,
            puede dar apoyo a otros tokens en base a cada caso. Por ejemplo,
                <emphasis>%max%</emphasis> es un token apoyado por
                <classname>Zend_Validate_LessThan</classname> . El método
                <methodname>getMessageVariables()</methodname> devuelve un array
            de tokens variables aceptados por el validador. </para>

        <para> El segundo argumento opcional es un string que identifica la
            plantilla de mensajes que se establecerá en caso del fracaso de la
            validación, lo que es útil cuando una clase de validación define más
            de una causa para el fallo. Si omite el segundo argumento,
                <methodname>setMessage()</methodname> asume que el mensaje que
            especifique debe ser utilizado por la plantilla del primer mensaje
            que declaró en la clase de validación. Muchas clases de validación
            sólo definen una plantilla de mensaje de error, así que no hay
            necesidad de especificar el cambio de plantilla de mensaje. </para>

        <para>
            <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));

$validator->setMessage(
    'El string \'%value%\' es muy corto; debe tener al menos %min% ' .
    'caracteres',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('word')) {
    $messages = $validator->getMessages();
    echo current($messages);

    // "El string 'word' es muy corto; debe tener al menos 8 caracteres"
}
]]></programlisting>
        </para>

        <para> Puede establecer varios mensajes usando el método
                <methodname>setMessages()</methodname> . Su argumento es un
            array que contiene pares de clave/mensaje. </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));

$validator->setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =>
        'El string \'%value%\' es muy corto',
    Zend_Validate_StringLength::TOO_LONG  =>
        'El string \'%value%\' es muy largo'
));
]]></programlisting>

        <para> Incluso, si su aplicación requiere una mayor flexibilidad para
            informar los fallos de validación, puede acceder a las propiedades
            por el mismo nombre, tal como los tokens de mensajes apoyados por
            una determinada clase de validación. La propiedad
                <methodname>value</methodname> siempre está disponible en un
            validador; es el valor que especificó en el argumento de
                <methodname>isValid()</methodname> . En cada clase de validación
            se puede dar apoyo a otras propiedades basándose en el esquema de
            caso por caso. <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);

if (!validator->isValid('word')) {
    echo 'Palabra fallada: '
        . $validator->value
        . '; su longitud no está entre '
        . $validator->min
        . ' y '
        . $validator->max
        . "\n";
}
]]></programlisting>
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.static">

        <title> Utilizando el método estático is() </title>

        <para> Si es inconveniente cargar una clase de validación y crear una
            instancia del validador, puede usar el método estático
                <methodname>Zend_Validate::is()</methodname> como un estilo
            alternativo de invocación. El primer argumento de este método es el
            valor de una entrada de datos que usted pasaría al método
                <methodname>isValid()</methodname> . El segundo argumento es un
            string, que corresponde al nombre base de la clase de validación,
            relativo al nombre de espacio <classname>Zend_Validate</classname> .
            El método <methodname>is()</methodname> carga automáticamente la
            clase, crea una instancia y aplica el método
                <methodname>isValid()</methodname> a la entrada de datos. <programlisting language="php"><![CDATA[
if (Zend_Validate::is($email, 'EmailAddress')) {
    // Si, el email parece ser válido
}
]]></programlisting>
        </para>

        <para> Si el validador lo necesita, también puede pasar un array de
            constructores de argumentos. <programlisting language="php"><![CDATA[
if (Zend_Validate::is($value, 'Between', array('min' => 1, 'max' => 12))) {
    // Si, $value está entre 1 y 12
}
]]></programlisting>
        </para>

        <para> El método <methodname>is()</methodname> devuelve un valor
            booleano, lo mismo que el método <methodname>isValid()</methodname>
            . Cuando se utiliza el método estático <methodname>is()</methodname>
            , no están disponibles los mensajes de fracaso de validación. </para>

        <para> El uso estático puede ser conveniente para invocar un validador
            ad-hoc (hecho especialmente), pero si tiene la necesidad de ejecutar
            el validador para múltiples entradas, es más eficiente usar métodos
            no estáticos, creando una instancia del objeto validador y llamando
            a su método <methodname>isValid()</methodname> . </para>

        <para> También la clase <classname>Zend_Filter_Input</classname> le
            permite crear ejemplos y ejecutar múltiples filtros y clases de
            validadores por demanda, para procesar juegos de datos de entrada.
            Ver <xref linkend="zend.filter.input"/> . </para>
        <sect3 id="zend.validate.introduction.static.namespaces">

            <title>Namespaces</title>

            <para> When working with self defined validators you can give a
                forth parameter to <methodname>Zend_Validate::is()</methodname>
                which is the namespace where your validator can be found. </para>

            <programlisting language="php"><![CDATA[
if (Zend_Validate::is($value, 'MyValidator', array('min' => 1, 'max' => 12),
                      array('FirstNamespace', 'SecondNamespace')) {
    // Yes, $value is ok
}
]]></programlisting>

            <para>
                <classname>Zend_Validate</classname> allows also to set
                namespaces as default. This means that you can set them once in
                your bootstrap and have not to give them again for each call of
                    <methodname>Zend_Validate::is()</methodname> . The following
                code snippet is identical to the above one. </para>

            <programlisting language="php"><![CDATA[
Zend_Validate::setDefaultNamespaces(array('FirstNamespace', 'SecondNamespace'));
if (Zend_Validate::is($value, 'MyValidator', array('min' => 1, 'max' => 12)) {
    // Yes, $value is ok
}

if (Zend_Validate::is($value, 'OtherValidator', array('min' => 1, 'max' => 12)) {
    // Yes, $value is ok
}
]]></programlisting>

            <para> For your convinience there are following methods which allow
                the handling of namespaces: </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>
                            <methodname>Zend_Validate::getDefaultNamespaces()</methodname>
                        </emphasis> : Returns all set default namespaces as
                        array. </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>
                            <methodname>Zend_Validate::setDefaultNamespaces()</methodname>
                        </emphasis> : Sets new default namespaces and overrides
                        any previous set. It accepts either a string for a
                        single namespace of an array for multiple namespaces.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>
                            <methodname>Zend_Validate::addDefaultNamespaces()</methodname>
                        </emphasis> : Adds additional namespaces to already set
                        ones. It accepts either a string for a single namespace
                        of an array for multiple namespaces. </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>
                            <methodname>Zend_Validate::hasDefaultNamespaces()</methodname>
                        </emphasis> : Returns <constant>TRUE</constant>  when one or more default
                        namespaces are set, and <constant>FALSE</constant> when no default namespaces
                        are set. </para>
                </listitem>
            </itemizedlist>
        </sect3>

    </sect2>
    <sect2 id="zend.validate.introduction.translation">

        <title>Translating messages</title>

        <para> Validate classes provide a
                <methodname>setTranslator()</methodname> method with which you
            can specify a instance of <classname>Zend_Translate</classname>
            which will translate the messages in case of a validation failure.
            The <methodname>getTranslator()</methodname> method returns the set
            translator instance. </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
    'en'
);

$validator->setTranslator($translate);
]]></programlisting>

        <para> With the static <methodname>setDefaultTranslator()</methodname>
            method you can set a instance of
                <classname>Zend_Translate</classname> which will be used for all
            validation classes, and can be retrieved with
                <methodname>getDefaultTranslator()</methodname> . This prevents
            you from setting a translator manually for all validator classes,
            and simplifies your code. </para>

        <programlisting language="php"><![CDATA[
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''),
    'en'
);
Zend_Validate::setDefaultTranslator($translate);
]]></programlisting>

        <note>
            <para> When you have set an application wide locale within your
                registry, then this locale will be used as default translator.
            </para>
        </note>

        <para> Sometimes it is necessary to disable the translator within a
            validator. To archive this you can use the
                <methodname>setDisableTranslator()</methodname> method, which
            accepts a boolean parameter, and
                <methodname>translatorIsDisabled()</methodname> to get the set
            value. </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
if (!$validator->isTranslatorDisabled()) {
    $validator->setDisableTranslator();
}
]]></programlisting>

        <para> It is also possible to use a translator instead of setting own
            messages with <methodname>setMessage()</methodname> . But doing so,
            you should keep in mind, that the translator works also on messages
            you set your own. </para>

    </sect2>
</sect1>