ZF-8962 #comment added manual chapter/section with description and examples for Zend_Filter_HtmlEntities. Also added 3 new unit tests.

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

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

@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.filter.set.htmlentities">
+    <title>HtmlEntities</title>
+
+    <para>
+        Returns the string <varname>$value</varname>, converting characters to their corresponding
+        <acronym>HTML</acronym> entity equivalents where they exist.
+    </para>
+
+    <sect3 id="zend.filter.set.htmlentities.options">
+        <title>Supported options for Zend_Filter_HtmlEntities</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Filter_HtmlEntities</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>quotestyle</property></emphasis>: Equivalent to the PHP
+                    <varname>htmlentities</varname> native function parameter <emphasis>quote_style</emphasis>.
+                    This allows you to define what will be done with 'single' and "double" quotes. It accepts
+                    constants: (ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES) with the default being ENT_COMPAT.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <emphasis><property>charset</property></emphasis>: Equivalent to the PHP
+                    <varname>htmlentities</varname> native function parameter <emphasis>charset</emphasis>.
+                    This defines the character set to be used in filtering. Unlike the PHP native function
+                    the default is 'UTF-8'. See "http://php.net/htmlentities" for a list of supported character sets.
+                </para>
+
+                <note>
+                    <para>
+                     This option can also be set via the <varname>$options</varname> parameter as a Zend_Config
+                     object or array. The option key will be accepted as either <varname>charset</varname> or
+                     <varname>encoding</varname>.
+                    </para>
+                </note>
+            </listitem>
+
+             <listitem>
+                <para>
+                    <emphasis><property>doublequote</property></emphasis>: Equivalent to the PHP
+                    <varname>htmlentities</varname> native function parameter <emphasis>double_encode</emphasis>.
+                    If set to <varname>false</varname> existing html entities will not be encoded. The default is
+                    to convert everything (<varname>true</varname>).
+                </para>
+
+                <note>
+                    <para>
+                        This option must be set via the <varname>$options</varname> parameter or the
+                        setDoubleEncode() method.
+                    </para>
+                </note>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.htmlentities.basic">
+        <title>Basic usage</title>
+
+        <para>
+            See the following example for the default behaviour of this filter.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities();
+
+$return = $filter->filter('<');
+// returns '&lt;'
+]]></programlisting>
+    </sect3>
+
+    <sect3 id="zend.filter.set.htmlentities.quotestyle">
+        <title>Quote Style</title>
+
+        <para>
+            <classname>Zend_Filter_HtmlEntities</classname> allows changing the quote style used. This can be useful
+            when you want to leave double, single, or both types of quotes un-filtered. See the following example:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities(array('quotestyle' => ENT_QUOTES));
+
+$input  = "A 'single' and " . '"double"';
+$return = $filter->filter($input);
+// returns
+//A &#039;single&#039; and &quot;double&quot;
+]]></programlisting>
+
+        <para>
+            The above example returns <emphasis>A &#039;single&#039; and &quot;double&quot;</emphasis>. Notice that 'single' as well
+            as "double" quotes are filtered.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities(array('quotestyle' => ENT_COMPAT));
+
+$input  = "A 'single' and " . '"double"';
+$return = $filter->filter($input);
+// returns
+//A 'single' and &quot;double&quot;
+]]></programlisting>
+
+        <para>
+            The above example returns <emphasis>>A 'single' and &quot;double&quot;</emphasis>. Notice that "double"
+            quotes are filtered while 'single' quotes are not altered.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities(array('quotestyle' => ENT_NOQUOTES));
+
+$input  = "A 'single' and " . '"double"';
+$return = $filter->filter($input);
+// returns:
+//A 'single' and "double"
+]]></programlisting>
+
+        <para>
+            The above example returns <emphasis>A 'single' and "double"</emphasis>. Notice that neither "double" or 
+            'single' quotes are altered.
+        </para>
+
+    </sect3>
+
+    <sect3 id="zend.filter.set.htmlentities.">
+        <title>Helper Methods</title>
+
+        <para>
+            To change or retrieve the <property>quotestyle</property> after instantiation, the two methods
+            <methodname>setQuoteStyle</methodname> and <methodname>getQuoteStyle</methodname> may be used respectively
+            <methodname>setQuoteStyle</methodname> accepts one parameter ($quoteStyle); the following constants are
+            acceptable: (ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES).
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities();
+
+$filter->setQuoteStyle(ENT_QUOTES);
+$return = $filter->getQuoteStyle(ENT_QUOTES);
+// returns 3
+]]></programlisting>
+
+         <para>
+            To change or retrieve the <property>charset</property> after instantiation, the two methods
+            <methodname>setCharSet</methodname> and <methodname>getCharSet</methodname> may be used respectively.
+            <methodname>setCharSet</methodname> accepts one parameter ($charSet); See "http://php.net/htmlentities"
+            for a list of supported character sets.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities();
+
+$filter->setQuoteStyle(ENT_QUOTES);
+$return = $filter->getQuoteStyle(ENT_QUOTES);
+// returns 3
+]]></programlisting>
+
+          <para>
+            To change or retrieve the <property>doublequote</property> option after instantiation, the two methods
+            <methodname>setDoubleQuote</methodname> and <methodname>getDoubleQuote</methodname> may be used respectively.
+            <methodname>setDoubleQuote</methodname> accepts one boolean parameter ($doubleQuote).
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_HtmlEntities();
+
+$filter->setQuoteStyle(ENT_QUOTES);
+$return = $filter->getQuoteStyle(ENT_QUOTES);
+// returns 3
+]]></programlisting>
+
+
+    </sect3>
+
+</sect2>
+<!--
+vim:se ts=4 sw=4 et:
+-->

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

@@ -17,15 +17,7 @@
     <xi:include href="Zend_Filter-Digits.xml" />
     <xi:include href="Zend_Filter-Dir.xml" />
     <xi:include href="Zend_Filter-Encryption.xml" />
-
-    <sect2 id="zend.filter.set.htmlentities">
-        <title>HtmlEntities</title>
-
-        <para>
-            Returns the string <varname>$value</varname>, converting characters to their
-            corresponding <acronym>HTML</acronym> entity equivalents where they exist.
-        </para>
-    </sect2>
+    <xi:include href="Zend_Filter-HtmlEntities.xml" />
 
     <sect2 id="zend.filter.set.int">
         <title>Int</title>

tests/Zend/Filter/HtmlEntitiesTest.php

@@ -168,4 +168,49 @@ class Zend_Filter_HtmlEntitiesTest extends PHPUnit_Framework_TestCase
         $this->assertEquals('ISO-8859-1', $filter->getEncoding());
         $this->assertEquals(5, $filter->getQuoteStyle());
     }
+
+    /**
+     * Ensures that when ENT_QUOTES is set, the filtered value has both 'single' and "double" quotes encoded
+     *
+     * @group  ZF-8962
+     * @return void
+     */
+    public function testQuoteStyleQuotesEncodeBoth()
+    {
+        $input  = "A 'single' and " . '"double"';
+        $result = 'A 'single' and "double"';
+
+        $this->_filter->setQuoteStyle(ENT_QUOTES);
+        $this->assertEquals($result, $this->_filter->filter($input));
+    }
+
+    /**
+     * Ensures that when ENT_COMPAT is set, the filtered value has only "double" quotes encoded
+     *
+     * @group  ZF-8962
+     * @return void
+     */
+    public function testQuoteStyleQuotesEncodeDouble()
+    {
+        $input  = "A 'single' and " . '"double"';
+        $result = "A 'single' and "double"";
+        
+        $this->_filter->setQuoteStyle(ENT_COMPAT);
+        $this->assertEquals($result, $this->_filter->filter($input));
+    }
+
+    /**
+     * Ensures that when ENT_NOQUOTES is set, the filtered value leaves both "double" and 'single' quotes un-altered
+     *
+     * @group  ZF-8962
+     * @return void
+     */
+    public function testQuoteStyleQuotesEncodeNone()
+    {
+        $input  = "A 'single' and " . '"double"';
+        $result = "A 'single' and " . '"double"';
+
+        $this->_filter->setQuoteStyle(ENT_NOQUOTES);
+        $this->assertEquals($result, $this->_filter->filter($input));
+    }
 }