<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.validate.introduction">
    <title>Introduction</title>

    <para>
        The <classname>Zend_Validate</classname> component provides a set of commonly needed
        validators. It also provides a simple validator chaining mechanism by
        which multiple validators may be applied to a single datum in a
        user-defined order.
    </para>

    <sect2 id="zend.validate.introduction.definition">
        <title>What is a validator?</title>

        <para>
            A validator examines its input with respect to some requirements
            and produces a boolean result - whether the input successfully
            validates against the requirements. If the input does not meet the
            requirements, a validator may additionally provide information
            about which requirement(s) the input does not meet.
        </para>

        <para>
            For example, a web application might require that a username be
            between six and twelve characters in length and may only contain
            alphanumeric characters. A validator can be used for ensuring that
            usernames meet these requirements. If a chosen username does not
            meet one or both of the requirements, it would be useful to know
            which of the requirements the username fails to meet.
        </para>
    </sect2>

    <sect2 id="zend.validate.introduction.using">
        <title>Basic usage of validators</title>

        <para>
            Having defined validation in this way provides the foundation for
            <classname>Zend_Validate_Interface</classname>, which defines two methods,
            <methodname>isValid()</methodname> and <methodname>getMessages()</methodname>. The
            <methodname>isValid()</methodname> method performs validation upon the provided
            value, returning <constant>TRUE</constant> if and only if the value passes
            against the validation criteria.
        </para>

        <para>
            If <methodname>isValid()</methodname> returns <constant>FALSE</constant>, the
            <methodname>getMessages()</methodname> returns an array of messages explaining
            the reason(s) for validation failure. The array keys are short
            strings that identify the reasons for validation failure, and the
            array values are the corresponding human-readable string messages.
            The keys and values are class-dependent; each validation class
            defines its own set of validation failure messages and the unique
            keys that identify them. Each class also has a const
            definition that matches each identifier for a validation failure
            cause.
        </para>

        <note>
            <para>
                The <methodname>getMessages()</methodname> methods return validation
                failure information only for the most recent
                <methodname>isValid()</methodname> call. Each call to
                <methodname>isValid()</methodname> clears any messages and errors caused by
                a previous <methodname>isValid()</methodname> call, because it's likely
                that each call to <methodname>isValid()</methodname> is made for a
                different input value.
            </para>
        </note>

        <para>
            The following example illustrates validation of an e-mail address:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    // email appears to be valid
} else {
    // email is invalid; print the reasons
    foreach ($validator->getMessages() as $messageId => $message) {
        echo "Validation failure '$messageId': $message\n";
    }
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.validate.introduction.messages">
        <title>Customizing messages</title>

        <para>
            Validate classes provide a <methodname>setMessage()</methodname> method with
            which you can specify the format of a message returned by
            <methodname>getMessages()</methodname> in case of validation failure. The
            first argument of this method is a string containing the error
            message. You can include tokens in this string which will be
            substituted with data relevant to the validator. The token
            <emphasis>%value%</emphasis> is supported by all validators; this is
            substituted with the value you passed to <methodname>isValid()</methodname>.
            Other tokens may be supported on a case-by-case basis in each
            validation class. For example, <emphasis>%max%</emphasis> is a token
            supported by <classname>Zend_Validate_LessThan</classname>.
            The <methodname>getMessageVariables()</methodname> method returns an array
            of variable tokens supported by the validator.
        </para>

        <para>
            The second optional argument is a string that identifies the
            validation failure message template to be set, which is useful when
            a validation class defines more than one cause for failure. If you
            omit the second argument, <methodname>setMessage()</methodname> assumes the
            message you specify should be used for the first message template
            declared in the validation class. Many validation classes only have
            one error message template defined, so there is no need to specify
            which message template you are changing.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    'The string \'%value%\' is too short; it must be at least %min% ' .
    'characters',
    Zend_Validate_StringLength::TOO_SHORT);

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

    // "The string 'word' is too short; it must be at least 8 characters"
}
]]></programlisting>

        <para>
            You can set multiple messages using the <methodname>setMessages()</methodname>
            method. Its argument is an array containing key/message pairs.
        </para>

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

$validator->setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =>
        'The string \'%value%\' is too short',
    Zend_Validate_StringLength::TOO_LONG  =>
        'The string \'%value%\' is too long'
));
]]></programlisting>

        <para>
            If your application requires even greater flexibility with which it
            reports validation failures, you can access properties by the same
            name as the message tokens supported by a given validation class.
            The <property>value</property> property is always available in a validator;
            it is the value you specified as the argument of
            <methodname>isValid()</methodname>. Other properties may be supported on a
            case-by-case basis in each validation class.
        </para>

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

if (!validator->isValid('word')) {
    echo 'Word failed: '
        . $validator->value
        . '; its length is not between '
        . $validator->min
        . ' and '
        . $validator->max
        . "\n";
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.validate.introduction.static">
        <title>Using the static is() method</title>

        <para>
            If it's inconvenient to load a given validation class and create an
            instance of the validator, you can use the static method
            <methodname>Zend_Validate::is()</methodname> as an alternative invocation
            style. The first argument of this method is a data input value,
            that you would pass to the <methodname>isValid()</methodname> method. The
            second argument is a string, which corresponds to the basename of
            the validation class, relative to the <classname>Zend_Validate</classname>
            namespace. The <methodname>is()</methodname> method automatically loads the
            class, creates an instance, and applies the <methodname>isValid()</methodname>
            method to the data input.
        </para>

        <programlisting language="php"><![CDATA[
if (Zend_Validate::is($email, 'EmailAddress')) {
    // Yes, email appears to be valid
}
]]></programlisting>

        <para>
            You can also pass an array of constructor arguments, if they
            are needed for the validator.
        </para>

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

        <para>
            The <methodname>is()</methodname> method returns a boolean value, the same as
            the <methodname>isValid()</methodname> method. When using the static
            <methodname>is()</methodname> method, validation failure messages are not
            available.
        </para>

        <para>
            The static usage can be convenient for invoking a validator ad hoc,
            but if you have the need to run a validator for multiple inputs,
            it's more efficient to use the non-static usage, creating an
            instance of the validator object and calling its
            <methodname>isValid()</methodname> method.
        </para>

        <para>
            Also, the <classname>Zend_Filter_Input</classname> class allows you to
            instantiate and run multiple filter and validator classes on demand
            to process sets of input data. See
            <link linkend="zend.filter.input">Zend_Filter_Input</link>.
        </para>

        <sect3 id="zend.validate.introduction.static.namespaces">
            <title>Namespaces</title>

            <para>
                When working with self defined validators you can give a fourth 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 convenience 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(
        'adapter' => 'array',
        'content' => array(
            Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''
        ),
        'locale' => '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(
        'adapter' => 'array',
        'content' => array(
            Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''
        ),
        'locale' => '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>
<!--
vim:se ts=4 sw=4 et:
-->