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

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

    <para>
        This validator allows you to validate if a given string is between a defined length.
    </para>

    <note>
        <title>Zend_Validate_StringLength supports only string validation</title>

        <para>
            It should be noted that <classname>Zend_Validate_StringLength</classname> supports only
            the validation of strings. Integers, floats, dates or objects can not be validated with
            this validator.
        </para>
    </note>

    <sect3 id="zend.validate.set.stringlength.options">
        <title>Supported options for Zend_Validate_StringLength</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>encoding</property></emphasis>: Sets the
                    <constant>ICONV</constant> encoding which has to be used for this string.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>min</property></emphasis>: Sets the minimum allowed length
                    for a string.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>max</property></emphasis>: Sets the maximum allowed length
                    for a string.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.validate.set.stringlength.basic">
        <title>Default behaviour for Zend_Validate_StringLength</title>

        <para>
            Per default this validator checks if a value is between <property>min</property> and
            <property>max</property>. But for <property>min</property> the default value is
            <emphasis>0</emphasis> and for <property>max</property> it is
            <emphasis><constant>NULL</constant></emphasis> which means unlimited.
        </para>

        <para>
            So per default, without giving any options, this validator only checks if the input
            is a string.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.stringlength.maximum">
        <title>Limiting the maximum allowed length of a string</title>

        <para>
            To limit the maximum allowed length of a string you need to set the
            <property>max</property> property. It accepts an integer value as input.
        </para>

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

$validator->isValid("Test"); // returns true
$validator->isValid("Testing"); // returns false
]]></programlisting>

        <para>
            You can set the maximum allowed length also afterwards by using the
            <methodname>setMax()</methodname> method. And <methodname>getMax()</methodname> to
            retrieve the actual maximum border.
        </para>

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

$validator->isValid("Test"); // returns true
$validator->isValid("Testing"); // returns false
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.stringlength.minimum">
        <title>Limiting the minimal required length of a string</title>

        <para>
            To limit the minimal required length of a string you need to set the
            <property>min</property> property. It accepts also an integer value as input.
        </para>

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

$validator->isValid("Test"); // returns false
$validator->isValid("Testing"); // returns true
]]></programlisting>

        <para>
            You can set the minimal requested length also afterwards by using the
            <methodname>setMin()</methodname> method. And <methodname>getMin()</methodname> to
            retrieve the actual minimum border.
        </para>

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

$validator->isValid("Test"); // returns false
$validator->isValid("Testing"); // returns true
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.stringlength.both">
        <title>Limiting a string on both sides</title>

        <para>
            Sometimes it is required to get a string which has a maximal defined length but which
            is also minimal chars long. For example when you have a textbox where a user can enter
            his name, then you may want to limit the name to maximum 30 chars but want to get sure
            that he entered his name. So you limit the mimimum required length to 3 chars. See the
            following example:
        </para>

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

$validator->isValid("."); // returns false
$validator->isValid("Test"); // returns true
$validator->isValid("Testing"); // returns true
]]></programlisting>

        <note>
            <title>Setting a lower maximum border than the minimum border</title>

            <para>
                When you try to set a lower maximum value as the actual minimum value, or a
                higher minimum value as the actual maximum value, then an exception will be
                raised.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.stringlength.encoding">
        <title>Encoding of values</title>

        <para>
            Strings are always using a encoding. Even when you don't set the encoding explicit,
            <acronym>PHP</acronym> uses one. When your application is using a different encoding
            than <acronym>PHP</acronym> itself then you should set an encoding yourself.
        </para>

        <para>
            You can set your own encoding at initiation with the <property>encoding</property>
            option, or by using the <methodname>setEncoding()</methodname> method. We assume that
            your installation uses <acronym>ISO</acronym> and your application it set to
            <acronym>ISO</acronym>. In this case you will see the below behaviour.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_StringLength(
    array('min' => 6)
);
$validator->isValid("Ärger"); // returns false

$validator->setEncoding("UTF-8");
$validator->isValid("Ärger"); // returns true

$validator2 = new Zend_Validate_StringLength(
    array('min' => 6, 'encoding' => 'UTF-8')
);
$validator2->isValid("Ärger"); // returns true
]]></programlisting>

        <para>
            So when your installation and your application are using different encodings, then you
            should always set an encoding yourself.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->