repo_zf1/documentation/manual/en/module_specs/Zend_Validate-PostCode.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.validate.set.post_code">
    <title>PostCode</title>

    <para>
        <classname>Zend_Validate_PostCode</classname> allows you to determine if a given value is a
        valid postal code. Postal codes are specific to cities, and in some locales termed
        <acronym>ZIP</acronym> codes.
    </para>

    <para>
        <classname>Zend_Validate_PostCode</classname> knows more than 160 different postal code
        formates. To select the correct format there are 2 ways. You can either use a fully
        qualified locale or you can set your own format manually.
    </para>

    <para>
        Using a locale is more convenient as Zend Framework already knows the appropriate postal
        code format for each locale; however, you need to use the fully qualified locale (one
        containing a region specifier) to do so. For instance, the locale "de" is a locale but
        could not be used with <classname>Zend_Validate_PostCode</classname> as it does not include
        the region; "de_AT", however, would be a valid locale, as it specifies the region code
        ("AT", for Austria).
    </para>

    <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_PostCode('de_AT');
]]></programlisting>

    <para>
        When you don't set a locale yourself, then <classname>Zend_Validate_PostCode</classname>
        will use the application wide set locale, or, when there is none, the locale returned by
        <classname>Zend_Locale</classname>.
    </para>

    <programlisting language="php"><![CDATA[
// application wide locale within your bootstrap
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

$validator = new Zend_Validate_PostCode();
]]></programlisting>

    <para>
        You can also change the locale afterwards by calling <methodname>setLocale()</methodname>.
        And of course you can get the actual used locale by calling
        <methodname>getLocale()</methodname>.
    </para>

    <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_PostCode('de_AT');
$validator->setLocale('en_GB');
]]></programlisting>

    <para>
        Postal code formats themself are simply regular expression strings. When the international
        postal code format, which is used by setting the locale, does not fit your needs, then you
        can also manually set a format by calling <methodname>setFormat()</methodname>.
    </para>

    <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_PostCode('de_AT');
$validator->setFormat('AT-\d{5}');
]]></programlisting>

    <note>
        <title>Conventions for self defined formats</title>

        <para>
            When using self defined formats you should omit the starting (<command>'/^'</command>)
            and ending tags (<command>'$/'</command>). They are attached automatically.
        </para>

        <para>
            You should also be aware that postcode values are always be validated in a strict way.
            This means that they have to be written standalone without additional characters when
            they are not covered by the format.
        </para>
    </note>

    <sect3 id="zend.validate.set.post_code.constructor">
        <title>Constructor options</title>

        <para>
            At it's most basic, you may pass either a <classname>Zend_Locale</classname> object or a
            string representing a fully qualified locale to the constructor of
            <classname>Zend_Validate_PostCode</classname>.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_PostCode('de_AT');
$validator = new Zend_Validate_PostCode($locale);
]]></programlisting>

        <para>
            Additionally, you may pass either an array or a <classname>Zend_Config</classname>
            object to the constructor. When you do so, you must include either the key "locale" or
            "format"; these will be used to set the appropriate values in the validator object.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_PostCode(array(
    'locale' => 'de_AT',
    'format' => 'AT_\d+'
));
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.post_code.options">
        <title>Supported options for Zend_Validate_PostCode</title>

        <para>
            The following options are supported for <classname>Zend_Validate_PostCode</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>format</property></emphasis>: Sets a postcode format which
                    will be used for validation of the input.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>locale</property></emphasis>: Sets a locale from which the
                    postcode will be taken from.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->