repo_zf1/documentation/manual/ja/module_specs/Zend_File_Transfer-Migration.xml

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

    <title>以前のバージョンからの移行</title>

    <para>
        <classname>Zend_File_Transfer</classname> の <acronym>API</acronym> は日々変わっています。
        <classname>Zend_File_Transfer</classname> やそのサブコンポーネントを
        初期のバージョンから使っている方は、以下のガイドラインに従ってスクリプトを変更し、
        新しい <acronym>API</acronym> にあわせましょう。
    </para>

    <sect2 id="zend.file.transfer.migration.fromonenineonetooneten">
        <title>1.9 から 1.10 以降への移行</title>
        <sect3 id="zend.file.transfer.migration.fromonenineonetooneten.mimetype">
            <title>MimeType の検証</title>

            <para>
                セキュリティ上の理由から、
                <classname>MimeType</classname>、<classname>ExcludeMimeType</classname>、
                <classname>IsCompressed</classname> および <classname>IsImage</classname>
                バリデータにおけるデフォルトのフォールバック機能を無効にしました。
                つまり、<emphasis>fileInfo</emphasis> 拡張モジュールあるいは
                <emphasis>magicMime</emphasis> 拡張モジュールがなければ、
                検証が常に失敗するようになるということです。
            </para>

            <para>
                ユーザ側から渡された <acronym>HTTP</acronym> フィールドを使用して入力を検証する必要がある場合は、
                <methodname>enableHeaderCheck()</methodname> メソッドを使用すればこの機能を有効にできます。
            </para>

            <note>
                <title>セキュリティに関するヒント</title>

                <para>
                    ユーザ側から渡された <acronym>HTTP</acronym>
                    フィールドに依存するのはセキュリティ上のリスクとなることに注意しましょう。
                    これは簡単に改ざんすることができ、悪意のあるファイルを受け取る可能性があります。
                    ユーザ側から渡された <acronym>HTTP</acronym> フィールドを使用して入力を検証する必要がある場合は、
                    <methodname>enableHeaderCheck()</methodname> メソッドを使用すればこの機能を有効にできます。
                </para>
            </note>

            <example id="zend.file.transfer.migration.fromonenineonetooneten.example">
                <title>HTTP フィールドの使用を許可する</title>

                <programlisting language="php"><![CDATA[
// 初期化時に
$valid = new Zend_File_Transfer_Adapter_Http(array('headerCheck' => true);

// あるいは後から
$valid->enableHeaderCheck();
]]></programlisting>
        </example>
        </sect3>
    </sect2>

    <sect2 id="zend.file.transfer.migration.fromonesixtooneseven">
        <title>1.6 から 1.7 以降への移行</title>
        <sect3 id="zend.file.transfer.migration.fromonesixtooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.rename">
                <title>Rename フィルタ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.count">
                <title>Count バリデータ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.extension">
                <title>Extension バリデータ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.filessize">
                <title>FilesSize バリデータ</title>

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

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.hash">
                <title>Hash バリデータ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.imagesize">
                <title>ImageSize バリデータ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixtooneseven.validators.size">
                <title>Size バリデータ</title>

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

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

                <example id="zend.file.transfer.migration.fromonesixonetooneseven.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="zend.file.transfer.migration.fromonesixonetoonesixtwo">
        <title>1.6.1 から 1.6.2 以降への移行</title>
        <sect3 id="zend.file.transfer.migration.fromonesixonetoonesixtwo.validators">
            <title>バリデータを使う際の変更点</title>

            <para>
                <classname>Zend_File_Transfer</classname> のバリデータが
                <classname>Zend_Form</classname> のデフォルトのものと同じようには動作しないという指摘がありました。
                <classname>Zend_Form</classname> では <classname>breakChainOnFailure</classname>
                パラメータを利用でき、検証エラーが発生した際に
                それ以降のバリデータを動作させないようにすることができます。
            </para>

            <para>
                そこで、<classname>Zend_File_Transfer</classname>
                の既存のバリデータにもこのパラメータを追加することにしました。
            </para>

            <itemizedlist>
                <listitem><para>
                    古い形式の <acronym>API</acronym>: <methodname>addValidator($validator, $options, $files)</methodname>.
                </para></listitem>

                <listitem><para>
                    新しい形式の <acronym>API</acronym>: <code>addValidator($validator, $breakChainOnFailure, $options, $files)</code>.
                </para></listitem>
            </itemizedlist>

            <para>
                既存のスクリプトを新しい <acronym>API</acronym> に移行するには、バリデータの定義の後に
                <constant>FALSE</constant> を追加します。
            </para>

            <example id="zend.file.transfer.migration.fromonesixonetoonesixtwo.example">
                <title>ファイルバリデータを 1.6.1 から 1.6.2 に移行する方法</title>

                <programlisting language="php"><![CDATA[
// 1.6.1 での例
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize', array('1B', '100kB'));

// 同じ例を 1.6.2 以降用にしたもの
// boolean false が追加されていることに注意しましょう
$upload = new Zend_File_Transfer_Adapter_Http();
$upload->addValidator('FilesSize', false, array('1B', '100kB'));
]]></programlisting>
        </example>
        </sect3>
    </sect2>
</sect1>