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

    <para>
        This filter allows you to use own methods in conjunction with
        <classname>Zend_Filter</classname>. You don't have to create a new filter when you already
        have a method which does the job.
    </para>

    <sect3 id="zend.filter.set.callback.options">
        <title>Supported options for Zend_Filter_Callback</title>

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

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>callback</property></emphasis>: This sets the callback
                    which should be used.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>options</property></emphasis>: This property sets the
                    options which are used when the callback is processed.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.filter.set.callback.basic">
        <title>Basic usage</title>

        <para>
            The usage of this filter is quite simple. Let's expect we want to create a filter which
            reverses a string.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_Callback('strrev');

print $filter->filter('Hello!');
// returns "!olleH"
]]></programlisting>

        <para>
            As you can see it's really simple to use a callback to define a own filter. It is also
            possible to use a method, which is defined within a class, by giving an array as
            callback.
        </para>

        <programlisting language="php"><![CDATA[
// Our classdefinition
class MyClass
{
    public function Reverse($param);
}

// The filter definition
$filter = new Zend_Filter_Callback(array('MyClass', 'Reverse'));
print $filter->filter('Hello!');
]]></programlisting>

        <para>
            To get the actual set callback use <methodname>getCallback()</methodname> and to set
            another callback use <methodname>setCallback()</methodname>.
        </para>

        <note>
            <title>Possible exceptions</title>

            <para>
                You should note that defining a callback method which can not be called will raise
                an exception.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.filter.set.callback.parameters">
        <title>Default parameters within a callback</title>

        <para>
            It is also possible to define default parameters, which are given to the called method
            as array when the filter is executed. This array will be concatenated with the value
            which will be filtered.
        </para>

        <programlisting language="php"><![CDATA[
$filter = new Zend_Filter_Callback(
    array(
        'callback' => 'MyMethod',
        'options'  => array('key' => 'param1', 'key2' => 'param2')
    )
);
$filter->filter(array('value' => 'Hello'));
]]></programlisting>

        <para>
            When you would call the above method definition manually it would look like this:
        </para>

        <programlisting language="php"><![CDATA[
$value = MyMethod('Hello', 'param1', 'param2');
]]></programlisting>
    </sect3>
</sect2>
