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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24658 -->
<sect1 id="zend.file.transfer.introduction">
    <title>Zend_File_Transfer(日本語)</title>

    <para>
        <classname>Zend_File_Transfer</classname> を使用すると、
        ファイルのアップロードやダウンロードを管理できます。
        組み込みのバリデータを使ってファイルを検証したり、
        フィルタによってファイルを変更したりという機能があります。
        <classname>Zend_File_Transfer</classname> はアダプタ形式を採用しており、
        <acronym>HTTP</acronym> や FTP、WEBDAV などのさまざまな転送プロトコルを同じ <acronym>API</acronym> で使用できます。
    </para>

    <note>
        <title>制限</title>

        <para>
            現在の <classname>Zend_File_Transfer</classname>
            の実装では、<acronym>HTTP</acronym> Post によるアップロードにしか対応していません。
            ファイルのダウンロードやその他のアダプタについては次のリリースで追加される予定です。
            実装されていないメソッドを実行すると例外をスローします。
            したがって、実際のところは
            <classname>Zend_File_Transfer_Adapter_Http</classname>
            のインスタンスを直接操作することになります。
            これは、将来複数のアダプタが使用可能になった段階で変更される予定です。
        </para>
    </note>

    <note>
        <title>フォーム</title>

        <para>
            <classname>Zend_Form</classname> を使う場合は <classname>Zend_Form</classname>
            の <acronym>API</acronym> を使うようにし、<classname>Zend_File_Transfer</classname>
            を直接使わないようにしましょう。<classname>Zend_Form</classname>
            のファイル転送機能は <classname>Zend_File_Transfer</classname>
            で実装されているので、この章の説明は <classname>Zend_Form</classname>
            のユーザにも有用です。
        </para>
    </note>

    <para>
        <classname>Zend_File_Transfer</classname> の使い方はきわめて単純です。
        ふたつの部分から成り立っており、
        アップロードを行う <acronym>HTTP</acronym> フォームとアップロードされたファイルを
        <classname>Zend_File_Transfer</classname> で処理するコードを作成します。
        次の例を参照ください。
    </para>

    <example id="zend.file.transfer.introduction.example">
        <title>シンプルなファイルアップロードフォーム</title>

        <para>
            これは、基本的なファイルアップロード処理の例です。
            まずはファイルアップロードフォームから。
            今回の例では。アップロードしたいファイルはひとつです。
        </para>

        <programlisting language="xml"><![CDATA[
<form enctype="multipart/form-data" action="/file/upload" method="POST">
    <input type="hidden" name="MAX_FILE_SIZE" value="100000" />
        アップロードするファイルを選択: <input name="uploadedfile" type="file" />
    <br />
    <input type="submit" value="アップロード" />
</form>
]]></programlisting>

        <para>
            <acronym>HTML</acronym> を直接作成するのではなく、利便性を考慮して
            <link linkend="zend.form.standardElements.file">Zend_Form_Element_File</link>
            を使っていることに注意しましょう。
        </para>

        <para>
            次はアップロードしたファイルを受け取る側です。
            今回の例では、受け取る側は <filename>/file/upload</filename>
            となります。そこで、 'file' コントローラにアクション
            <methodname>upload()</methodname> を作成します。
        </para>

        <programlisting language="php"><![CDATA[
$adapter = new Zend_File_Transfer_Adapter_Http();

$adapter->setDestination('C:\temp');

if (!$adapter->receive()) {
    $messages = $adapter->getMessages();
    echo implode("\n", $messages);
}
]]></programlisting>

        <para>
            このコードは <classname>Zend_File_Transfer</classname> のもっともシンプルな使用法を示すものです。
            ローカルの保存先を <methodname>setDestination()</methodname> メソッドで指定して
            <methodname>receive()</methodname> メソッドをコールします。
            アップロード時に何らかのエラーが発生した場合は、
            返された例外の中でその情報を取得できます。
        </para>

    </example>

    <note>
        <title>注意</title>

        <para>
            この例は、<classname>Zend_File_Transfer</classname> の基本的な <acronym>API</acronym> を説明するためだけのものです。
            これをそのまま実際の環境で使用しては
            <emphasis>いけません</emphasis>。
            深刻なセキュリティ問題を引き起こしてしまいます。
            常にバリデータを使用してセキュリティを向上させるようにしなければなりません。
        </para>
    </note>

    <sect2 id="zend.file.transfer.introduction.adapters">
        <title>Zend_File_Transfer がサポートするアダプタ</title>

        <para>
            <classname>Zend_File_Transfer</classname> は、
            さまざまなアダプタと転送方向をサポートするように作られています。
            ファイルのアップロードやダウンロードだけでなく、転送
            (あるアダプタでのアップロードと別のアダプタでのダウンロードを同時に行う)
            にも対応できるように設計されています。
            しかし、Zend Framework 1.6 の時点で存在するアダプタは
            Http アダプタひとつだけです。
        </para>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.options">
        <title>Zend_File_Transfer のオプション</title>

        <para>
            <classname>Zend_File_Transfer</classname> やそのアダプタはさまざまなオプションをサポートしています。
            オプションはコンストラクタで指定することもできますし、
            <methodname>setOptions($options)</methodname> で指定することもできます。
            <methodname>getOptions()</methodname> は、実際に設定されているオプションを返します。
            サポートするオプションは次のとおりです。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>ignoreNoFile</emphasis>: このオプションを <constant>TRUE</constant> にすると、
                    ファイルがフォームからアップロードされなかったときにバリデータは何も行いません。
                    このオプションの既定値は <constant>FALSE</constant> で、
                    この場合はファイルがアップロードされなければエラーとなります。
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.checking">
        <title>ファイルのチェック</title>

        <para>
            <classname>Zend_File_Transfer</classname>
            のメソッドの中には、さまざまな前提条件をチェックするためのものもあります。
            これらは、アップロードされたファイルを処理する際に便利です。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>isValid($files = null)</emphasis>: このメソッドは、
                    ファイルにアタッチされたバリデータを用いてそのファイルが妥当なものかどうかを検証します。
                    ファイル名を省略した場合はすべてのファイルをチェックします。
                    <methodname>isValid()</methodname> を <methodname>receive()</methodname> の前にコールすることもできます。
                    この場合、<methodname>receive()</methodname> がファイルを受信する際に内部的に
                    <methodname>isValid()</methodname> をコールすることはありません。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>isUploaded($files = null)</emphasis>: このメソッドは、
                    指定したファイルがユーザによってアップロードされたものなのかどうかを調べます。
                    これは、複数のファイルを任意でアップロードできるようにする場合などに便利です。
                    ファイル名を省略した場合はすべてのファイルをチェックします。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>isReceived($files = null)</emphasis>: このメソッドは、
                    指定したファイルがすでに受信済みであるかどうかを調べます。
                    ファイル名を省略した場合はすべてのファイルをチェックします。
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.file.transfer.introduction.checking.example">
            <title>ファイルのチェック</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();

// すべての既知の内部ファイル情報を返します
$files = $upload->getFileInfo();

foreach ($files as $file => $info) {
    // アップロードされたファイルか ?
    if (!$upload->isUploaded($file)) {
        print "ファイルをアップロードしてください";
        continue;
    }

    // バリデータを通過したか ?
    if (!$upload->isValid($file)) {
        print "$file は不適切です";
        continue;
    }
}

$upload->receive();
]]></programlisting>

        </example>
    </sect2>

    <sect2 id="zend.file.transfer.introduction.informations">
        <title>さらなるファイル情報</title>

        <para>
            <classname>Zend_File_Transfer</classname> は、ファイルについてのさらなる情報を返すことができます。
            次のメソッドが使用可能です。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>getFileName($file = null, $path = true)</emphasis>:
                    このメソッドは、転送されたファイルの実際のファイル名を返します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getFileInfo($file = null)</emphasis>:
                    このメソッドは、転送されたファイルのすべての内部情報を返します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getFileSize($file = null)</emphasis>:
                    このメソッドは、指定したaifるの実際のファイルサイズを返します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getHash($hash = 'crc32', $files = null)</emphasis>:
                    このメソッドは、転送されたファイルの内容のハッシュを返します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>getMimeType($files = null)</emphasis>:
                    このメソッドは、転送されたファイルの mimetype を返します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <methodname>getFileName()</methodname> の最初のパラメータには、
            要素の名前を渡すことができます。名前を省略した場合は、
            すべてのファイル名を配列で返します。
            multifile 形式であった場合も結果は配列となります。
            ファイルがひとつだけだった場合は結果を文字列で返します。
        </para>

        <para>
            デフォルトでは、ファイル名はフルパス形式で返されます。
            パス抜きのファイル名だけがほしい場合は、2 番目のパラメータ
            <code>$path</code> を設定します。これを <constant>FALSE</constant>
            にするとパスの部分を取り除いた結果を返します。
        </para>

        <example id="zend.file.transfer.introduction.informations.example1">
            <title>ファイル名の取得</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();
$upload->receive();

// すべてのファイルのファイル名を返します
$names = $upload->getFileName();

// フォームの 'foo' 要素のファイル名を返します。
$names = $upload->getFileName('foo');
]]></programlisting>

        </example>

        <note>
            <para>
                ファイルを受信する際にファイル名が変わることがあることに注意しましょう。
                これは、ファイルを受信した後ですべてのフィルタが適用されるからです。
                <methodname>getFileName()</methodname> をコールするのは、ファイルを受信してからでなければなりません。
            </para>
        </note>

        <para>
            <methodname>getFileSize()</methodname> は、デフォルトではファイルサイズを SI 記法で返します。
            つまり、たとえば <emphasis>2048</emphasis> ではなく <emphasis>2kB</emphasis>
            のようになるということです。単にサイズだけが知りたい場合は、オプション
            <property>useByteString</property> を <constant>FALSE</constant> に設定してください。
        </para>

        <example id="zend.file.transfer.introduction.informations.example.getfilesize">
            <title>ファイルのサイズの取得</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();
$upload->receive();

// 複数のファイルがアップロードされた場合は、すべてのファイルのサイズを配列で返します
$size = $upload->getFileSize();

// SI 記法を無効にし、数値のみを返すようにします
$upload->setOptions(array('useByteString' => false));
$size = $upload->getFileSize();
]]></programlisting>

        </example>

        <!-- TODO : to be translated -->
        <note>
            <title>Client given filesize</title>

            <para>
                Note that the filesize which is given by the client is not seen as save input.
                Therefor the real size of the file will be detected and returned instead of the
                filesize sent by the client.
            </para>
        </note>

        <para>
            <methodname>getHash()</methodname> の最初のパラメータには、ハッシュアルゴリズムの名前を指定します。
            使用できるアルゴリズムについては
            <ulink url="http://php.net/hash_algos">PHP の hash_algos メソッド</ulink>
            を参照ください。アルゴリズムを省略した場合は
            <emphasis>crc32</emphasis> をデフォルトのアルゴリズムとして使用します。
        </para>

        <example id="zend.file.transfer.introduction.informations.example2">
            <title>ファイルのハッシュの取得</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();
$upload->receive();

// 複数のファイルがアップロードされた場合は、すべてのファイルのハッシュを配列で返します
$hash = $upload->getHash('md5');

// フォームの 'foo' 要素のハッシュを返します。
$names = $upload->getHash('crc32', 'foo');
]]></programlisting>

        </example>

        <note>
            <title>返り値</title>

            <para>
                複数のファイルを指定した場合は、返される結果が配列となることに注意しましょう。
            </para>
        </note>

        <para>
            <methodname>getMimeType()</methodname> はファイルの mimetype を返します。
            複数のファイルがアップロードされた場合は配列、そうでない場合は文字列を返します。
        </para>

        <example id="zend.file.transfer.introduction.informations.getmimetype">
            <title>ファイルの mimetype の取得</title>

            <programlisting language="php"><![CDATA[
$upload = new Zend_File_Transfer();
$upload->receive();

$mime = $upload->getMimeType();

// フォーム要素 'foo' の mimetype を返します
$names = $upload->getMimeType('foo');
]]></programlisting>

        </example>

        <!-- TODO : to be translated -->
        <note>
            <title>Client given mimetype</title>

             <para>
                Note that the mimetype which is given by the client is not seen as save input.
                Therefor the real mimetype of the file will be detected and returned instead of the
                mimetype sent by the client.
            </para>
        </note>

        <warning>
            <title>ありえる例外</title>

            <para>
                このメソッドは、fileinfo 拡張モジュールが使用可能な場合はそれを使用することに注意しましょう。
                この拡張モジュールがみつからなかった場合は、mimemagic 拡張モジュールを使用します。
                それもみつからなかった場合は、例外を発生します。
            </para>
        </warning>

        <!-- TODO : to be translated -->
        <warning>
            <title>Original data within $_FILES</title>

            <para>
                Due to security reasons also the original data within $_FILES will be overridden
                as soon as <classname>Zend_File_Transfer</classname> is initiated. When you want
                to omit this behaviour and have the original data simply set the
                <property>detectInfos</property> option to <constant>FALSE</constant> at initiation.
            </para>

            <para>
                This option will have no effect after you initiated
                <classname>Zend_File_Transfer</classname>.
            </para>
        </warning>

    </sect2>

    <sect2 id="zend.file.transfer.introduction.uploadprogress">
        <title>ファイルアップロードの進捗</title>

        <para>
            <classname>Zend_File_Transfer</classname> では、ファイルアップロードの進捗状況を知ることができます。
            この機能を使用するには、<acronym>APC</acronym> 拡張モジュール
            (ほとんどの <acronym>PHP</acronym> 環境においてデフォルトで提供されています)
            あるいは <classname>uploadprogress</classname> 拡張モジュールが必要です。
            これらの拡張モジュールがインストールされていれば、自動検出してそれを使用します。
            進捗状況を取得するには、いくつかの事前条件があります。
        </para>

        <para>
            まず、<acronym>APC</acronym> あるいは <classname>uploadprogress</classname>
            のいずれかを有効にする必要があります。<acronym>APC</acronym>
            の機能は <filename>php.ini</filename> で無効化できることに注意しましょう。
        </para>

        <para>
            次に、ファイルを送信するフォームの中に適切な hidden
            フィールドを追加しなければなりません。<classname>Zend_Form_Element_File</classname>
            を使う場合は、この hidden フィールドは
            <classname>Zend_Form</classname> が自動的に追加します。
        </para>

        <para>
            これらふたつの条件さえ満たせば、ファイルアップロードの進捗状況を
            <code>getProgress</code> メソッドで取得できます。
            実際には、これを処理する公式な方法は 2 通りあります。
        </para>

        <sect3 id="zend.file.transfer.introduction.uploadprogress.progressadapter">

            <title>progressbar アダプタを使用する</title>

            <para>
                <emphasis>Zend_ProgressBar</emphasis> を使用して、
                実際の進捗状況を取得した上でそれをシンプルにユーザに見せることができます。
            </para>

            <para>
                そのためには、<methodname>getProgress()</methodname> を最初にコールするときにお望みの
                <emphasis>Zend_ProgressBar_Adapter</emphasis> を追加しなければなりません。
                どのアダプタを使用すればいいのかについては
                <link linkend="zend.progressbar.adapters">Zend_ProgressBar の標準のアダプタ</link>
                の章を参照ください。
            </para>

            <example id="zend.file.transfer.introduction.uploadprogress.progressadapter.example1">
                <title>progressbar アダプタを使用した実際の状態の取得</title>

                <programlisting language="php"><![CDATA[
$adapter = new Zend_ProgressBar_Adapter_Console();
$upload  = Zend_File_Transfer_Adapter_Http::getProgress($adapter);

$upload = null;
while (!$upload['done']) {
    $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
}
]]></programlisting>

            </example>

            <para>
                完全な処理は、バックグラウンドで <methodname>getProgress()</methodname> によって行われます。
            </para>

        </sect3>

        <sect3 id="zend.file.transfer.introduction.uploadprogress.manually">
            <title>getProgress() を手動で使用する</title>

            <para>
                <classname>Zend_ProgressBar</classname> を使わずに手動で
                <methodname>getProgress()</methodname> を動作させることもできます。
            </para>

            <para>
                <methodname>getProgress()</methodname> を何も設定なしでコールします。
                すると、いくつかのキーを含む配列が返されます。
                使用している <acronym>PHP</acronym> 拡張モジュールによってその内容は異なります。
                しかし、次のキーは拡張モジュールにかかわらず返されます。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>id</emphasis>:
                        このアップロードの ID。その拡張モジュール内でのアップロードを一意に識別します。
                        自動的に設定され、この値は決して変更することができません。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>total</emphasis>:
                        アップロードされたファイル全体のサイズをバイト単位で表した整数値。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>current</emphasis>:
                        現在までにアップロードされたファイルサイズをバイト単位で表した整数値。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>rate</emphasis>:
                        アップロードの平均速度を「バイト/秒」単位で表した整数値。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>done</emphasis>:
                        アップロードが終了したときは <constant>TRUE</constant> 、
                        そうでなければ <constant>FALSE</constant> を返します。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>message</emphasis>:
                        実際のメッセージ。進捗を <emphasis>10kB / 200kB</emphasis>
                        形式で表したテキストか、何か問題が起こった場合には有用なメッセージとなります。
                        「問題」とは、何もアップロード中でない場合や
                        進捗状況の取得に失敗した場合、あるいはアップロードがキャンセルされた場合を意味します。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>progress</emphasis>:
                        このオプションキーには <classname>Zend_ProgressBar_Adapter</classname> あるいは
                        Zend_ProgressBar のインスタンスが含まれ、
                        プログレスバー内から実際のアップロード状況を取得できるようになります。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>session</emphasis>:
                        このオプションキーには <classname>Zend_ProgressBar</classname>
                        内で使用するセッション名前空間の名前が含まれます。
                        このキーが与えられなかったときのデフォルトは
                        <classname>Zend_File_Transfer_Adapter_Http_ProgressBar</classname> です。
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                それ以外に返されるキーについては各拡張モジュールが直接返すものであり、
                チェックしていません。
            </para>

            <para>
                次の例は、手動で使用する方法を示すものです。
            </para>

            <example id="zend.file.transfer.introduction.uploadprogress.manually.example1">
                <title>手動での進捗状況表示の使用法</title>

                <programlisting language="php"><![CDATA[
$upload  = Zend_File_Transfer_Adapter_Http::getProgress();

while (!$upload['done']) {
    $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
    print "\nActual progress:".$upload['message'];
    // 何か必要な処理をします
}
]]></programlisting>

            </example>

            <!-- TODO : to be translated -->
            <note>
                <title>Knowing the file to get the progress from</title>

                <para>
                    The above example works when your upload identified is set to 'progress_key'.
                    When you are using another identifier within your form you must give the used
                    identifier as first parameter to <methodname>getProgress()</methodname> on the
                    initial call.
                </para>
            </note>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 tw=80 et:
-->