repo_zf1/documentation/manual/de/ref/migration-17.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="migration.17">
    <title>Zend Framework 1.7</title>

    <para>
        Wenn man von einem älteren Release auf Zend Framework 1.7 oder höher hochrüstet sollte
        man die folgenden Migrations Hinweise beachten.
    </para>

    <sect2 id="migration.17.zend.controller">
        <title>Zend_Controller</title>

        <sect3 id="migration.17.zend.controller.dispatcher">
            <title>Änderungen im Dispatcher Interface</title>

            <para>
                Benutzer haben uns darauf aufmerksam gemacht das
                <classname>Zend_Controller_Action_Helper_ViewRenderer</classname> Methoden auf der
                abstrakten Dispatcher Klasse verwendet hat die nicht im Dispatcher Interface waren.
                Die folgenden Methoden wurden hinzugefügt um sicherzustellen das eigene Dispatcher
                weiterhin mit den ausgelieferten Implementierungen funktionieren:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>formatModuleName()</methodname>: sollte verwendet werden um
                        einen rohen Controllernamen zu nehmen, wie den einen der in einem
                        Anfrageobjekt gepackt ist, und Ihn in einen richtigen Klassennamen zu
                        reformatieren den eine Klasse, die
                        <classname>Zend_Controller_Action</classname> erweitert, verwenden würde
                    </para>
                </listitem>
            </itemizedlist>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.file.transfer">
        <title>Zend_File_Transfer</title>

        <sect3 id="migration.17.zend.file.transfer.validators">
            <title>Änderungen bei der Verwendung von Filtern und Prüfungen</title>

            <para>
                Wie von Benutzern erwähnt, arbeiteten die Prüfungen von
                <classname>Zend_File_Transfer</classname> nicht in Verbindung mit
                <classname>Zend_Config</classname> zusammen, durch den Fakt das Sie keine benannten
                Arrays verwendet haben.
            </para>

            <para>
                Deswegen wurden alle Filter und Prüfungen für
                <classname>Zend_File_Transfer</classname> überarbeitet. Wärend die alten Signaturen
                weiterhin funktionieren, wurden sie als veraltet markiert, und werfen eine
                <acronym>PHP</acronym> Notiz mit der Aufforderung das zu beheben.
            </para>

            <para>
                Die folgende Liste zeigt die Änderungen und was für die richtige Verwendung der
                Parameter getan werden muß.
            </para>

            <sect4 id="migration.17.zend.file.transfer.validators.rename">
                <title>Filter: Rename</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Filter_File_Rename($oldfile, $newfile,
                                $overwrite)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Filter_File_Rename($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>source</emphasis> identisch mit
                            <varname>$oldfile</varname>, <emphasis>target</emphasis> identisch mit
                            <varname>$newfile</varname>, <emphasis>overwrite</emphasis> identisch
                            mit <varname>$overwrite</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.rename.example">
                    <title>Änderungen für den Rename Filter von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('/path/to/oldfile', '/path/to/newfile', true));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addFilter('Rename',
                   array('source' => '/path/to/oldfile',
                         'target' => '/path/to/newfile',
                         'overwrite' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.count">
                <title>Prüfung: Count</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Count($min, $max)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Count($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>min</emphasis> identisch mit
                            <varname>$min</varname>, <emphasis>max</emphasis> identisch mit
                            <varname>$max</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.count.example">
                    <title>Änderungen für die Count Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      array(2, 3));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Count',
                      false,
                      array('min' => 2,
                            'max' => 3));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.extension">
                <title>Prüfung: Extension</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Extension($extension, $case)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Extension($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>*</emphasis> identisch mit
                            <varname>$extension</varname> und kann jeden anderen Schlüssel haben
                            <emphasis>case</emphasis> identisch mit <varname>$case</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.extension.example">
                    <title>Änderungen für die Extension Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                      array('jpg,gif,bmp', true));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Extension',
                      false,
                      array('extension1' => 'jpg,gif,bmp',
                            'case' => true));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.filessize">
                <title>Prüfung: FilesSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_FilesSize($min, $max,
                                $bytestring)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>min</emphasis> identisch mit
                            <varname>$min</varname>, <emphasis>max</emphasis> identisch mit
                            <varname>$max</varname>, <emphasis>bytestring</emphasis> identisch mit
                            <varname>$bytestring</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <para>
                    Zustätzlich wurde die Signatur der <methodname>useByteString()</methodname>
                    Methode geändert. Sie kann nur verwendet werden um zu testen ob die Prüfung
                    ByteStrings in den erzeugten Meldungen verwendet oder ncht. Um den Wert dieses
                    Flags zu setzen muß die <methodname>setUseByteString()</methodname> Methode
                    verwendet werden.
                </para>

                <example id="migration.17.zend.file.transfer.validators.filessize.example">
                    <title>Änderungen für die FilesSize Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      array(100, 10000, true));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));

// Beispiel für 1.6
$upload->useByteString(true); // Flag setzen

// Gleiches Beispiel für 1.7
$upload->setUseByteSting(true); // Flag setzen
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.hash">
                <title>Prüfung: Hash</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Hash($hash, $algorithm)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Hash($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>*</emphasis> identisch mit
                            <varname>$hash</varname> und kann jeden anderen Schlüssel haben
                            <emphasis>algorithm</emphasis> identisch mit
                            <varname>$algorithm</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.hash.example">
                    <title>Änderungen für die Hash Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                      array('12345', 'md5'));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Hash',
                      false,
                      array('hash1' => '12345',
                            'algorithm' => 'md5'));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.imagesize">
                <title>Prüfung: ImageSize</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_ImageSize($minwidth, $minheight,
                                $maxwidth, $maxheight)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_FilesSize($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>minwidth</emphasis> identisch mit
                            <varname>$minwidth</varname>, <emphasis>maxwidth</emphasis> identisch
                            mit <varname>$maxwidth</varname>, <emphasis>minheight</emphasis>
                            identisch mit <varname>$minheight</varname>,
                            <emphasis>maxheight</emphasis> identisch mit
                            <varname>$maxheight</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.imagesize.example">
                    <title>Änderungen für die ImageSize Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      array(10, 10, 100, 100));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('ImageSize',
                      false,
                      array('minwidth' => 10,
                            'minheight' => 10,
                            'maxwidth' => 100,
                            'maxheight' => 100));
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.size">
                <title>Prüfung: Size</title>

                <itemizedlist>
                    <listitem>
                        <para>
                            Alte <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Size($min, $max,
                                $bytestring)</methodname>
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            Neue <acronym>API</acronym> der Methode:
                            <methodname>Zend_Validate_File_Size($options)</methodname> wobei
                            <varname>$options</varname> die folgenden Schlüssel für das Array
                            akzeptiert: <emphasis>min</emphasis> identisch mit
                            <varname>$min</varname>, <emphasis>max</emphasis> identisch mit
                            <varname>$max</varname>, <emphasis>bytestring</emphasis> identisch mit
                            <varname>$bytestring</varname>
                        </para>
                    </listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.size.example">
                    <title>Änderungen für die Size Prüfung von 1.6 zu 1.7</title>

                    <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      array(100, 10000, true));

// Gleiches Beispiel für 1.7
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('Size',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));
]]></programlisting>
                </example>
            </sect4>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.locale">
        <title>Zend_Locale</title>

        <sect3 id="migration.17.zend.locale.islocale">
            <title>Änderungen bei der Verwendung von isLocale()</title>

            <para>
                Bezugnehmend auf den Codingstandard mußte <methodname>isLocale()</methodname> so
                geändert werden das es ein Boolean zurückgibt. In vorhergehenden Releases wurde im
                Erfolgsfall ein String zurückgegeben. Für das Release 1.7 wurde ein
                Kompatibilitätsmodus hinzugefügt der es erlaubt das alte Verhalten, das ein String
                zurückgegeben wird, zu verwenden, aber das triggert auch eine User Warning die
                darauf hinweist das man auf das neue Verhalten wechseln sollte. Das Rerouting
                welches das alte Verhalten von <methodname>isLocale()</methodname> durchgeführt
                hätte ist nicht länger notwendig, da alle I18n Komponenten jetzt das Rerouting
                selbst durchführen.
            </para>

            <para>
                Um die Skripte auf die neue <acronym>API</acronym> zu migrieren muß die Methode
                einfach wie anbei gezeigt verwendet werden.
            </para>

            <example id="migration.17.zend.locale.islocale.example">
                <title>Wie man isLocale() von 1.6 nach 1.7 ändern muß</title>

                <programlisting language="php"><![CDATA[
// Beispiel für 1.6
if ($locale = Zend_Locale::isLocale($locale)) {
    // mach was
}

// Selbes Beispiel für 1.7

// Man sollte den Kompatibilitätsmodus ändern um User Warnings zu verhindern
// Aber man kann das in der Bootstrap tun
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale)) {
}
]]></programlisting>

                <para>
                    Es ist zu beachten das man den zweiten Parameter verwendet kann um zu sehen ob
                    das Gebietsschema richtig ist ohne das ein Rerouting durchgeführt wird.
                </para>

                <programlisting language="php"><![CDATA[
// Beispiel für 1.6
if ($locale = Zend_Locale::isLocale($locale, false)) {
    // mach was
}

// Selbes Beispiel für 1.7

// Man sollte den Kompatibilitätsmodus ändern um User Warnings zu verhindern
// Aber man kann das in der Bootstrap tun
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale, false)) {
    if (Zend_Locale::isLocale($locale, true)) {
        // gar kein Gebietsschema
    }

    // Original String ist kein Gebietsschema, kann aber Reroutet werden
}
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="migration.17.zend.locale.islocale.getdefault">
            <title>Änderungen bei der Verwendung von getDefault()</title>

            <para>
                Die Bedeutung der <methodname>getDefault()</methodname> Methode wurde verändert
                durch den Fakt das Framework-weite Gebietsschemata integriert wurden welche mit
                <methodname>setDefault()</methodname> gesetzt werden können. Deswegen gibe es nicht
                mehr die Kette der Gebietsschemata zurück sondern nur die gesetzten Framework-weiten
                Gebietsschemata.
            </para>

            <para>
                Um die eigenen Skripte auf die neue <acronym>API</acronym> zu migrieren, muß einfach
                die Methode wie unten gezeigt verwendet werden.
            </para>

            <example id="migration.17.zend.locale.getdefault.example">
                <title>Wie man getDefault() von 1.6 auf 1.7 ändert</title>

                <programlisting language="php"><![CDATA[
// Beispiel für 1.6
$locales = $locale->getDefault(Zend_Locale::BROWSER);

// Selbes Beispiel für 1.7

// Man sollte den Compatibility Mode setzen um User Notices zu verhindern
// Das kann in der Bootstrap Datei getan werden
Zend_Locale::$compatibilityMode = false;

$locale = Zend_Locale::getOrder(Zend_Locale::BROWSER);
]]></programlisting>

                <para>
                    Es ist zu beachten das der zweite Parameter der alten
                    <methodname>getDefault()</methodname> Implementation nicht mehr vorhanden ist,
                    aber die zurückgegebenen Werte die gleichen sind.
                </para>
            </example>

            <note>
                <para>
                    Standardmäßig ist das alte Verhalten noch immer aktiv, wirft aber eine User
                    Notice. Wenn man den eigenen Code zum neuen Verhalten geändert hat sollte man
                    auch den Compatibility Mode auf <constant>FALSE</constant> setzen damit keine
                    Notices mehr geworfen werden.
                </para>
            </note>
         </sect3>
    </sect2>

    <sect2 id="migration.17.zend.translate">
        <title>Zend_Translate</title>

        <sect3 id="migration.17.zend.translate.languages">
            <title>Setzen von Sprachen</title>

            <para>
                Wenn man die automatische Erkennung von Sprachen verwendet, oder Sprachen manuell
                auf <classname>Zend_Translate</classname> setzt kann es sein das man von Zeit zu
                Zeit eine Notiz geworfen bekommen die über nicht hinzugefügte oder leere
                Übersetzungen schreibt. In einigen vorhergehenden Releases wurde in einigen Fällen
                auch eine Exception geworfen.
            </para>

            <para>
                Der Grund ist, das wenn ein Benutzer eine nicht existierende Sprache anfragt, man
                einfach keinen Weg hat um festzustellen was falsch ist. Deswegen haben wir diese
                Notizen hinzugefügt die einem in den eigenen Logs zeigen das der Benutzer eine
                Sprache angefragt hat die man nicht unterstützt. Es ist zu beachten das der Code,
                selbst wenn eine Notiz getriggert wird, weiterhin ohne Probleme arbeitet.
            </para>

            <para>
                Aber wenn man einen eigenen Fehler oder Exception Handler, wie XDebug, verwendet
                wird man alle Notizen zurückerhalten, selbst wenn man das nicht gewollt hat. Das ist
                der Fall, weil diese Handler alle Einstellungen von <acronym>PHP</acronym> selbst
                überschreiben.
            </para>

            <para>
                Um diese Notizen wegzubekommen kann man einfach die neue Option 'disableNotices' auf
                <constant>TRUE</constant> setzen. Der Standardwert ist <constant>FALSE</constant>.
            </para>

            <example id="migration.17.zend.translate.example">
                <title>Setzen von Sprachen ohne das man Notizen erhält</title>

                <para>
                    Nehmen wir an das wir 'en' vorhanden haben und unser Benutzer 'fr' anfragt was
                    nicht in unserem Portfolio der übersetzten Sprachen ist.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto');
]]></programlisting>

                <para>
                    In diesem Fall werden wir eine Notiz darüber erhalten das die Sprache 'fr' nicht
                    vorhanden ist. Durch das einfache Hinzufügen der Option wird die Notiz
                    abgeschaltet.
                </para>

                <programlisting language="php"><![CDATA[
$language = new Zend_Translate('gettext',
                               '/path/to/translations',
                               'auto',
                               array('disableNotices' => true));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="migration.17.zend.view">
        <title>Zend_View</title>

        <note>
            <para>
                Die Änderung der <acronym>API</acronym> in <classname>Zend_View</classname> sind nur
                dann zu beachten wenn man zum Release 1.7.5 oder höher hochrüstet.
            </para>
        </note>

        <para>
            Vor dem 1.7.5 Release wurde das Zend Framework Team darauf aufmerksam gemacht das eine
            potentielle Local File Inclusion (<acronym>LFI</acronym>) Schwäche in der
            <methodname>Zend_View::render()</methodname> Methode existiert. Vor 1.7.5, erlaubte die
            Methode standardmäßig, die Fähigkeit View Skripte zu spezifizieren die Schreibweisen für
            Eltern-Verzeichnisse enthalten (z.B. "../" oder "..\"). Das öffnet die Möglichkeit für
            eine <acronym>LFI</acronym> Attacke wenn ungefilterte Benutzereingaben an die
            <methodname>render()</methodname> Methode übergeben werden:
        </para>

        <programlisting language="php"><![CDATA[
// Wobei $_GET['foobar'] = '../../../../etc/passwd'
echo $view->render($_GET['foobar']); // LFI Einbruch
]]></programlisting>

        <para>
            <classname>Zend_View</classname> wirft jetzt standardmäßig eine Ausnahme wenn so ein
            View Skript angefragt wird.
        </para>

        <sect3 id="migration.17.zend.view.disabling">
            <title>Ausschalten des LFI Schutzes für die render() Methode</title>

            <para>
                Da viele Entwickler gemeldet haben das Sie so eine Schreibweise in Ihren
                Anwendungen verwenden die <emphasis>nicht</emphasis> das Ergebnis einer
                Benutzereingabe sind, wurde ein spezielles Flag erstellt um das Deaktivieren des
                standardmäßigen Schutzes zu erlauben. Es gibt 2 Methoden um das Durchzuführen:
                Indem der 'lfiProtectionOn' Schlüssel in den Konstruktor-Optionen übergeben wird,
                oder durch den expliziten Aufruf der <methodname>setLfiProtection()</methodname>
                Methode.
            </para>

            <programlisting language="php"><![CDATA[
// Ausschalten über den Konstruktor
$view = new Zend_View(array('lfiProtectionOn' => false));

// Ausschalten über expliziten Aufruf der Methode:
$view = new Zend_View();
$view->setLfiProtection(false);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>