<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.filter.introduction">

    <title>導入</title>

    <para>
        <classname>Zend_Filter</classname> コンポーネントは、データのフィルタリングに必要となる一般的な機能を提供します。
        シンプルなフィルタチェイン機能も持っており、
        ひとつのデータに対して複数のフィルタを指定した順に適用できます。
    </para>

    <sect2 id="zend.filter.introduction.definition">

        <title>フィルタとは?</title>

        <para>
            自然界におけるフィルタの典型的な使用法は、
            入力から不要な部分を除去して必要なものだけを出力することです (例: コーヒーのフィルタ)。
            このような場合、フィルタは入力の一部を取り出すための演算子となります。
            この型のフィルタリングはウェブアプリケーションで有用です。
            たとえば不正な入力を除去したり、余分な空白を除去したりといったことが考えられます。
        </para>

        <para>
            この基本的なフィルタの定義を拡張して、入力に一般的な変換を加える処理もフィルタに含めることにしましょう。
            ウェブアプリケーションでよくある変換は、<acronym>HTML</acronym> エンティティのエスケープ処理です。
            たとえば (ウェブブラウザなどからの) 信頼できない入力をもとにして
            フォームのフィールドに値を自動的に埋め込む場合は、その値には
            <acronym>HTML</acronym> エンティティが含まれてはいけません。あるいはもし含むならそれをエスケープしておかなければなりません。
            これにより、予期せぬ振る舞いを起こすことを防ぎ、
            セキュリティ上の脆弱性も防ぎます。
            この要求を満たすには、入力に含まれる <acronym>HTML</acronym>
            エンティティを削除あるいはエスケープしなければなりません。
            もちろん、どちらの方式が適切かはその場の状況に依存します。
            <acronym>HTML</acronym> エンティティを除去するフィルタは、最初に定義したフィルタの考え方
            - 入力の一部を取り出すための演算子 - にもとづくものです。
            一方、<acronym>HTML</acronym> エンティティをエスケープするフィルタは、入力を変換するタイプのものです
            (たとえば "&amp;" は "&amp;amp;" に変換されます)。
            これらの例のような処理はウェブ開発者にとって重要です。
            <classname>Zend_Filter</classname> で "フィルタリングする" という場合、
            それは入力データに対して何らかの変換を行うことを意味します。
        </para>

    </sect2>

    <sect2 id="zend.filter.introduction.using">

        <title>フィルタの基本的な使用法</title>

        <para>
            ここで考えたフィルタについての定義をもとにして
            <classname>Zend_Filter_Interface</classname> が作成されました。
            これは、フィルタクラスに対して <methodname>filter()</methodname>
            という名前のメソッドを実装するよう強制するものです。
        </para>

        <para>
            以下の例は、アンパサンド (<emphasis>&amp;</emphasis>) およびダブルクォート (<emphasis>&quot;</emphasis>)
            の二つの入力データに対してフィルタを適用するものです。
        </para>

        <programlisting language="php"><![CDATA[
$htmlEntities = new Zend_Filter_HtmlEntities();

echo $htmlEntities->filter('&'); // &amp;
echo $htmlEntities->filter('"'); // &quot;
]]></programlisting>
    </sect2>

    <sect2 id="zend.filter.introduction.static">

        <title>静的メソッド staticFilter() の使用法</title>

        <para>
            指定したフィルタクラスを読み込んでそのインスタンスを作成するというのが面倒ならば、
            もうひとつの方法として、静的メソッド <methodname>Zend_Filter::filterStatic()</methodname>
            を実行する方法もあります。このメソッドの最初の引数には、
            <methodname>filter()</methodname> メソッドに渡す入力値を指定します。
            二番目の引数は文字列で、フィルタクラスのベースネーム
            (<classname>Zend_Filter</classname> 名前空間における相対的な名前) を指定します。
            <methodname>staticFilter()</methodname> メソッドは自動的にクラスを読み込んでそのインスタンスを作成し、
            指定した入力に対して <methodname>filter()</methodname> メソッドを適用します。
        </para>

        <programlisting language="php"><![CDATA[
echo Zend_Filter::filterStatic('&', 'HtmlEntities');
]]></programlisting>

        <para>
            フィルタクラスのコンストラクタにオプションを指定する必要がある場合は、
            それを配列で渡すことができます。
        </para>

        <programlisting language="php"><![CDATA[
echo Zend_Filter::filterStatic('"',
                               'HtmlEntities',
                               array('quotestyle' => ENT_QUOTES));
]]></programlisting>

        <para>
            この静的な使用法は、その場限りのフィルタリングには便利です。
            ただ、複数の入力に対してフィルタを適用するのなら、
            最初の例の方式、つまりフィルタオブジェクトのインスタンスを作成して
            その <methodname>filter()</methodname> メソッドをコールする方式のほうがより効率的です。
        </para>

        <para>
            また、<classname>Zend_Filter_Input</classname> クラスでも、特定の入力データのセットを処理する際に
            複数のフィルタやバリデータを必要に応じて実行させる機能も提供しています。
            詳細は <link linkend="zend.filter.input">Zend_Filter_Input</link> を参照ください。
        </para>

        <sect3 id="zend.filter.introduction.static.namespaces">

            <title>名前空間</title>

            <para>
                自分で定義したフィルタを使う際に、
                <methodname>Zend_Filter::filterStatic()</methodname> に
                4 番目のパラメータを指定できます。
                これは、フィルタを探すための名前空間となります。
            </para>

            <programlisting language="php"><![CDATA[
echo Zend_Filter::filterStatic(
    '"',
    'MyFilter',
    array($parameters),
    array('FirstNamespace', 'SecondNamespace')
);
]]></programlisting>

            <para>
                <classname>Zend_Filter</classname> には、名前空間をデフォルトで設定することもできます。
                つまり、起動時に一度設定しておけば
                <methodname>Zend_Filter::filterStatic()</methodname>
                のたびに指定する必要がなくなるということです。
                次のコード片は、上のコードと同じ意味となります。
            </para>

            <programlisting language="php"><![CDATA[
Zend_Filter::setDefaultNamespaces(array('FirstNamespace', 'SecondNamespace'));
echo Zend_Filter::filterStatic('"', 'MyFilter', array($parameters));
echo Zend_Filter::filterStatic('"', 'OtherFilter', array($parameters));
]]></programlisting>

            <para>
                名前空間の操作のために、次のような便利なメソッド群が用意されています。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::getDefaultNamespaces()</methodname></emphasis>:
                        設定されているすべての名前空間を配列で返します。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::setDefaultNamespaces()</methodname></emphasis>:
                        新たなデフォルト名前空間を設定し、既存の名前空間を上書きします。
                        単一の名前空間の場合は文字列、複数の場合は配列で指定できます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::addDefaultNamespaces()</methodname></emphasis>:
                        新たな名前空間を、既に設定されているものに追加します。
                        単一の名前空間の場合は文字列、複数の場合は配列で指定できます。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::hasDefaultNamespaces()</methodname></emphasis>:
                        デフォルトの名前空間が設定されている場合は <constant>TRUE</constant> 、
                        設定されていない場合は <constant>FALSE</constant> を返します。
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <!-- TODO : to be translated -->
    <sect2 id="zend.filter.introduction.caveats">
        <title>Double filtering</title>

        <para>
            When using two filters after each other you have to keep in mind that it is often not
            possible to get the original output by using the opposite filter. Take the following
            example:
        </para>

        <programlisting language="php"><![CDATA[
$original = "my_original_content";

// Attach a filter
$filter   = new Zend_Filter_Word_UnderscoreToCamelCase();
$filtered = $filter->filter($original);

// Use it's opposite
$filter2  = new Zend_Filter_Word_CamelCaseToUnderscore();
$filtered = $filter2->filter($filtered)
]]></programlisting>

        <para>
            The above code example could lead to the impression that you will get the original
            output after the second filter has been applied. But thinking logically this is not the
            case. After applying the first filter <emphasis>my_original_content</emphasis> will be
            changed to <emphasis>MyOriginalContent</emphasis>. But after applying the second filter
            the result is <emphasis>My_Original_Content</emphasis>.
        </para>

        <para>
            As you can see it is not always possible to get the original output by using a filter
            which seems to be the opposite. It depends on the filter and also on the given input.
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
