<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15207 -->
<!-- Reviewed: no -->
<sect1 id="zend.file.transfer.filters">

    <title>Filter für Zend_File_Transfer</title>

    <para>
        <classname>Zend_File_Transfer</classname> wird mit verschiedenen Datei bezogenen Filtern ausgeliefert die
        verwendet werden können um verschiedene Arbeiten die oft auf Dateien angewendet werden zu automatisieren.
        Es ist zu beachten das Dateifilter nach der Validierung angewendet werden. Dateifilter verhlaten sich
        auch etwas anders als andere Filter. Sie geben immer den Dateinamen zurück, und nicht den
        geänderten Inhalt (was eine schlechte Idee wäre wenn auf 1GB Dateien gearbeitet wird). Alle Dateifilter
        welche mit <classname>Zend_File_Transfer</classname> angeboten werden können in der <classname>Zend_Filter</classname>
        Komponente gefunden werden und heißen <classname>Zend_Filter_File_*</classname>. Die folgenden Filter sind
        aktuell vorhanden:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <code>Decrypt</code>: Dieser Filter kann verschlüsselte Dateien entschlüsseln.
            </para>
        </listitem>
        <listitem>
            <para>
                <code>Encrypt</code>: Dieser Filter kann Dateien verschlüsseln.
            </para>
        </listitem>
        <listitem>
            <para>
                <code>LowerCase</code>: Dieser Filter kann den Inhalt einer Textdatei auf Kleinschreibung
                ändern.
            </para>
        </listitem>
        <listitem>
            <para>
                <code>Rename</code>: Dieser Filter kann Dateien umbenennen, den Ort ändern und sogar das
                Überschreiben von existierenden Dateien erzwingen.
            </para>
        </listitem>
        <listitem>
            <para>
                <code>UpperCase</code>: Dieser Filter kann den Inhalt einer Textdatei auf Großschreibung
                ändern.
            </para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.file.transfer.filters.usage">
        <title>Verwenden von Filtern mit Zend_File_Transfer</title>

        <para>
            Die Verwendung von Filtern ist sehr einfach. Es gibt verschiedene Methoden für das
            Hinzufügen und Manipulieren von Filtern.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>addFilter($filter, $options = null, $files = null)</code>: Fügt den
                    angegebenen Filter zu den Filterstapel hinzu (optional nur zu den Datei(en) die
                    spezifiziert wurden). <code>$filter</code> kann entweder eine aktuelle
                    Filterinstanz sein, oder ein Kurzname der den Filtertyp spezifiziert (z.B. 'Rename').
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>addFilters(array $filters, $files = null)</code>: Fügt die angegebenen
                    Filter zum Filterstapel hinzu. Jeder Eintrag kann entweder ein Filtertyp/-options
                    Paar sein, oder ein Array mit dem Schlüssel 'filter' das den Filter spezifiziert
                    (alle anderen Optionen werden als Optionen für die Instanzierung der Filter angenommen).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>setFilters(array $filters, $files = null)</code>: Überschreibt alle bestehenden
                    Filter mit den spezifizierten Filtern. Die Filter sollten der Syntax folgen die
                    für <code>addFilters()</code> definiert ist.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>hasFilter($name)</code>: Zeigt ob ein Filter registriert wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getFilter($name)</code>: Gibt einen vorher registrierten Filter zurück.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>getFilters($files = null)</code>: Gibt registrierte Filter zurück; wenn
                    <code>$files</code> übergeben wurde, werden die Filter für die betreffende Datei
                    oder das Set an Dateien zurückgegeben.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>removeFilter($name)</code>: Entfernt einen vorher registrierten Filter.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>clearFilters()</code>: Löscht alle registrierten Filter.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.filters.usage.example">
            <title>Filter zu einem Dateitransfer hinzufügen</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer();

// Setzt einen neuen Zielpfad
$upload->addFilter('Rename', 'C:\picture\uploads');

// Setzt einen neuen Zielpfad und überschreibt bestehende Dateien
$upload->addFilter('Rename',
                   array('target' => 'C:\picture\uploads',
                         'overwrite' => true));
]]></programlisting>
        </example>

        <example id="zend.file.transfer.filters.usage.exampletwo">
            <title>Filter auf eine einzelne Datei begrenzen</title>

            <para>
                <code>addFilter()</code>, <code>addFilters()</code>, und <code>setFilters()</code>
                akzeptieren ein endenes <code>$files</code> Argument. Dieses Argument kann verwendet werden
                um eine Datei oder ein Array von Dateien zu spezifizieren auf dem der angegebene Filter
                gesetzt werden soll.
            </para>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer();

// Setzt einen neuen Zielpfad und begrenzt Ihn auf 'file2'
$upload->addFilter('Rename', 'C:\picture\uploads', 'file2');
]]></programlisting>
        </example>

        <para>
            Generell sollte einfach die <code>addFilters()</code> Methode verwendet werden, welche mehrmals
            aufgerufen werden kann.
        </para>

        <example id="zend.file.transfer.filters.usage.examplemultiple">
            <title>Mehrere Filter hinzufügen</title>

            <para>
                Oft ist es einfacher <code>addFilter()</code> mehrere Male aufzurufen. Ein Aufruf für
                jeden Filter. Das erhöht auch die Lesbarkeit und macht den Code wartbarer. Da alle
                Methoden das Fluent-Interface implementieren können Aufrufe einfach wie anbei gezeigt
                gekoppelt werden:
            </para>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer();

// Setzt mehrere Rename Filter
$upload->addFilter('Rename', 'C:\picture\newjpg', 'file1')
       ->addFilter('Rename', 'C:\picture\newgif', 'file2');
]]></programlisting>

        </example>

        <note>
            <para>
                Es ist zu beachten das, auch wenn das mehrfache Setzen des gleichen Filters erlaubt
                ist, das zu Problemen führen kann wenn verschiedene Optionen für den gleichen
                Filter verwendet werden.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.file.transfer.filters.decrypt">
        <title>Decrypt Filter</title>

        <para>
            Der <code>Decrypt</code> Filter erlaubt es verschlüsselte Dateien zu entschlüsseln.
        </para>

        <para>
            Dieser Filter verwendet <classname>Zend_Filter_Decrypt</classname>. Er unterstützt die Erweiterungen
            <code>Mcrypt</code> und <code>OpenSSL</code> von PHP. Lesen Sie bitte das betreffende Kapitel
            für Details darüber wie Optionen für die Entschlüsselung gesetzt werden können und welche
            Optionen unterstützt werden.
        </para>

        <para>
            Dieser Filter unterstützt eine zusätzliche Option die verwendet werden kann um die
            entschlüsselte Datei unter einem anderen Dateinamen zu speichern. Setze die <code>filename</code>
            Option um den Dateinamen zu ändern unter dem die entschlüsselte Datei abgespeichert wird.
            Wenn diese Option nicht angegeben wird, überschreibt die entschlüsselte Datei die verschlüsselte
            Originaldatei.
        </para>

        <example id="zend.file.transfer.filters.decrypt.example1">
            <title>Verwenden des Decrypt Filters mit Mcrypt</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();

// Fügt einen Filter hinzu um die hochgeladene verschlüsselte Datei
// mit Mcrypt und dem Schlüssel mykey zu entschlüsseln
// with mcrypt and the key mykey
$upload->addFilter('Decrypt',
    array('adapter' => 'mcrypt', 'key' => 'mykey'));
]]></programlisting>

        </example>

        <example id="zend.file.transfer.filters.decrypt.example2">
            <title>Verwenden des Decrypt Filters mit OpenSSL</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();

// Fügt einen Filter hinzu um die hochgeladene verschlüsselte Datei
// mit openssl und den angegebenen Schlüsseln zu entschlüseln
$upload->addFilter('Decrypt',
    array('adapter' => 'openssl',
          'private' => '/path/to/privatekey.pem',
          'envelope' => '/path/to/envelopekey.pem'));
]]></programlisting>

        </example>
    </sect2>

    <sect2 id="zend.file.transfer.filters.encrypt">
        <title>Encrypt Filter</title>

        <para>
            Der <code>Encrypt</code> Filter erlaubt es eine Datei zu verschlüsseln.
        </para>

        <para>
            Dieser Filter verwendet <classname>Zend_Filter_Encrypt</classname>. Er unterstützt die Erweiterungen
            <code>Mcrypt</code> und <code>OpenSSL</code> von PHP. Lesen Sie bitte das betreffende Kapitel
            für Details darüber wie Optionen für die Entschlüsselung gesetzt werden können und welche
            Optionen unterstützt werden.
        </para>

        <para>
            Dieser Filter unterstützt eine zusätzliche Option die verwendet werden kann um die
            verschlüsselte Datei unter einem anderen Dateinamen zu speichern. Setze die <code>filename</code>
            Option um den Dateinamen zu ändern unter dem die verschlüsselte Datei abgespeichert wird.
            Wenn diese Option nicht angegeben wird, überschreibt die verschlüsselte Datei die
            Originaldatei.
        </para>

        <example id="zend.file.transfer.filters.encrypt.example1">
            <title>Verwenden des Encrypt Filters mit Mcrypt</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();

// Fügt einen Filter hinzu um die hochgeladene Datei mit mcrypt
// und dem Schlüssel mykey zu verschlüsseln
$upload->addFilter('Encrypt',
    array('adapter' => 'mcrypt', 'key' => 'mykey'));
]]></programlisting>

        </example>

        <example id="zend.file.transfer.filters.encrypt.example2">
            <title>Verwenden des Encrypt Filters mit OpenSSL</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();

// Fügt einen Filter hinzu um die hochgeladene Datei mit openssl
// und den angegebenen Schlüsseln zu verschlüsseln
$upload->addFilter('Encrypt',
    array('adapter' => 'openssl',
          'public' => '/path/to/publickey.pem'));
]]></programlisting>

        </example>
    </sect2>

    <sect2 id="zend.file.transfer.filters.lowercase">
        <title>LowerCase Filter</title>

        <para>
            Der <code>LowerCase</code> Filter erlaubt es den Inhalt einer Datei auf Kleinschreibung zu ändern.
            Dieser Filter sollte nur mit Textdateien verwendet werden.
        </para>

        <para>
            Bei der Initialisierung kann ein String angegeben werden welcher dann als Kodierung verwendet
            wird. Oder man kann die <code>setEncoding()</code> Methode verwenden um Sie im Nachhinein zu
            setzen.
        </para>

        <example id="zend.file.transfer.filters.lowercase.example">
            <title>Verwenden des Lowercase Filters</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('MimeType', 'text');

// Fügt einen Filter hinzu der hochgeladene Textdateien
// auf Kleinschreibung ändert
$upload->addFilter('LowerCase');

// Fügt einen Filter hinzu um die hochgeladene Datei auf Kleinschreibung
// zu ändern aber nur für uploadfile1
$upload->addFilter('LowerCase', null, 'uploadfile1');

// Fügt einen Filter für die Kleinschreibung hinzu wobei die Kodierung
// auf ISO-8859-1 gesetzt wird
$upload->addFilter('LowerCase', 'ISO-8859-1');
]]></programlisting>

        </example>

        <note>
            <para>
                Da die Optionen für den LowerCase Filter optional sind muß man darauf achten das man als zweiten
                Parameter eine null (die Optionen) geben muß wenn man Ihn auf ein einzelnes Dateielement
                einschränken will.
            </para>
        </note>

    </sect2>

    <sect2 id="zend.file.transfer.filters.rename">
        <title>Rename Filter</title>

        <para>
            Der <code>Rename</code> Filter erlaubt es das Ziel des Uploads zu Ändern, den Dateinamen sowie
            bereits bestehende Dateien zu überschreiben. Er unterstützt die folgenden Optionen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>source</code>: Der Name und das Ziel der alten Datei welche umbenannt werden soll.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>target</code>: Das neue Verzeichnis, oder der Dateiname der Datei.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>overwrite</code>: Definiert ob die alte Datei von der neuen überschrieben wird wenn
                    diese bereits existiert. Der Standardwert ist false.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Zusätzlich kann die <code>setFile()</code> Methode verwendet werden um Dateien zu setzen, sie
            überschreibt alle vorher gesetzten Dateien, <code>addFile()</code> um eine neue Datei zu bereits
            bestehenden zu setzen, und <code>getFile()</code> um alle aktuell gesetzten Dateien zu erhalten.
            Um die Dinge zu vereinfachen, versteht dieser Filter verschiedene Schreibweisen und seine
            Methoden und der Contructor verstehen die gleichen Schreibweisen.
        </para>

        <example id="zend.file.transfer.filters.rename.example">
            <title>Verwenden des Rename Filters</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();

// Setzt einen neuen Zielpfad für alle Dateien
$upload->addFilter('Rename', 'C:\mypics\new');

// Setzt einen neuen Zielpfad nur für uploadfile1
$upload->addFilter('Rename', 'C:\mypics\newgifs', 'uploadfile1');
]]></programlisting>

        </example>

        <para>
            Man kann verschiedene Schreibweisen verwenden. Anbei ist eine Tabelle in der eine Beschreibung
            und der Hintergrund für die verschiedenen unterstützten Schreibweisen zu finden ist. Es ist zu
            beachten das, wenn man den Adapter oder das Form Element verwendet, man nicht alle beschriebenen
            Schreibweisen verwenden kann.
        </para>

        <table id="zend.file.transfer.filters.rename.notations">

            <title>Verschiedene Schreibweisen des Rename Filters und deren Bedeutung</title>

            <tgroup cols="2" align="left">
                <thead>
                    <row>
                        <entry>
                            Schreibweise
                        </entry>
                        <entry>
                            Beschreibung
                        </entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            addFile('C:\uploads')
                        </entry>
                        <entry>
                            Spezifiziert einen neuen Pfad für alle Dateien wenn der angegebene String ein
                            Verzeichnis ist. Es ist zu beachten das man eine Exception erhält wenn die Datei
                            bereits existiert, siehe den overwriting Parameter.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            addFile('C:\uploads\file.ext')
                        </entry>
                        <entry>
                            Spezifiziert einen neuen Pfad und Dateinamen für alle Dateien wenn der angegebene
                            String nicht als Verzeichnis erkannt wird. Es ist zu beachten das man eine
                            Exception erhält wenn die angegebene Datei bereits existiert, siehe den
                            overwriting Parameter.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            addFile(array('C:\uploads\file.ext', 'overwrite' => true))
                        </entry>
                        <entry>
                            Spezifiziert einen neuen Pfad und Dateinamen für alle Dateien wenn der angegebene
                            String nicht als Verzeichnis erkannt wird, und überschreibt alle existierenden
                            Dateien mit dem gleichen Zielnamen. Es ist zu beachten das man keine
                            Verständigung erhält das eine Datei überschrieben wurde.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            addFile(array('source' => 'C:\temp\uploads', 'target' => 'C:\uploads'))
                        </entry>
                        <entry>
                            Spezifiziert einen neuen Pfad für alle Dateien im alten Pfad wenn die angegebenen
                            Strings als Verzeichnis erkannt werden. Es ist zu beachten das man eine
                            Exception erhält wenn die Datei bereits exstiert, siehe den overwriting Parameter.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            addFile(array('source' => 'C:\temp\uploads', 'target' => 'C:\uploads', 'overwrite' => true))
                        </entry>
                        <entry>
                            Spezifiziert einen neuen Pfad für alle Dateien im alten Pfad wenn die angegebenen
                            Strings als Verzeichnis erkant werden und überschreibt alle existierenden Dateien
                            mit dem gleichen Zielnamen. Es ist zu beachten das man keine Benachrichtigung
                            erhält das eine Datei überschrieben wurde.
                        </entry>
                    </row>
                </tbody>
            </tgroup>

        </table>

    </sect2>

    <sect2 id="zend.file.transfer.filters.uppercase">
        <title>UpperCase Filter</title>

        <para>
            Der <code>UpperCase</code> Filter erlaubt es den Inhalt einer Datei auf Großschreibung zu ändern.
            Dieser Filter sollte nur mit Textdateien verwendet werden.
        </para>

        <para>
            Bei der Initialisierung kann ein String angegeben werden welcher dann als Kodierung verwendet
            wird. Oder man kann die <code>setEncoding()</code> Methode verwenden um Sie im Nachhinein zu
            setzen.
        </para>

        <example id="zend.file.transfer.filters.uppercase.example">
            <title>Verwenden des UpperCase Filters</title>

            <programlisting role="php"><![CDATA[
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('MimeType', 'text');

// Fügt einen Filter hinzu um die hochgeladene Textdatei auf
// Großschreibung zu ändern
$upload->addFilter('UpperCase');

// Fügt einen Filter hinzu um die hochgeladene Datei auf Großschreibung
// zu ändern aber nur für uploadfile1
$upload->addFilter('UpperCase', null, 'uploadfile1');

// Fügt einen Filter für die Großschreibung hinzu wobei die Kodierung
// auf ISO-8859-1 gesetzt wird
$upload->addFilter('UpperCase', 'ISO-8859-1');
]]></programlisting>

        </example>

        <note>
            <para>
                Da die Optionen für den UpperCase Filter optional sind muß man darauf achten das man als zweiten
                Parameter eine null (die Optionen) geben muß wenn man Ihn auf ein einzelnes Dateielement
                einschränken will.
            </para>
        </note>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->
