[ZF-7243] Zend_Filter_StringToLower/Upper:

- added constructor to set encoding at initiation (ZF-7243)
- added check for false encodings
- extended manual to describe this undocumented feature


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

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

@@ -87,22 +87,8 @@
     </sect2>
 
     <xi:include href="Zend_Filter-RealPath.xml" />
-
-    <sect2 id="zend.filter.set.stringtolower">
-        <title>StringToLower</title>
-        <para>
-            Returns the string <varname>$value</varname>, converting alphabetic characters to
-            lowercase as necessary.
-        </para>
-    </sect2>
-
-    <sect2 id="zend.filter.set.stringtoupper">
-        <title>StringToUpper</title>
-        <para>
-            Returns the string <varname>$value</varname>, converting alphabetic characters to
-            uppercase as necessary.
-        </para>
-    </sect2>
+    <xi:include href="Zend_Filter-StringToLower.xml" />
+    <xi:include href="Zend_Filter-StringToUpper.xml" />
 
     <sect2 id="zend.filter.set.stringtrim">
         <title>StringTrim</title>

documentation/manual/en/module_specs/Zend_Filter-StringToLower.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.filter.set.stringtolower">
+    <title>StringToLower</title>
+
+    <para>
+        This filter converts any input to be lowercased.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_StringToLower();
+
+print $filter->filter('SAMPLE');
+// returns "sample"
+]]></programlisting>
+
+    <para>
+        Per default it will only handle characters from the actual locale of your
+        server. Characters from other charsets would be ignored. Still it's
+        possible to also to lowercase them when the mbstring extension is available
+        in your environment. Simply set the wished encoding when initiating the
+        <classname>StringToLower</classname> filter. Or use the
+        <methodname>setEncoding()</methodname> method to change the encoding afterwards.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// using UTF-8
+$filter = new Zend_Filter_StringToLower('UTF-8');
+
+// or give an array which can be usefull when using a configuration
+$filter = new Zend_Filter_StringToLower(array('encoding' => 'UTF-8'));
+
+// or do this afterwards
+$filter->setEncoding('ISO-8859-1');
+]]></programlisting>
+
+    <note>
+        <title>Setting wrong encodings</title>
+
+        <para>
+            Be aware that you will get an exception when you want to set an encoding
+            and the mbstring extension is not available in your environment.
+        </para>
+
+        <para>
+            Also when you are trying to set an encoding which is not supported by your
+            mbstring extension you will get an exception.
+        </para>
+    </note>
+</sect2>

documentation/manual/en/module_specs/Zend_Filter-StringToUpper.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.filter.set.stringtoupper">
+    <title>StringToUpper</title>
+
+    <para>
+        This filter converts any input to be uppercased.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_StringToUpper();
+
+print $filter->filter('Sample');
+// returns "SAMPLE"
+]]></programlisting>
+
+    <para>
+        Like the <classname>StringToLower</classname> filter this filter handles
+        only characters from the actual locale of your server. Using different
+        charactersets works the same as with <classname>StringToLower</classname>.
+    </para>
+
+    <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_StringToUpper(array('encoding' => 'UTF-8'));
+
+// or do this afterwards
+$filter->setEncoding('ISO-8859-1');
+]]></programlisting>
+</sect2>

library/Zend/Filter/StringToLower.php

@@ -1,5 +1,4 @@
 <?php
-
 /**
  * Zend Framework
  *
@@ -20,13 +19,11 @@
  * @version    $Id$
  */
 
-
 /**
  * @see Zend_Filter_Interface
  */
 require_once 'Zend/Filter/Interface.php';
 
-
 /**
  * @category   Zend
  * @package    Zend_Filter
@@ -43,6 +40,30 @@ class Zend_Filter_StringToLower implements Zend_Filter_Interface
     protected $_encoding = null;
 
     /**
+     * Constructor
+     *
+     * @param string|array $options OPTIONAL
+     */
+    public function __construct($options = null)
+    {
+        if (is_array($options) && array_key_exists('encoding', $options)) {
+            $options = $options['encoding'];
+        }
+
+        $this->setEncoding($options);
+    }
+
+    /**
+     * Returns the set encoding
+     *
+     * @return string
+     */
+    public function getEncoding()
+    {
+        return $this->_encoding;
+    }
+
+    /**
      * Set the input encoding for the given string
      *
      * @param  string $encoding
@@ -50,10 +71,19 @@ class Zend_Filter_StringToLower implements Zend_Filter_Interface
      */
     public function setEncoding($encoding = null)
     {
-        if (!function_exists('mb_strtolower')) {
-            require_once 'Zend/Filter/Exception.php';
-            throw new Zend_Filter_Exception('mbstring is required for this feature');
+        if ($encoding !== null) {
+            if (!function_exists('mb_strtolower')) {
+                require_once 'Zend/Filter/Exception.php';
+                throw new Zend_Filter_Exception('mbstring is required for this feature');
+            }
+
+            $encoding = (string) $encoding;
+            if (!in_array($encoding, mb_list_encodings())) {
+                require_once 'Zend/Filter/Exception.php';
+                throw new Zend_Filter_Exception("The given encoding '$encoding' is not supported by mbstring");
+            }
         }
+
         $this->_encoding = $encoding;
     }
 
@@ -67,7 +97,7 @@ class Zend_Filter_StringToLower implements Zend_Filter_Interface
      */
     public function filter($value)
     {
-        if ($this->_encoding) {
+        if ($this->_encoding !== null) {
             return mb_strtolower((string) $value, $this->_encoding);
         }
 

library/Zend/Filter/StringToUpper.php

@@ -1,5 +1,4 @@
 <?php
-
 /**
  * Zend Framework
  *
@@ -20,13 +19,11 @@
  * @version    $Id$
  */
 
-
 /**
  * @see Zend_Filter_Interface
  */
 require_once 'Zend/Filter/Interface.php';
 
-
 /**
  * @category   Zend
  * @package    Zend_Filter
@@ -43,6 +40,30 @@ class Zend_Filter_StringToUpper implements Zend_Filter_Interface
     protected $_encoding = null;
 
     /**
+     * Constructor
+     *
+     * @param string|array $options OPTIONAL
+     */
+    public function __construct($options = null)
+    {
+        if (is_array($options) && array_key_exists('encoding', $options)) {
+            $options = $options['encoding'];
+        }
+
+        $this->setEncoding($options);
+    }
+
+    /**
+     * Returns the set encoding
+     *
+     * @return string
+     */
+    public function getEncoding()
+    {
+        return $this->_encoding;
+    }
+
+    /**
      * Set the input encoding for the given string
      *
      * @param  string $encoding
@@ -50,10 +71,19 @@ class Zend_Filter_StringToUpper implements Zend_Filter_Interface
      */
     public function setEncoding($encoding = null)
     {
-        if (!function_exists('mb_strtoupper')) {
-            require_once 'Zend/Filter/Exception.php';
-            throw new Zend_Filter_Exception('mbstring is required for this feature');
+        if ($encoding !== null) {
+            if (!function_exists('mb_strtoupper')) {
+                require_once 'Zend/Filter/Exception.php';
+                throw new Zend_Filter_Exception('mbstring is required for this feature');
+            }
+
+            $encoding = (string) $encoding;
+            if (!in_array($encoding, mb_list_encodings())) {
+                require_once 'Zend/Filter/Exception.php';
+                throw new Zend_Filter_Exception("The given encoding '$encoding' is not supported by mbstring");
+            }
         }
+
         $this->_encoding = $encoding;
     }
 

tests/Zend/Filter/StringToLowerTest.php

@@ -99,6 +99,22 @@ class Zend_Filter_StringToLowerTest extends PHPUnit_Framework_TestCase
         } catch (Zend_Filter_Exception $e) {
             $this->assertContains('mbstring is required', $e->getMessage());
         }
+    }
+
+    /**
+     * @return void
+     */
+    public function testFalseEncoding()
+    {
+        if (!function_exists('mb_strtolower')) {
+            $this->markTestSkipped('mbstring required');
+        }
 
+        try {
+            $this->_filter->setEncoding('aaaaa');
+            $this->fail();
+        } catch (Zend_Filter_Exception $e) {
+            $this->assertContains('is not supported', $e->getMessage());
+        }
     }
 }

tests/Zend/Filter/StringToUpperTest.php

@@ -99,6 +99,22 @@ class Zend_Filter_StringToUpperTest extends PHPUnit_Framework_TestCase
         } catch (Zend_Filter_Exception $e) {
             $this->assertContains('mbstring is required', $e->getMessage());
         }
+    }
+
+    /**
+     * @return void
+     */
+    public function testFalseEncoding()
+    {
+        if (!function_exists('mb_strtolower')) {
+            $this->markTestSkipped('mbstring required');
+        }
 
+        try {
+            $this->_filter->setEncoding('aaaaa');
+            $this->fail();
+        } catch (Zend_Filter_Exception $e) {
+            $this->assertContains('is not supported', $e->getMessage());
+        }
     }
 }