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

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

    <para>
        以前のバージョンから Zend Framework 1.7 またはそれ以降に更新する際は、
        下記の移行上の注意点に注意すべきです。
    </para>

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

        <sect3 id="migration.17.zend.controller.dispatcher">
            <title>ディスパッチャインターフェイスの変更</title>

            <para>
                ユーザからの指摘により、
                <classname>Zend_Controller_Action_Helper_ViewRenderer</classname>
                が使っているディスパッチャ抽象クラスのメソッドの中で
                ディスパッチャインターフェイスに存在しないものがあることに気づきました。
                次のメソッドを追加し、
                自作のディスパッチャが同梱の実装と共存できるようにしています。
            </para>

            <itemizedlist>
                <listitem><para>
                    <methodname>formatModuleName()</methodname>:
                リクエストオブジェクト内に格納されたりしている生のコントローラ名を受け取り、
                それを再フォーマットして
                <classname>Zend_Controller_Action</classname> を継承した適切なクラス名にします。
                </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>フィルタやバリデータを使用する際の変更点</title>

            <para>
                <classname>Zend_File_Transfer</classname> のバリデータが
                <classname>Zend_Config</classname> と組み合わせて使えないという指摘がありました。
                名前つき配列を使っていなかったからです。
            </para>

            <para>
                そこで、<classname>Zend_File_Transfer</classname> 用のすべてのフィルタとバリデータを作り直しました。
                古い構文でも動作しますがこれは非推奨となり、
                設定せずに実行すると <acronym>PHP</acronym> の notice が発生するようになります。
            </para>

            <para>
                次のリストは、パラメータの使用法に関する変更点をまとめたものです。
            </para>

            <sect4 id="migration.17.zend.file.transfer.validators.rename">
                <title>Rename フィルタ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Filter_File_Rename($oldfile, $newfile, $overwrite)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Filter_File_Rename($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>source</emphasis> (<varname>$oldfile</varname> と同等)、
                        <emphasis>target</emphasis> (<varname>$newfile</varname> と同等)、
                        <emphasis>overwrite</emphasis> (<varname>$overwrite</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.rename.example">
                    <title>rename フィルタの 1.6 から 1.7 での変更点</title>

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

// 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>Count バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_Count($min, $max)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_Count($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>min</emphasis> (<varname>$min</varname> と同等)、
                        <emphasis>max</emphasis> (<varname>$max</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.count.example">
                    <title>count バリデータの 1.6 から 1.7 での変更点</title>

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

// 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>Extension バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_Extension($extension, $case)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_Extension($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>*</emphasis> (<varname>$extension</varname> と同等、任意の他のキーを使用可能)、
                        <emphasis>case</emphasis> (<varname>$case</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.extension.example">
                    <title>extension バリデータの 1.6 から 1.7 での変更点</title>

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

// 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>FilesSize バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_FilesSize($min, $max, $bytestring)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_FilesSize($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>min</emphasis> (<varname>$min</varname> と同等)、
                        <emphasis>max</emphasis> (<varname>$max</varname> と同等)、
                        <emphasis>bytestring</emphasis> (<varname>$bytestring</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <para>
                    さらに <methodname>useByteString()</methodname> メソッドのシグネチャも変わりました。
                    このメソッドの使用法は、
                    そのバリデータが生成するメッセージでバイト文字列を使うことを想定しているかどうかを調べるだけになりました。
                    フラグの値を設定するには
                    <methodname>setUseByteString()</methodname> メソッドを使用します。
                </para>

                <example id="migration.17.zend.file.transfer.validators.filessize.example">
                    <title>filessize バリデータの 1.6 から 1.7 での変更点</title>

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

// 1.7 の例
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize',
                      false,
                      array('min' => 100,
                            'max' => 10000,
                            'bytestring' => true));

// 1.6 の例
$upload->useByteString(true); // set flag

// 1.7 の例
$upload->setUseByteSting(true); // set flag
]]></programlisting>
                </example>
            </sect4>

            <sect4 id="migration.17.zend.file.transfer.validators.hash">
                <title>Hash バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_Hash($hash, $algorithm)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_Hash($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>*</emphasis> (<varname>$hash</varname> と同等、任意の他のキーを使用可能)、
                        <emphasis>algorithm</emphasis> (<varname>$algorithm</varname> と同等)、
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.hash.example">
                    <title>hash バリデータの 1.6 から 1.7 での変更点</title>

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

// 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>ImageSize バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_ImageSize($minwidth, $minheight, $maxwidth, $maxheight)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_FilesSize($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>minwidth</emphasis> (<varname>$minwidth</varname> と同等)、
                        <emphasis>maxwidth</emphasis> (<varname>$maxwidth</varname> と同等)、
                        <emphasis>minheight</emphasis> (<varname>$minheight</varname> と同等)、
                        <emphasis>maxheight</emphasis> (<varname>$maxheight</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.imagesize.example">
                    <title>imagesize バリデータの 1.6 から 1.7 での変更点</title>

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

// 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>Size バリデータ</title>

                <itemizedlist>
                    <listitem><para>
                        古い形式の <acronym>API</acronym>: <command>Zend_Validate_File_Size($min, $max, $bytestring)</command>
                    </para></listitem>

                    <listitem><para>
                        新しい形式の <acronym>API</acronym>: <command>Zend_Validate_File_Size($options)</command>
                        <varname>$options</varname> には次の配列キーを使えます。
                        <emphasis>min</emphasis> (<varname>$min</varname> と同等)、
                        <emphasis>max</emphasis> (<varname>$max</varname> と同等)、
                        <emphasis>bytestring</emphasis> (<varname>$bytestring</varname> と同等)
                    </para></listitem>
                </itemizedlist>

                <example id="migration.17.zend.file.transfer.validators.size.example">
                    <title>size バリデータの 1.6 から 1.7 での変更点</title>

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

// 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>isLocale() を使う際の変更点</title>

            <para>
                コーディング規約に従うと、 <methodname>isLocale()</methodname> は boolean
                値を返さなければなりませんでした。
                以前のバージョンでは、成功したばあいに文字列を返していました。
                リリース 1.7 では、互換性モードが追加されて文字列を返す古い挙動も使えます。
                しかし、このばあいは新しい挙動に変更するようにというユーザ警告が発生します。
                古い挙動の <methodname>isLocale()</methodname> が行っていた再ルーティングはもはや不要で、
                すべての I18N は自分自身で再ルーティングを行います。
            </para>

            <para>
                あなたのスクリプトを新しい <acronym>API</acronym> 用に変更するには、次のようにメソッドを使用します。
            </para>

            <example id="migration.17.zend.locale.islocale.example">
                <title>isLocale() を 1.6 用から 1.7 用に変更する方法</title>

                <programlisting language="php"><![CDATA[
// 1.6 の例
if ($locale = Zend_Locale::isLocale($locale)) {
    // ここで何かします
}

// 1.7 の例

// 互換性モードを変更して警告の発生を防ぐ必要があります
// これは起動ファイルで行うことができます
Zend_Locale::$compatibilityMode = false;

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

                <para>
                    2 番目のパラメータを使えば、
                    そのロケールが正しくて再ルーティングが発生しなかったかどうかがわかることに注意しましょう。
                </para>

                <programlisting language="php"><![CDATA[
// 1.6 の例
if ($locale = Zend_Locale::isLocale($locale, false)) {
    // ここで何かします
}

// 1.7 の例

// 互換性モードを変更して警告の発生を防ぐ必要があります
// これは起動ファイルで行うことができます
Zend_Locale::$compatibilityMode = false;

if (Zend_Locale::isLocale($locale, false)) {
    if (Zend_Locale::isLocale($locale, true)) {
        // ロケールはありません
    }

    // もとの文字列はロケールを持ちませんが再ルーティングできます
}
]]></programlisting>

            </example>
        </sect3>

        <sect3 id="migration.17.zend.locale.islocale.getdefault">
            <title>getDefault() を使用する際の変更</title>

            <para>
                <methodname>getDefault()</methodname> メソッドの意味が変わりました。
                フレームワークにロケールが統合され、それを <methodname>setDefault()</methodname>
                で設定できるようになったからです。
                このメソッドはもはやロケールチェインを返すことはなく、
                フレームワークのロケールに設定されたものだけを返します。
            </para>

            <para>
                あなたのスクリプトを新しい <acronym>API</acronym> 用に変更するには、次のようにメソッドを使用します。
            </para>

            <example id="migration.17.zend.locale.islocale.getdefault.example">
                <title>getDefault() を 1.6 用から 1.7 用に変更する方法</title>

                <programlisting language="php"><![CDATA[
// 1.6 の例
$locales = $locale->getDefault(Zend_Locale::BROWSER);

// 1.7 の例

// 互換性モードを変更して警告の発生を防ぐ必要があります
// これは起動ファイルで行うことができます
Zend_Locale::$compatibilityMode = false;

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

                <para>
                    古い実装における <methodname>getDefault()</methodname>
                    の 2 番目のパラメータはもはや使えないことに注意しましょう。
                    返り値がそれと同じ値となります。
                </para>
            </example>

            <note>
                <para>
                    デフォルトでは古い挙動も有効ですが、ユーザ警告が発生します。
                    新しい挙動にあわせてコードを変更し終えたら、
                    互換性モードを false に変更して警告が発生しないようにしなければなりません。
                </para>
            </note>
        </sect3>
    </sect2>

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

        <sect3 id="migration.17.zend.translate.languages">
            <title>言語の設定</title>

            <para>
                言語の自動検出を使用したり <classname>Zend_Translate</classname> に手動で言語を設定したりする際に、
                「追加に失敗」や「翻訳がない」などの理由で notice が発行されることがありました。
                以前のリリースでは、場合によっては例外が発生することもありました。
            </para>

            <para>
                その原因は、存在しない言語をユーザが指定した際に
                何が問題なのかを知る簡単な方法がなかったことにあります。
                そこで私たちは notice を発行させるようにしていたのです。
                ログに記録が残るので、サポートしていない言語がリクエストされたことがわかるようになります。
                そしてたとえ notice が発行されたとしても、コード自体は問題なく動作します。
            </para>

            <para>
                しかし、xdebug のような独自のエラーハンドラ/例外ハンドラを使った場合など、
                意図せぬものも含めてすべての notice を拾ってしまうこともあります。
                そういった独自のハンドラは <acronym>PHP</acronym> の設定を上書きしてしまうことがあるからです。
            </para>

            <para>
                これらの notice を発生させないようにするためには、新たなオプション
                'disableNotices' を true に設定するだけです。デフォルトは false となっています。
            </para>

            <example id="migration.17.zend.translate.example">
                <title>notice を取得せずに言語の設定を行う</title>

                <para>
                    ここでは、'en' に対応しているところにユーザから
                    'fr' がリクエストされたものと家庭します。この翻訳は登録されていません。
                </para>

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

                <para>
                    この場合、存在しない言語 'fr' が指定されたことに関する notice が発行されます。
                    オプションを追加すると、この notice は発生しなくなります。
                </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>
                <classname>Zend_View</classname> 内の API 変更は、
                リリース 1.7.5 またはそれ以降にアップグレードする際にだけ注意すべきです。
            </para>
        </note>

        <para>
            Zend Framework 開発陣は、1.7.5 より前のバージョンにおいて
            <methodname>Zend_View::render()</methodname> メソッドにローカルファイル読み込み
            (Local File Inclusion: LFI) 脆弱性の問題があることに気づきました。
            1.7.5 より前のバージョンでは、このメソッドはデフォルトで
            親ディレクトリを指す記法 ("../" や "..\")
            を含むビュースクリプトも指定できてしまいます。
            フィルタリングをしていないユーザ入力が <methodname>render()</methodname>
            メソッドに渡されると、LFI 攻撃を受ける可能性が出てきます。
        </para>

        <programlisting language="php"><![CDATA[
// $_GET['foobar'] = '../../../../etc/passwd' だったら……
echo $view->render($_GET['foobar']); // LFI
]]></programlisting>

        <para>
            <classname>Zend_View</classname> は、このようなビュースクリプトがリクエストされると
            デフォルトで例外を発生させるようになりました。
        </para>

        <sect3 id="migration.17.zend.view.disabling">
            <title>render() メソッドにおける LFI 保護機能の無効化</title>

            <para>
                多くの開発者から「ユーザの入力では<emphasis>ない</emphasis>
                場面で、意図的にこれらの記法を使っていることもある」という指摘を受けたため、
                特別なフラグを用意してデフォルトの保護機能を無効化できるようにしました。
                無効化する方法は二通りあります。コンストラクタのオプションで
                'lfiProtectionOn' キーを指定するか、あるいは
                <methodname>setLfiProtection()</methodname> メソッドをコールします。
            </para>

            <programlisting language="php"><![CDATA[
// コンストラクタでの無効化
$view = new Zend_View(array('lfiProtectionOn' => false));

// メソッドコールによる無効化
$view = new Zend_View();
$view->setLfiProtection(false);
]]></programlisting>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->