[ZF-8979] Zend_Validate:

- added chapter for StringLength validator

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21474 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Validate-Set.xml

@@ -178,23 +178,7 @@ if ($validator->isValid($iban)) {
     </sect2>
 
     <xi:include href="Zend_Validate-Sitemap.xml" />
-
-    <sect2 id="zend.validate.set.string_length">
-        <title>StringLength</title>
-
-        <para>
-            Returns <constant>TRUE</constant> if and only if the string length of
-            <varname>$value</varname> is at least a minimum and no greater than a maximum (when the
-            max option is not <constant>NULL</constant>). The <methodname>setMin()</methodname>
-            method throws an exception if the minimum length is set to a value greater than the set
-            maximum length, and the <methodname>setMax()</methodname> method throws an exception if
-            the maximum length is set to a value less than the set minimum length. This class
-            supports UTF-8 and other character encodings, based on the current value of <ulink
-                url="http://www.php.net/manual/en/ref.iconv.php#iconv.configuration">iconv.internal_encoding</ulink>.
-            If you need a different encoding you can set it with the accessor methods getEncoding
-            and setEncoding.
-        </para>
-    </sect2>
+    <xi:include href="Zend_Validate-StringLength.xml" />
 </sect1>
 <!--
 vim:se ts=4 sw=4 et:

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

@@ -0,0 +1,196 @@
+<?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 Zend_Validate_StringLength 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,
+            <acromyn>PHP</acronym> uses one. When your application is using a different encoding
+            than <acromyn>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:
+-->