<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17618 -->
<!-- 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 verhalten 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). <varname>$filter</varname> 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 <methodname>addFilters()</methodname> definiert ist.
                </para>
            </listitem>

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

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

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

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

            <listitem>
                <para>
                    <methodname>clearFilters()</methodname>: 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 language="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>
                <methodname>addFilter()</methodname>, <methodname>addFilters()</methodname>, und
                <methodname>setFilters()</methodname> akzeptieren ein endenes
                <varname>$files</varname> 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 language="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 <methodname>addFilters()</methodname> 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 <methodname>addFilter()</methodname> 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 language="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 <acronym>PHP</acronym>.
            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 language="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 language="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 <acronym>PHP</acronym>.
            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 language="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 language="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 <methodname>setEncoding()</methodname> Methode
            verwenden um Sie im Nachhinein zu setzen.
        </para>

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

            <programlisting language="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 <methodname>setFile()</methodname> Methode verwendet werden um
            Dateien zu setzen, sie überschreibt alle vorher gesetzten Dateien,
            <methodname>addFile()</methodname> um eine neue Datei zu bereits bestehenden zu setzen,
            und <methodname>getFile()</methodname> 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 language="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>
                            <methodname>addFile('C:\uploads')</methodname>
                        </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>
                            <methodname>addFile('C:\uploads\file.ext')</methodname>
                        </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>
                            <methodname>addFile(array('C:\uploads\file.ext',
                                'overwrite' => true))</methodname>
                        </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>
                            <methodname>addFile(array('source' => 'C:\temp\uploads', 'target' =>
                                'C:\uploads'))</methodname>
                        </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>
                            <methodname>addFile(array('source' => 'C:\temp\uploads', 'target' =>
                                'C:\uploads', 'overwrite' => true))</methodname>
                        </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 <methodname>setEncoding()</methodname> Methode
            verwenden um Sie im Nachhinein zu setzen.
        </para>

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

            <programlisting language="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:
-->
