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

    <title>導入</title>

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

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

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

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

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

    </sect2>

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

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

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

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

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

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

        </para>

    </sect2>

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

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

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

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

        </para>

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

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

        </para>

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

        <para>
            また、Zend_Filter_Input クラスでも、特定の入力データのセットを処理する際に
            複数のフィルタやバリデータを必要に応じて実行させる機能も提供しています。
            詳細は <xref linkend="zend.filter.input" /> を参照ください。
        </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>:
                        デフォルトの名前空間が設定されている場合は true、
                        設定されていない場合は false を返します。
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
