file-upload.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 04d9aded7bbd447523cf038ddf88e6d7f7e43c53 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,takagi,mumumu -->
 <chapter xml:id="features.file-upload" xmlns="http://docbook.org/ns/docbook">
  <title>ファイルアップロードの処理</title>

  <sect1 xml:id="features.file-upload.post-method">
   <title>POST メソッドによるアップロード</title>
   <simpara>
    この機能により、テキスト、バイナリファイルの両方をアップロードできるように
    なります。
    PHP の認証機構およびファイル操作関数を用いて、アップロードを許可する
    ユーザーとアップロード後にそのファイルを使用して行う動作を完全に制御する
    ことが可能です。
   </simpara>
   <simpara>
    PHP は、全ての RFC-1867 対応ブラウザからファイルのアップロードを
    受けることができます。
   </simpara>

   <note>
    <title>関係する設定に関する注記</title>
    <para>
     &php.ini;の
     <link linkend="ini.file-uploads">file_uploads</link>,
     <link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
     <link linkend="ini.upload-tmp-dir">upload_tmp_dir</link>,
     <link linkend="ini.post-max-size">post_max_size</link>,
     <link linkend="ini.max-input-time">max_input_time</link>
     ディレクティブも参照ください。
    </para>
   </note>

   <para>
    PHP は <productname>Netscape Composer</productname> および
    W3C の <productname>Amaya</productname> クライアントにより使用される
    PUT メソッドによるファイルアップロードもサポートしています。詳細は、<link
    linkend="features.file-upload.put-method">PUT メソッドのサポート
    </link>を参照ください。
   </para>

   <para>
    <example>
     <title>ファイルアップロード用のフォーム</title>
     <para>
      ファイルアップロード画面は、次のような特別なフォームを作成すること
      により、作成することができます。
      </para>
     <programlisting role="html">
<![CDATA[
<!-- データのエンコード方式である enctype は、必ず以下のようにしなければなりません -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
    <!-- MAX_FILE_SIZE は、必ず "file" input フィールドより前になければなりません -->
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    <!-- input 要素の name 属性の値が、$_FILES 配列のキーになります -->
    このファイルをアップロード: <input name="userfile" type="file" />
    <input type="submit" value="ファイルを送信" />
</form>
]]>
     </programlisting>
     <para>
      上の例の <literal>__URL__</literal> は、PHP ファイルを指すよう置換される
      必要があります。
     </para>
     <para>
      "<literal>MAX_FILE_SIZE</literal>" hidden フィールドは、
      "file" input フィールドの前に置く必要があります。
      この値は、PHP で取得可能なファイルの最大サイズを規定します。この値はバイト数で指定します。
      <literal>MAX_FILE_SIZE</literal> は常に指定しておくべきです。
      巨大なファイルを転送しようとして長時間待ち続け、
      結局ファイルが大きすぎて転送できなかったなどといった羽目に陥るのを防げるからです。
      注意: ブラウザ側でこの最大値を出し抜くのは簡単なことなので、この機能を信頼して、
      これより大きなサイズのファイルがブロックされることを前提にしてはいけません。
      しかし、PHP 側の最大サイズの設定を欺くことはできません。
     </para>
    </example>
   </para>

   <note>
    <para>
      アップロード用のフォームが
      <literal>enctype="multipart/form-data"</literal> 属性を有しているかを
      確認してください。さもないと、ファイルのアップロードは動作しません。
    </para>
   </note>

   <para>
    グローバルの <varname>$_FILES</varname> には、アップロードされたファイルの情報が含まれます。
    サンプルのフォームからの内容は次のようになります。ここでは、上の例のスクリプトで使われたように、
    アップロードファイルの名前として <emphasis>userfile</emphasis> を
    使用することを仮定していることに注意してください。
    実際にはどんな名前にすることもできます。
    <variablelist>
     <varlistentry>
      <term><varname>$_FILES['userfile']['name']</varname></term>
      <listitem>
       <para>
        クライアントマシンの元のファイル名。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['type']</varname></term>
      <listitem>
       <para>
        ファイルの MIME 型。ただし、ブラウザがこの情報を提供する場合。
        例えば、<literal>"image/gif"</literal> のようになります。
        この MIME 型は PHP 側ではチェックされません。そのため、
        この値は信用できません。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['size']</varname></term>
      <listitem>
       <para>
        アップロードされたファイルのバイト単位のサイズ。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['tmp_name']</varname></term>
      <listitem>
       <para>
        アップロードされたファイルがサーバー上で保存されているテンポラ
        リファイルの名前。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['error']</varname></term>
      <listitem>
       <para>
        このファイルアップロードに関する
        <link linkend="features.file-upload.errors">エラーコード</link>
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['full_path']</varname></term>
      <listitem>
       <para>
        ブラウザからアップロードされたファイルのフルパス。
        この値は実際のディレクトリ構造を反映しているとは必ずしも言えないため、
        信用できません。
        PHP 8.1.0 以降で利用可能です。
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    &php.ini; の <link
    linkend="ini.upload-tmp-dir">upload_tmp_dir</link> ディレクティブで
    他の場所を指定しない限り、ファイルはサーバーにおけるデフォルトの
    テンポラリディレクトリに保存されます。サーバーのデフォルトディレクトリは、
    PHP を実行する環境において環境変数 <envar>TMPDIR</envar> を設定する
    ことにより変更することができます。しかし、PHP スクリプトの内部から
    <function>putenv</function> 関数により設定しても上手くいきません。
    この環境変数は、アップロードされたファイルに他の処理を行う際にも
    同様に使用することが可能です。
    <example>
     <title>ファイルのアップロードを検証する</title>
     <para>
      詳細については、<function>is_uploaded_file</function>
      および <function>move_uploaded_file</function> の関数のエントリも
      参照ください。以下はフォームからファイルをアップロードするプロセスの例です。
     </para>
     <programlisting role="php">
<![CDATA[
<?php
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo "File is valid, and was successfully uploaded.\n";
} else {
    echo "Possible file upload attack!\n";
}

echo 'Here is some more debugging info:';
print_r($_FILES);

print "</pre>";

?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    アップロードされたファイルを受け取る PHP スクリプトは、アップロード
    されたファイルを用いて何をするべきかを決めるために必要なロジックを
    全て実装する必要があります。例えば、変数
    <varname>$_FILES['userfile']['size']</varname> を使用して、小さすぎたり
    大きすぎたりするファイルを捨てることができます。指定した型以外の
    ファイルを全て捨てるために変数
    <varname>$_FILES['userfile']['type']</varname> を用いることができますが、
    これはあくまでいくつかのチェックの中のひとつとしてのみ実行するように
    してください。なぜなら、この値を設定するのはあくまでもクライアントであり、
    PHP 側では何もチェックしていないからです。
    また、
    <varname>$_FILES['userfile']['error']</varname> を使用することができ、
    <link linkend="features.file-upload.errors">エラーコード</link>
    に基づき、ロジックを構成することができます。
    何らかの方法により、テンポラリディレクトリからファイルを削除したり
    他の場所に移動したりする必要があります。
   </simpara>
   <simpara>
    フォームでアップロードされるファイルが選択されていない場合、PHP は
    <varname>$_FILES['userfile']['size']</varname> として 0 を返し、
    <varname>$_FILES['userfile']['tmp_name']</varname> には値を
    設定しません。
   </simpara>
   <simpara>
    移動または名前の変更が行われていない場合、リクエストの終了時に
    そのファイルはテンポラリディレクトリから削除されます。
   </simpara>
    <example>
     <title>ファイルの配列をアップロードする</title>
     <para>
      PHP はファイルについても
      <link linkend="faq.html.arrays">HTML フォームで配列を使用すること</link>
      をサポートしています。
     </para>
     <programlisting role="html">
<![CDATA[
<form action="" method="post" enctype="multipart/form-data">
<p>Pictures:
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="submit" value="Send" />
</p>
</form>
]]>
     </programlisting>
     <programlisting role="php">
<![CDATA[
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        // basename() で、ひとまずファイルシステムトラバーサル攻撃は防げるでしょう。
        // ファイル名についてのその他のバリデーションも、適切に行いましょう。
        $name = basename($_FILES["pictures"]["name"][$key]);
        move_uploaded_file($tmp_name, "data/$name");
    }
}
?>
]]>
     </programlisting>
    </example>
   <para>
    ファイルアップロードのプログレスバーは、<link
    linkend="session.upload-progress">セッションのアップロードの進捗</link>
    で実装することができます。
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.errors">
   <title>エラーメッセージの説明</title>
   <simpara>
    PHP はファイル配列とともに適当なエラーコードを返します。
    エラーコードは、PHP によるファイルアップロードの間に生成され、
    ファイル配列の<emphasis>['error']</emphasis> 要素で
    アクセス可能です。言い換えると、エラーは、
    <varname>$_FILES['userfile']['error']</varname> でアクセス可能でしょう。
   </simpara>
   <para>
    <variablelist>
     <varlistentry>
      <term><constant>UPLOAD_ERR_OK</constant></term>
      <listitem>
       <para>
        値: 0; エラーはなく、ファイルアップロードは成功しています。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_INI_SIZE</constant></term>
      <listitem>
       <para>
        値: 1; アップロードされたファイルは、&php.ini; の
        <link linkend="ini.upload-max-filesize">upload_max_filesize</link>
        ディレクティブの値を超えています。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_FORM_SIZE</constant></term>
      <listitem>
       <para>
        値: 2; アップロードされたファイルは、HTML フォームで指定された
        <emphasis>MAX_FILE_SIZE</emphasis> を超えています。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_PARTIAL</constant></term>
      <listitem>
       <para>
        値: 3; アップロードされたファイルは一部のみしかアップロードされていません。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_NO_FILE</constant></term>
      <listitem>
       <para>
        値: 4; ファイルはアップロードされませんでした。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_NO_TMP_DIR</constant></term>
      <listitem>
       <para>
        値: 6; テンポラリフォルダがありません。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><constant>UPLOAD_ERR_CANT_WRITE</constant></term>
      <listitem>
       <para>
        値: 7; ディスクへの書き込みに失敗しました。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
       <term><constant>UPLOAD_ERR_EXTENSION</constant></term>
       <listitem>
         <para>
           値: 8; PHP の拡張モジュールがファイルのアップロードを中止しました。
           どの拡張モジュールがファイルアップロードを中止させたのかを突き止めることはできません。
           読み込まれている拡張モジュールの一覧を <function>phpinfo</function> で取得すれば参考になるでしょう。
         </para>
       </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.common-pitfalls">
   <title>陥りやすい落とし穴</title>
   <simpara>
    <literal>MAX_FILE_SIZE</literal> の値に、&php.ini; の <link
    linkend="ini.upload-max-filesize">upload_max_filesize</link>
    で指定されたファイルサイズより大きなファイルサイズを指定する
    ことはできません。デフォルトは、2 メガバイトです。
   </simpara>
   <simpara>
    メモリ制限が有効な場合、<link
    linkend="ini.memory-limit">memory_limit</link> の値をより大きく
    設定することが必要となる可能性があります。
    <link linkend="ini.memory-limit">memory_limit</link> に充分大きな
    値を設定するようにしてください。
   </simpara>
   <simpara>
    <link linkend="ini.max-execution-time">max_execution_time</link>
    に設定した値が小さすぎた場合、スクリプトの実行時間がこの値を越える
    可能性を生じます。
    <literal>max_execution_time</literal> に充分大きな値を設定するように
    してください。
   </simpara>
   <note>
    <simpara>
     <link linkend="ini.max-execution-time">max_execution_time</link>
     はスクリプト自身の実行時間にのみ影響します。
     スクリプトの実行範囲の外側で発生する動作にかかる時間、つまり、
     <function>system</function> を使ったシステムコールや、
     <function>sleep</function> 関数、データベースに対するクエリー、
     ファイルアップロードプロセス、などに費やされた時間はスクリプトの
     総実行時間に含まれません。
    </simpara>
   </note>
   <warning>
    <simpara>
     <link linkend="ini.max-input-time">max_input_time</link>
     は、スクリプトで入力を受け付けることができる最大秒数を設定します。
     この秒数には、ファイルアップロードの時間も含まれます。
     大きなファイルや複数のファイルをアップロードしたり接続に時間を要したりする場合は、
     デフォルト値の <literal>60</literal> 秒を増やしましょう。
    </simpara>
   </warning>
   <simpara>
    <link linkend="ini.post-max-size">post_max_size</link> の設定値が
    小さすぎた場合、大きなファイルをアップロードすることができなくなります。
    <literal>post_max_size</literal> に充分大きな値を設定するように
    してください。
   </simpara>
   <simpara>
    <link linkend="ini.max-file-uploads">max_file_uploads</link>
    は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。
    この制限を超える数のファイルをアップロードしようとすると、制限に達した時点で
    <varname>$_FILES</varname> は処理を停止します。たとえば
    <link linkend="ini.max-file-uploads">max_file_uploads</link> が
    <literal>10</literal> の場合には、<varname>$_FILES</varname>
    には 10 件までの要素しか入らないということです。
   </simpara>
   <simpara>
    処理するファイルを検証しない場合、ユーザーが他のディレクトリにある
    非公開情報にアクセスできる可能性を生じます。
   </simpara>
   <simpara>
    大量のディレクトリ一覧のスタイルのせいで、
    風変わりな名前（空白を含んでいるとか）のファイルを適切に扱えることは
    保証できません。
   </simpara>
   <simpara>
    通常の <literal>input</literal> フィールドとファイルアップロードフィールドを
    (<literal>input</literal> の name に <literal>foo[]</literal> を利用するなどして)
    同一のフォーム変数で扱うことはできません。
   </simpara>
  </sect1>

  <sect1 xml:id="features.file-upload.multiple">
   <title>複数ファイルのアップロード</title>
   <simpara>
    <literal>input</literal> で異なった <literal>name</literal> を
    使用することにより、複数のファイルをアップロードすることができます。
   </simpara>
   <simpara>
    複数のファイルを一度にアップロードし、自動的にまとめられた情報を
    配列で取得することが可能です。これを行うには、HTML フォームで
    複数選択可能なセレクトやチェックボックスを指定する際と同様、
    配列を用いた投稿用の構文を使用する必要があります。
   </simpara>
   <para>
    <example>
     <title>複数ファイルのアップロード</title>
     <programlisting role="html">
<![CDATA[
<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send these files:<br />
  <input name="userfile[]" type="file" /><br />
  <input name="userfile[]" type="file" /><br />
  <input type="submit" value="Send files" />
</form>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    上記のフォームで投稿された場合、配列
    <varname>$_FILES['userfile']</varname>,
    <varname>$_FILES['userfile']['name']</varname>,
    <varname>$_FILES['userfile']['size']</varname>
    が設定されます。
   </simpara>
   <simpara>
    例えば、ファイル名が <filename>/home/test/review.html</filename> 
    および <filename>/home/test/xwp.out</filename> のファイルが
    投稿されたとしましょう。この場合、
    <varname>$_FILES['userfile']['name'][0]</varname> の値が
    <filename>review.html</filename> となり、
    <varname>$_FILES['userfile']['name'][1]</varname> の値が
    <filename>xwp.out</filename> となります。
    同様に、<varname>$_FILES['userfile']['size'][0]</varname> の値が
    <filename>review.html</filename> のファイルサイズといったように
    なります。
   </simpara>
   <simpara>
    <varname>$_FILES['userfile']['name'][0]</varname>,
    <varname>$_FILES['userfile']['tmp_name'][0]</varname>,
    <varname>$_FILES['userfile']['size'][0]</varname>,
    <varname>$_FILES['userfile']['type'][0]</varname> も設定されます。
   </simpara>
   <warning>
    <simpara>
     <link linkend="ini.max-file-uploads">max_file_uploads</link>
     は一回のリクエストあたりでアップロードできるファイルの数の制限値となります。
     フォームからの一回のリクエストで、
     これを超える数のファイルをアップロードしてしまわないようにしましょう。
    </simpara>
   </warning>
   <para>
    <example>
     <title>ディレクトリ全体をアップロードする</title>
     <simpara>
      HTML のファイルアップロードフィールド中に、
      <literal>webkitdirectory</literal> 属性を指定することで
      ディレクトリ全体をアップロードすることができます。
      この機能はほとんどのモダンなブラウザでサポートされています。
     </simpara>
     <simpara>
      <literal>full_path</literal> の情報を使うと、
      相対パスを保存することもできますし、
      サーバー上で同じディレクトリを再構築することもできます。
     </simpara>
     <programlisting role="html">
<![CDATA[
<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send this directory:<br />
  <input name="userfile[]" type="file" webkitdirectory multiple />
  <input type="submit" value="Send files" />
</form>
]]>
     </programlisting>
    </example>

    <warning>
     <simpara>
      <literal>webkitdirectory</literal> 属性は標準ではありませんし、
      標準化の過程にも入っていません。
      この属性を Web 上の本番環境で使わないで下さい:
      なぜなら、この属性を全ユーザーが使えるとは限らないからです。
      また、この属性はクライアントの実装に非互換がある可能性もありますし、
      振る舞いが将来変更される可能性もあります。
     </simpara>
     <simpara>
      PHP は ブラウザ/ユーザーエージェントから送られてきた相対パスの情報をパースし、
      その情報を <varname>$_FILES</varname> 配列に渡すことだけを行います。
      <literal>full_path</literal> 配列中の値が、
      実際のディレクトリ構造を含んでいるという保証はありません。
      よって、PHP アプリケーションはこの情報を信用してはいけません。
     </simpara>
    </warning>
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.put-method">
   <title>PUT メソッドのサポート</title>
   <para>
    PHP は、クライアントがサーバーにファイルを保存するための
    HTTP PUT メソッドのサポートを提供します。
    PUT リクエストは POST リクエストによるファイルアップロードよりもシンプルであり、
    次のような形になります。
    <informalexample>
     <programlisting role="HTTP">
<![CDATA[
PUT /path/filename.html HTTP/1.1
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    これは、通常、リモートクライアントが <filename>/path/filename.html</filename>
    が指す内容を Web ツリーに保存したいことを意味します。 Apache または PHP に
    おいて全ての人が Web ツリー上の任意のファイルを自動的に上書きできる
    ようにするというのは明らかに良い発想ではありません。よって、このような
    リクエストを処理する際には、まずそのリクエストを処理する特定の
    PHP スクリプトが必要なことを web サーバーに通知する必要があります。
    Apache においては、<emphasis>Script</emphasis> ディレクティブにより
    これを行うことができます。これは、Apache 設定ファイルのほぼ任意の
    場所に置くことができます。一般的なのは、<literal>&lt;Directory&gt;</literal>
    ブロックまたは <literal>&lt;VirtualHost&gt;</literal> ブロックの中です。次のように指定します。
    <informalexample>
     <programlisting>
<![CDATA[
Script PUT /put.php
]]>
    </programlisting>
    </informalexample>
   </para>
   <simpara>
    これにより、この行を指定したコンテキストにマッチする URI を有する
    すべての PUT リクエストが <filename>put.php</filename> スクリプトに送られるよう Apache に
    指定します。 もちろん、拡張子 <filename class="extension">.php</filename> により PHP が実行されるよう設定され、
    PHP がアクティブであることが必要です。
    このスクリプトに対するすべての PUT リクエストの対象リソースは、
    スクリプト自身とします。アップロードされるファイルのファイル名ではありません。
   </simpara>
   <simpara>
    PHP では、put.php の中で以下のようなことを行います。
    これは、アップロードされたファイルをサーバー上のファイル
    <filename>myputfile.ext</filename> にコピーします。
    ファイルコピーを行う前には、
    何らかの確認やユーザー認証を行いたくなるかもしれません。
   </simpara>
   <para>
    <example>
     <title>HTTP PUT されたファイルの保存</title>
     <programlisting role="php">
<![CDATA[
<?php
/* PUT されたデータは標準入力からやってきます */
$putdata = fopen("php://input", "r");

/* 書き込みモードでファイルをオープンします */
$fp = fopen("myputfile.ext", "w");

/* データを 1 KB 単位で読み込み、
   ファイルに書き込みます */
while ($data = fread($putdata, 1024))
  fwrite($fp, $data);

/* ストリームを閉じます */
fclose($fp);
fclose($putdata);
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.errors.seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="security.filesystem">ファイルシステムのセキュリティ</link></member>
   </simplelist>
  </para>
 </sect1>

 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->