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

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

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

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

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

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

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

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Filter_File_Rename($options)</classname>
                        $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 role="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><emphasis>Count</emphasis> バリデータ</title>

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Validate_File_Count($options)</classname>
                        $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 role="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><emphasis>Extension</emphasis> バリデータ</title>

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Validate_File_Extension($options)</classname>
                        $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 role="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><emphasis>FilesSize</emphasis> バリデータ</title>

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

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

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

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

                    <programlisting role="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><emphasis>Hash</emphasis> バリデータ</title>

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Validate_File_Hash($options)</classname>
                        $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 role="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><emphasis>ImageSize</emphasis> バリデータ</title>

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Validate_File_FilesSize($options)</classname>
                        $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 role="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><emphasis>Size</emphasis> バリデータ</title>

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

                    <listitem><para>
                        新しい形式の API: <classname>Zend_Validate_File_Size($options)</classname>
                        $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 role="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>
                    古い形式の API: <code>addValidator($validator, $options, $files)</code>.
                </para></listitem>

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

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

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

                <programlisting role="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>