[GENERIC] Zend_Filter_Null:

- cored new component Zend_Filter_Null

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

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

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.filter.set.null">
+    <title>Null</title>
+
+    <para>
+        This filter will change the given input to be <constant>NULL</constant> if it meets specific
+        criteria. This is often necessary when you work with databases and want to have a
+        <constant>NULL</constant> value instead of a boolean or any other type.
+    </para>
+
+    <sect3 id="zend.filter.set.null.default">
+        <title>Default behaviour for Zend_Filter_Null</title>
+
+        <para>
+            Per default this filter works like <acronym>PHP</acronym>'s
+            <methodname>empty()</methodname> method; in other words, if
+            <methodname>empty()</methodname> returns a boolean true, then a
+            <constant>NULL</constant> value will be returned.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_Null();
+$value  = '';
+$result = $filter->filter($value);
+// returns null instead of the empty string
+]]></programlisting>
+
+        <para>
+            This means that without providing any configuration,
+            <classname>Zend_Filter_Null</classname> will accept all input types and return
+            <constant>NULL</constant> in the same cases as <methodname>empty()</methodname>.
+        </para>
+
+        <para>
+            Any other value will be returned as is, without any changes.
+        </para>
+    </sect3>
+
+    <sect3 id="zend.filter.set.null.types">
+        <title>Changing behaviour for Zend_Filter_Null</title>
+
+        <para>
+            Sometimes it's not enough to filter based on <methodname>empty()</methodname>. Therefor
+            <classname>Zend_Filter_Null</classname> allows you to configure which type will be
+            converted and which not.
+        </para>
+
+        <para>
+            The following types can be handled:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis>boolean</emphasis>: Converts a boolean
+                    <emphasis><constant>FALSE</constant></emphasis> value to
+                    <constant>NULL</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>integer</emphasis>: Converts an integer <emphasis>0</emphasis> value to
+                    <constant>NULL</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>empty_array</emphasis>: Converts an empty <emphasis>array</emphasis>
+                    to <constant>NULL</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>string</emphasis>: Converts an empty string <emphasis>''</emphasis> to
+                    <constant>NULL</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>zero</emphasis>: Converts a string containing the single character
+                    zero (<emphasis>'0'</emphasis>) to <constant>NULL</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>all</emphasis>: Converts all above types to <constant>NULL</constant>.
+                    (This is the default behavior.)
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            There are several ways to select which of the above types are filtered. You can give one
+            or multiple types and add them, you can give an array, you can use constants, or you can
+            give a textual string. See the following examples:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// converts false to null
+$filter = new Zend_Filter_Null(Zend_Filter_Null::BOOLEAN);
+
+// converts false and 0 to null
+$filter = new Zend_Filter_Null(
+    Zend_Filter_Null::BOOLEAN + Zend_Filter_Null::INTEGER
+);
+
+// converts false and 0 to null
+$filter = new Zend_Filter_Null( array(
+    Zend_Filter_Null::BOOLEAN,
+    Zend_Filter_Null::INTEGER
+));
+
+// converts false and 0 to null
+$filter = new Zend_Filter_Null(array(
+    'boolean',
+    'integer',
+));
+]]></programlisting>
+
+        <para>
+            You can also give an instance of <classname>Zend_Config</classname> to set the wished
+            types. To set types afterwards use <methodname>setType()</methodname>.
+        </para>
+    </sect3>
+</sect2>
+<!--
+vim:se ts=4 sw=4 et:
+-->

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

@@ -78,6 +78,7 @@
 
     <xi:include href="Zend_Filter-LocalizedToNormalized.xml" />
     <xi:include href="Zend_Filter-NormalizedToLocalized.xml" />
+    <xi:include href="Zend_Filter-Null.xml" />
 
     <sect2 id="zend.filter.set.stripnewlines">
         <title>StripNewlines</title>

library/Zend/Filter/Null.php

@@ -0,0 +1,183 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Filter
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id$
+ */
+
+/**
+ * @see Zend_Filter_Interface
+ */
+require_once 'Zend/Filter/Interface.php';
+
+/**
+ * @category   Zend
+ * @package    Zend_Filter
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ */
+class Zend_Filter_Null implements Zend_Filter_Interface
+{
+    const BOOLEAN      = 1;
+    const INTEGER      = 2;
+    const EMPTY_ARRAY  = 4;
+    const STRING       = 8;
+    const ZERO         = 16;
+    const ALL          = 31;
+
+    protected $_constants = array(
+        self::BOOLEAN     => 'boolean',
+        self::INTEGER     => 'integer',
+        self::EMPTY_ARRAY => 'array',
+        self::STRING      => 'string',
+        self::ZERO        => 'zero',
+        self::ALL         => 'all'
+    );
+
+    /**
+     * Internal type to detect
+     *
+     * @var integer
+     */
+    protected $_type = self::ALL;
+
+    /**
+     * Constructor
+     *
+     * @param string|array|Zend_Config $options OPTIONAL
+     */
+    public function __construct($options = null)
+    {
+        if ($options instanceof Zend_Config) {
+            $options = $options->toArray();
+        } else if (!is_array($options)) {
+            $options = func_get_args();
+            $temp    = array();
+            if (!empty($options)) {
+                $temp = array_shift($options);
+            }
+            $options = $temp;
+        } else if (is_array($options) && array_key_exists('type', $options)) {
+            $options = $options['type'];
+        }
+
+        if (!empty($options)) {
+            $this->setType($options);
+        }
+    }
+
+    /**
+     * Returns the set null types
+     *
+     * @return array
+     */
+    public function getType()
+    {
+        return $this->_type;
+    }
+
+    /**
+     * Set the null types
+     *
+     * @param  integer|array $type
+     * @throws Zend_Filter_Exception
+     * @return Zend_Filter_Null
+     */
+    public function setType($type = null)
+    {
+        if (is_array($type)) {
+            $detected = 0;
+            foreach($type as $value) {
+                if (is_int($value)) {
+                    $detected += $value;
+                } else if (in_array($value, $this->_constants)) {
+                    $detected += array_search($value, $this->_constants);
+                }
+            }
+
+            $type = $detected;
+        } else if (is_string($type)) {
+            if (in_array($type, $this->_constants)) {
+                $type = array_search($type, $this->_constants);
+            }
+        }
+
+        if (!is_int($type) || ($type < 0) || ($type > self::ALL)) {
+            require_once 'Zend/Filter/Exception.php';
+            throw new Zend_Filter_Exception('Unknown type');
+        }
+
+        $this->_type = $type;
+        return $this;
+    }
+
+    /**
+     * Defined by Zend_Filter_Interface
+     *
+     * Returns null representation of $value, if value is empty and matches 
+     * types that should be considered null.
+     *
+     * @param  string $value
+     * @return string
+     */
+    public function filter($value)
+    {
+        $type = $this->getType();
+
+        // STRING ZERO ('0')
+        if ($type >= self::ZERO) {
+            $type -= self::ZERO;
+            if (is_string($value) && ($value == '0')) {
+                return null;
+            }
+        }
+
+        // STRING ('')
+        if ($type >= self::STRING) {
+            $type -= self::STRING;
+            if (is_string($value) && ($value == '')) {
+                return null;
+            }
+        }
+
+        // EMPTY_ARRAY (array())
+        if ($type >= self::EMPTY_ARRAY) {
+            $type -= self::EMPTY_ARRAY;
+            if (is_array($value) && ($value == array())) {
+                return null;
+            }
+        }
+
+        // INTEGER (0)
+        if ($type >= self::INTEGER) {
+            $type -= self::INTEGER;
+            if (is_int($value) && ($value == 0)) {
+                return null;
+            }
+        }
+
+        // BOOLEAN (false)
+        if ($type >= self::BOOLEAN) {
+            $type -= self::BOOLEAN;
+            if (is_bool($value) && ($value == false)) {
+                return null;
+            }
+        }
+
+        return $value;
+    }
+}

tests/Zend/Filter/AllTests.php

@@ -92,6 +92,11 @@ require_once 'Zend/Filter/InputTest.php';
 require_once 'Zend/Filter/IntTest.php';
 
 /**
+ * @see Zend_Filter_NullTest
+ */
+require_once 'Zend/Filter/NullTest.php';
+
+/**
  * @see Zend_Filter_PregReplaceTest
  */
 require_once 'Zend/Filter/PregReplaceTest.php';

tests/Zend/Filter/NullTest.php

@@ -0,0 +1,297 @@
+<?php
+/**
+ * Zend Framework
+ *
+ * LICENSE
+ *
+ * This source file is subject to the new BSD license that is bundled
+ * with this package in the file LICENSE.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://framework.zend.com/license/new-bsd
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to license@zend.com so we can send you a copy immediately.
+ *
+ * @category   Zend
+ * @package    Zend_Filter
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @version    $Id$
+ */
+
+/**
+ * Test helper
+ */
+require_once dirname(__FILE__) . '/../../TestHelper.php';
+
+/**
+ * @see Zend_Filter_Int
+ */
+require_once 'Zend/Filter/Null.php';
+
+/**
+ * @category   Zend
+ * @package    Zend_Filter
+ * @subpackage UnitTests
+ * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license    http://framework.zend.com/license/new-bsd     New BSD License
+ * @group      Zend_Filter
+ */
+class Zend_Filter_NullTest extends PHPUnit_Framework_TestCase
+{
+    /**
+     * Zend_Filter_Null object
+     *
+     * @var Zend_Filter_Null
+     */
+    protected $_filter;
+
+    /**
+     * Creates a new Zend_Filter_Null object for each test method
+     *
+     * @return void
+     */
+    public function setUp()
+    {
+        $this->_filter = new Zend_Filter_Null();
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testBasic()
+    {
+        $this->assertEquals(null, $this->_filter->filter('0'));
+        $this->assertEquals(null, $this->_filter->filter(''));
+        $this->assertEquals(null, $this->_filter->filter(0));
+        $this->assertEquals(null, $this->_filter->filter(array()));
+        $this->assertEquals(null, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testOnlyBoolean()
+    {
+        $this->_filter->setType(Zend_Filter_Null::BOOLEAN);
+        $this->assertEquals('0', $this->_filter->filter('0'));
+        $this->assertEquals('', $this->_filter->filter(''));
+        $this->assertEquals(0, $this->_filter->filter(0));
+        $this->assertEquals(array(), $this->_filter->filter(array()));
+        $this->assertEquals(null, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testOnlyInteger()
+    {
+        $this->_filter->setType(Zend_Filter_Null::INTEGER);
+        $this->assertEquals('0', $this->_filter->filter('0'));
+        $this->assertEquals('', $this->_filter->filter(''));
+        $this->assertEquals(null, $this->_filter->filter(0));
+        $this->assertEquals(array(), $this->_filter->filter(array()));
+        $this->assertEquals(false, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testOnlyArray()
+    {
+        $this->_filter->setType(Zend_Filter_Null::EMPTY_ARRAY);
+        $this->assertEquals('0', $this->_filter->filter('0'));
+        $this->assertEquals('', $this->_filter->filter(''));
+        $this->assertEquals(0, $this->_filter->filter(0));
+        $this->assertEquals(null, $this->_filter->filter(array()));
+        $this->assertEquals(false, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testOnlyString()
+    {
+        $this->_filter->setType(Zend_Filter_Null::STRING);
+        $this->assertEquals('0', $this->_filter->filter('0'));
+        $this->assertEquals(null, $this->_filter->filter(''));
+        $this->assertEquals(0, $this->_filter->filter(0));
+        $this->assertEquals(array(), $this->_filter->filter(array()));
+        $this->assertEquals(false, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testOnlyZero()
+    {
+        $this->_filter->setType(Zend_Filter_Null::ZERO);
+        $this->assertEquals(null, $this->_filter->filter('0'));
+        $this->assertEquals('', $this->_filter->filter(''));
+        $this->assertEquals(0, $this->_filter->filter(0));
+        $this->assertEquals(array(), $this->_filter->filter(array()));
+        $this->assertEquals(false, $this->_filter->filter(false));
+        $this->assertEquals('test', $this->_filter->filter('test'));
+        $this->assertEquals(true, $this->_filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testArrayConstantNotation()
+    {
+        $filter = new Zend_Filter_Null(
+            array(
+                Zend_Filter_Null::ZERO,
+                Zend_Filter_Null::STRING,
+                Zend_Filter_Null::BOOLEAN
+            )
+        );
+
+        $this->assertEquals(null, $filter->filter('0'));
+        $this->assertEquals(null, $filter->filter(''));
+        $this->assertEquals(0, $filter->filter(0));
+        $this->assertEquals(array(), $filter->filter(array()));
+        $this->assertEquals(null, $filter->filter(false));
+        $this->assertEquals('test', $filter->filter('test'));
+        $this->assertEquals(true, $filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testArrayConfigNotation()
+    {
+        $filter = new Zend_Filter_Null(
+            array(
+                'type' => array(
+                    Zend_Filter_Null::ZERO,
+                    Zend_Filter_Null::STRING,
+                    Zend_Filter_Null::BOOLEAN),
+                'test' => false
+            )
+        );
+
+        $this->assertEquals(null, $filter->filter('0'));
+        $this->assertEquals(null, $filter->filter(''));
+        $this->assertEquals(0, $filter->filter(0));
+        $this->assertEquals(array(), $filter->filter(array()));
+        $this->assertEquals(null, $filter->filter(false));
+        $this->assertEquals('test', $filter->filter('test'));
+        $this->assertEquals(true, $filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testMultiConstantNotation()
+    {
+        $filter = new Zend_Filter_Null(
+            Zend_Filter_Null::ZERO + Zend_Filter_Null::STRING + Zend_Filter_Null::BOOLEAN
+        );
+
+        $this->assertEquals(null, $filter->filter('0'));
+        $this->assertEquals(null, $filter->filter(''));
+        $this->assertEquals(0, $filter->filter(0));
+        $this->assertEquals(array(), $filter->filter(array()));
+        $this->assertEquals(null, $filter->filter(false));
+        $this->assertEquals('test', $filter->filter('test'));
+        $this->assertEquals(true, $filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testStringNotation()
+    {
+        $filter = new Zend_Filter_Null(
+            array(
+                'zero', 'string', 'boolean'
+            )
+        );
+
+        $this->assertEquals(null, $filter->filter('0'));
+        $this->assertEquals(null, $filter->filter(''));
+        $this->assertEquals(0, $filter->filter(0));
+        $this->assertEquals(array(), $filter->filter(array()));
+        $this->assertEquals(null, $filter->filter(false));
+        $this->assertEquals('test', $filter->filter('test'));
+        $this->assertEquals(true, $filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testSingleStringNotation()
+    {
+        $filter = new Zend_Filter_Null(
+            'boolean'
+        );
+
+        $this->assertEquals('0', $filter->filter('0'));
+        $this->assertEquals(null, $filter->filter(''));
+        $this->assertEquals(0, $filter->filter(0));
+        $this->assertEquals(array(), $filter->filter(array()));
+        $this->assertEquals(false, $filter->filter(false));
+        $this->assertEquals('test', $filter->filter('test'));
+        $this->assertEquals(true, $filter->filter(true));
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testSettingFalseType()
+    {
+        try {
+            $this->_filter->setType(true);
+            $this->fail();
+        } catch (Zend_Exception $e) {
+            $this->assertContains('Unknown', $e->getMessage());
+        }
+    }
+
+    /**
+     * Ensures that the filter follows expected behavior
+     *
+     * @return void
+     */
+    public function testGetType()
+    {
+        $this->assertEquals(31, $this->_filter->getType());
+    }
+}