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

    <para>
        Die <classname>Zend_Filter</classname> Komponente bietet ein Set von normalerweise benötigen
        Datenfiltern. Sie bietet auch einen einfachen Filterketten Mechanismus mit dem mehrere
        Filter bei einem einfachen Wert in einer benutzerdefinierten Reihenfolge ausgeführt werden
        können.
    </para>

    <sect2 id="zend.filter.introduction.definition">
        <title>Was ist ein Filter?</title>

        <para>
            In der physikalischen Welt wird ein Filter typischerweise für das entfernen von
            unerwünschten Teilen einer Eingabe verwendet, und der gewünschte Teil der Eingabe wird
            zur Ausgabe des Filters weitergeleitet (z.B. Kaffee). In solchen Szenarien ist ein
            Filter ein Operator der ein Subset von der Eingabe produziert. Diese Art des Filterns
            ist für Web Anwendungen nützlich - entfernen illegaler Eingaben, trimmen von unnötigen
            Leerzeichen, usw.
        </para>

        <para>
            Diese Basisdefinition eines Filter kann erweitert werden um generelle Umwandlungen über
            eine Eingabe zu beinhalten. Eine übliche Umwandlung die in Web Anwendungen durchgeführt
            wird, ist das auskommentieren von <acronym>HTML</acronym> Entititäten. Zum Beispiel,
            wenn ein Formular Feld automatisch mit einer unsicheren Eingabe übergeben wird (z.B. von
            einem Web Browser), sollte dieser Wert entweder frei von <acronym>HTML</acronym>
            Entititäten sein oder nur auskommentierte <acronym>HTML</acronym> Entititäten enthalten,
            um unerwünschtes Verhalten und Sicherheitslöcher zu vermeiden. Um diesen Anforderungen
            gerecht zu werden müssen <acronym>HTML</acronym> Entititäten die in der Eingabe
            vorkommen entweder entfernt oder auskommentiert werden. Natürlich hängt es von der
            Situation ab welcher Weg mehr zutrifft. Ein Filter der <acronym>HTML</acronym>
            Entititäten entfernt operiert innerhalb der Beschreibung der ersten Definition von
            Filter - ein Operator der ein Subset von einer Eingabe produziert. Ein Filter der
            <acronym>HTML</acronym> Entititäten auskommentiert, wandelt die Eingabe um (z.B. "&amp;"
            wird umgewandelt in "&amp;amp;"). Solche Fälle zu unterstützen ist für Web Entwickler
            sehr wichtig und "zu filtern", im Kontext der Verwendung von
            <classname>Zend_Filter</classname>, bedeutet einige Umwandlungen über Eingabedaten
            durchzuführen.
        </para>
    </sect2>

    <sect2 id="zend.filter.introduction.using">
        <title>Normale Verwendung von Filtern</title>

        <para>
            Diese Filterdefinition bekanntgegeben zu haben bietet die Grundlage für
            <classname>Zend_Filter_Interface</classname>, welches eine einzelne Methode benötigt
            die <methodname>filter()</methodname> genannt wird, und von der Filterklasse
            implementiert werden muß.
        </para>

        <para>
            Nachfolgend ist ein grundsätzliches Beispiel der Verwendung eines Filters über zwei
            Eingabedaten, einem Und-Zeichen (<emphasis>&amp;</emphasis>) und einem Hochkommazeichen
            (<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>Verwenden der statischen staticFilter() Methode</title>

        <para>
            Wenn es unbequem ist einen gegebene Filterklasse zu Laden und eine Instanz des Filters
            zu erstellen, kann die statische <methodname>Zend_Filter::staticFilter()</methodname>
            Methode als alternativer Aufrufstil verwendet werden. Das erste Argument dieser Methode
            ist der Eingabewert, der die <methodname>filter()</methodname> Methode passieren soll.
            Das zweite Argument ist ein String, der dem Basisnamen der Filterklasse, relativ zum
            <classname>Zend_Filter</classname> Namensraum, entspricht. Die
            <methodname>filterStatic()</methodname> Methode lädt die Klasse automatisch, erstellt
            eine Instanz, und führt die Eingabedaten der <methodname>filter()</methodname> Methode
            zu.
        </para>

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

        <para>
            Es kann auch ein Array von Konstruktor Argumenten übergeben werden, wen diese für die
            Filterklasse benötigt werden.
        </para>

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

        <para>
            Die statische Verwendung kann für das Ad-Hoc aufrufen von Filtern bequem sein, aber wenn
            man einen Filter über mehrere Eingaben anwenden will ist es effizienter den ersten
            Beispiel von oben zu folgen, eine Instanz des Filter Objekts zu erstellen und dessen
            <methodname>filter()</methodname> Methode aufzurufen.
        </para>

        <para>
            Die <classname>Zend_Filter_Input</classname> Klasse erlaubt es also, mehrere Filter zu
            instanzieren und auszurufen, und wenn benötigt, den Prüfklassen diese Sets von
            Eingabedaten zu verarbeiten. Siehe <link
                linkend="zend.filter.input">Zend_Filter_Input</link>.
        </para>

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

            <para>
                Wenn man mit selbst definierten Filtern arbeitet, dann kann man an
                <methodname>Zend_Filter::filterStatic()</methodname> einen vierten Parameter
                übergeben welcher der Namespace ist, an dem der eigene Filter gefunden werden kann.
            </para>

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

            <para>
                <classname>Zend_Filter</classname> erlaubt es auch standardmäßige Namespaces zu
                setzen. Das bedeutet das man Sie einmal in der Bootstrap setzt und sie nicht mehr
                bei jedem Aufruf von <methodname>Zend_Filter::filterStatic()</methodname> angeben
                muß. Der folgende Codeschnipsel ist identisch mit dem vorherigen.
            </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>
                Der Bequemlichkeit halber gibt es die folgenden Methoden welche die Behandlung von
                Namespaces erlauben:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::getDefaultNamespaces()</methodname></emphasis>:
                        Gibt alle standardmäßigen Namespaces als Array zurück.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::setDefaultNamespaces()</methodname></emphasis>:
                        Setzt neue standardmäßige Namespaces und überschreibt alle vorher
                        gesetzten. Es wird entweder ein String für einen einzelnen Namespace
                        akzeptiert, oder ein Array für mehrere Namespaces.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::addDefaultNamespaces()</methodname></emphasis>:
                        Fügt zusätzliche Namespaces zu den bereits gesetzten hinzu. Es wird
                        entweder ein String für einen einzelnen Namespace akzeptiert, oder ein
                        Array für mehrere Namespaces.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis><methodname>Zend_Filter::hasDefaultNamespaces()</methodname></emphasis>:
                        Gibt <constant>TRUE</constant> zurück wenn ein oder mehrere standardmäßige
                        Namespaces gesetzt sind, und <constant>FALSE</constant> wenn keine
                        standardmäßigen Namespaces gesetzt sind.
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.introduction.caveats">
        <title>Doppelt filtern</title>

        <para>
            Wenn zwei Filter nacheinander verwendet werden muss man bedenken dass es oft nicht
            möglich ist die originale Ausgabe zu erhalten indem der gegensätzliche Filter verwendet
            wird. Nehmen wir das folgende Beispiel:
        </para>

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

// Einen Filter anwenden
$filter   = new Zend_Filter_Word_UnderscoreToCamelCase();
$filtered = $filter->filter($original);

// Sein gegenstück verwenden
$filter2  = new Zend_Filter_Word_CamelCaseToUnderscore();
$filtered = $filter2->filter($filtered)
]]></programlisting>

        <para>
            Das oben stehende Code Beispiel könnte zur Vermutung führen dass man die originale
            Ausgabe erhält nachdem der zweite Filter angewendet wurde. Aber bei logischer
            Betrachtung ist dies nicht der Fall. Nachdem der erste Filter angewendet wurde, wird
            <emphasis>my_original_content</emphasis> zu <emphasis>MyOriginalContent</emphasis>
            geändert. Aber nachdem der zweite Filter angewendet wurde ist das Ergebnis
            <emphasis>My_Original_Content</emphasis>.
        </para>

        <para>
            Wie man sieht ist es nicht immer möglich die originale Ausgabe zu erhalten indem ein
            Filter angewendet wird der das Gegenteil zu sein scheint. Das hängt vom Filter und auch
            von der angegebenen Inhalt ab.
        </para>
    </sect2>
</sect1>
