<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.filter.set.boolean">
    <title>Boolean</title>

    <para>
        This filter changes a given input to be a <constant>BOOLEAN</constant> value. This is often
        useful when working with databases or when processing form values.
    </para>

    <sect3 id="zend.filter.set.boolean.options">
        <title>Supported options for Zend_Filter_Boolean</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>casting</property></emphasis>: When this option is set to
                    <constant>TRUE</constant> then any given input will be casted to boolean. This
                    option defaults to <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>locale</property></emphasis>: This option sets the locale
                    which will be used to detect localized input.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>type</property></emphasis>: The <property>type</property>
                    option sets the boolean type which should be used. Read the following for
                    details.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.filter.set.boolean.default">
        <title>Default behaviour for Zend_Filter_Boolean</title>

        <para>
            By default, this filter works by casting the input to a <constant>BOOLEAN</constant>
            value; in other words, it operates in a similar fashion to calling
            <command>(boolean) $value</command>.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_Boolean();
$value  = '';
$result = $filter->filter($value);
// returns false
]]></programlisting>

        <para>
            This means that without providing any configuration,
            <classname>Zend_Filter_Boolean</classname> accepts all input types and returns a
            <constant>BOOLEAN</constant> just as you would get by type casting to
            <constant>BOOLEAN</constant>.
        </para>
    </sect3>

    <sect3 id="zend.filter.set.boolean.types">
        <title>Changing behaviour for Zend_Filter_Boolean</title>

        <para>
            Sometimes casting with <command>(boolean)</command> will not suffice.
            <classname>Zend_Filter_Boolean</classname> allows you to configure specific types to
            convert, as well as which to omit.
        </para>

        <para>
            The following types can be handled:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>boolean</emphasis>: Returns a boolean value as is.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>integer</emphasis>: Converts an integer <emphasis>0</emphasis> value
                    to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>float</emphasis>: Converts a float <emphasis>0.0</emphasis> value
                    to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>string</emphasis>: Converts an empty string <emphasis>''</emphasis> to
                    <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>zero</emphasis>: Converts a string containing the single character
                    zero (<emphasis>'0'</emphasis>) to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>empty_array</emphasis>: Converts an empty <emphasis>array</emphasis>
                    to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>null</emphasis>: Converts a <constant>NULL</constant> value
                    to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>php</emphasis>: Converts values according to <acronym>PHP</acronym>
                    when casting them to <constant>BOOLEAN</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>false_string</emphasis>: Converts a string containing the word "false"
                    to a boolean <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>yes</emphasis>: Converts a localized string which contains the word
                    "no" to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>all</emphasis>: Converts all above types to
                    <constant>BOOLEAN</constant>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            All other given values will return <constant>TRUE</constant> by default.
        </para>

        <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 0 to false
$filter = new Zend_Filter_Boolean(Zend_Filter_Boolean::INTEGER);

// converts 0 and '0' to false
$filter = new Zend_Filter_Boolean(
    Zend_Filter_Boolean::INTEGER + Zend_Filter_Boolean::ZERO
);

// converts 0 and '0' to false
$filter = new Zend_Filter_Boolean(array(
    'type' => array(
        Zend_Filter_Boolean::INTEGER,
        Zend_Filter_Boolean::ZERO,
    ),
));

// converts 0 and '0' to false
$filter = new Zend_Filter_Boolean(array(
    'type' => array(
        'integer',
        'zero',
    ),
));
]]></programlisting>

        <para>
            You can also give an instance of <classname>Zend_Config</classname> to set the desired
            types. To set types after instantiation, use the <methodname>setType()</methodname>
            method.
        </para>
    </sect3>

    <sect3 id="zend.filter.set.boolean.localized">
        <title>Localized booleans</title>

        <para>
            As mentioned previously, <classname>Zend_Filter_Boolean</classname> can also recognise
            localized "yes" and "no" strings. This means that you can ask your customer in a form
            for "yes" or "no" within his native language and
            <classname>Zend_Filter_Boolean</classname> will convert the response to the appropriate
            boolean value.
        </para>

        <para>
            To set the desired locale, you can either use the <property>locale</property> option, or
            the method <methodname>setLocale()</methodname>.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_Boolean(array(
    'type'   => Zend_Filter_Boolean::ALL,
    'locale' => 'de',
));

// returns false
echo $filter->filter('nein');

$filter->setLocale('en');

// returns true
$filter->filter('yes');
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.boolean.casting">
        <title>Disable casting</title>

        <para>
            Sometimes it is necessary to recognise only <constant>TRUE</constant> or
            <constant>FALSE</constant> and return all other values without changes.
            <classname>Zend_Filter_Boolean</classname> allows you to do this by setting the
            <property>casting</property> option to <constant>FALSE</constant>.
        </para>

        <para>
            In this case <classname>Zend_Filter_Boolean</classname> will work as described in the
            following table, which shows which values return <constant>TRUE</constant> or
            <constant>FALSE</constant>. All other given values are returned without change when
            <property>casting</property> is set to <constant>FALSE</constant>
        </para>

        <table id="zend.filter.set.boolean.casting.table">
            <title>Usage without casting</title>
            <tgroup cols="3">
                <thead>
                    <row>
                        <entry>Type</entry>
                        <entry>True</entry>
                        <entry>False</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><constant>Zend_Filter_Boolean::BOOLEAN</constant></entry>
                        <entry><constant>TRUE</constant></entry>
                        <entry><constant>FALSE</constant></entry>
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::INTEGER</constant></entry>
                        <entry>0</entry>
                        <entry>1</entry>
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::FLOAT</constant></entry>
                        <entry>0.0</entry>
                        <entry>1.0</entry>
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::STRING</constant></entry>
                        <entry>""</entry>
                        <entry />
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::ZERO</constant></entry>
                        <entry>"0"</entry>
                        <entry>"1"</entry>
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::EMPTY_ARRAY</constant></entry>
                        <entry><methodname>array()</methodname></entry>
                        <entry />
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::NULL</constant></entry>
                        <entry><constant>NULL</constant></entry>
                        <entry />
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::FALSE_STRING</constant></entry>
                        <entry>"false" (case independently)</entry>
                        <entry>"true" (case independently)</entry>
                    </row>

                    <row>
                        <entry><constant>Zend_Filter_Boolean::YES</constant></entry>
                        <entry>localized "yes" (case independently)</entry>
                        <entry>localized "no" (case independently)</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            The following example shows the behaviour when changing the <property>casting</property>
            option:
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_Boolean(array(
    'type'    => Zend_Filter_Boolean::ALL,
    'casting' => false,
));

// returns false
echo $filter->filter(0);

// returns true
echo $filter->filter(1);

// returns the value
echo $filter->filter(2);
]]></programlisting>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->
