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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 21606 -->
   4 <sect1 id="zend.file.transfer.introduction">
   5     <title>Zend_File_Transfer</title>
   6
   7     <para>
   8         <classname>Zend_File_Transfer</classname> を使用すると、
   9         ファイルのアップロードやダウンロードを管理できます。
  10         組み込みのバリデータを使ってファイルを検証したり、
  11         フィルタによってファイルを変更したりという機能があります。
  12         <classname>Zend_File_Transfer</classname> はアダプタ形式を採用しており、
  13         <acronym>HTTP</acronym> や FTP、WEBDAV などのさまざまな転送プロトコルを同じ <acronym>API</acronym> で使用できます。
  14     </para>
  15
  16     <note>
  17         <title>制限</title>
  18
  19         <para>
  20             現在の <classname>Zend_File_Transfer</classname>
  21             の実装では、<acronym>HTTP</acronym> Post によるアップロードにしか対応していません。
  22             ファイルのダウンロードやその他のアダプタについては次のリリースで追加される予定です。
  23             実装されていないメソッドを実行すると例外をスローします。
  24             したがって、実際のところは
  25             <classname>Zend_File_Transfer_Adapter_Http</classname>
  26             のインスタンスを直接操作することになります。
  27             これは、将来複数のアダプタが使用可能になった段階で変更される予定です。
  28         </para>
  29     </note>
  30
  31     <note>
  32         <title>フォーム</title>
  33
  34         <para>
  35             <classname>Zend_Form</classname> を使う場合は <classname>Zend_Form</classname>
  36             の <acronym>API</acronym> を使うようにし、<classname>Zend_File_Transfer</classname>
  37             を直接使わないようにしましょう。<classname>Zend_Form</classname>
  38             のファイル転送機能は <classname>Zend_File_Transfer</classname>
  39             で実装されているので、この章の説明は <classname>Zend_Form</classname>
  40             のユーザにも有用です。
  41         </para>
  42     </note>
  43
  44     <para>
  45         <classname>Zend_File_Transfer</classname> の使い方はきわめて単純です。
  46         ふたつの部分から成り立っており、
  47         アップロードを行う <acronym>HTTP</acronym> フォームとアップロードされたファイルを
  48         <classname>Zend_File_Transfer</classname> で処理するコードを作成します。
  49         次の例を参照ください。
  50     </para>
  51
  52     <example id="zend.file.transfer.introduction.example">
  53         <title>シンプルなファイルアップロードフォーム</title>
  54
  55         <para>
  56             これは、基本的なファイルアップロード処理の例です。
  57             まずはファイルアップロードフォームから。
  58             今回の例では。アップロードしたいファイルはひとつです。
  59         </para>
  60
  61         <programlisting language="xml"><![CDATA[
  62 <form enctype="multipart/form-data" action="/file/upload" method="POST">
  63     <input type="hidden" name="MAX_FILE_SIZE" value="100000" />
  64         アップロードするファイルを選択: <input name="uploadedfile" type="file" />
  65     <br />
  66     <input type="submit" value="アップロード" />
  67 </form>
  68 ]]></programlisting>
  69
  70         <para>
  71             HTML を直接作成するのではなく、利便性を考慮して
  72             <link linkend="zend.form.standardElements.file">Zend_Form_Element_File</link>
  73             を使っていることに注意しましょう。
  74         </para>
  75
  76         <para>
  77             次はアップロードしたファイルを受け取る側です。
  78             今回の例では、受け取る側は <filename>/file/upload</filename>
  79             となります。そこで、 'file' コントローラにアクション
  80             <methodname>upload()</methodname> を作成します。
  81         </para>
  82
  83         <programlisting language="php"><![CDATA[
  84 $adapter = new Zend_File_Transfer_Adapter_Http();
  85
  86 $adapter->setDestination('C:\temp');
  87
  88 if (!$adapter->receive()) {
  89     $messages = $adapter->getMessages();
  90     echo implode("\n", $messages);
  91 }
  92 ]]></programlisting>
  93
  94         <para>
  95             このコードは <classname>Zend_File_Transfer</classname> のもっともシンプルな使用法を示すものです。
  96             ローカルの保存先を <methodname>setDestination()</methodname> メソッドで指定して
  97             <methodname>receive()</methodname> メソッドをコールします。
  98             アップロード時に何らかのエラーが発生した場合は、
  99             返された例外の中でその情報を取得できます。
 100         </para>
 101
 102     </example>
 103
 104     <note>
 105         <title>注意</title>
 106
 107         <para>
 108             この例は、<classname>Zend_File_Transfer</classname> の基本的な <acronym>API</acronym> を説明するためだけのものです。
 109             これをそのまま実際の環境で使用しては
 110             <emphasis>いけません</emphasis>。
 111             深刻なセキュリティ問題を引き起こしてしまいます。
 112             常にバリデータを使用してセキュリティを向上させるようにしなければなりません。
 113         </para>
 114     </note>
 115
 116     <sect2 id="zend.file.transfer.introduction.adapters">
 117         <title>Zend_File_Transfer がサポートするアダプタ</title>
 118
 119         <para>
 120             <classname>Zend_File_Transfer</classname> は、
 121             さまざまなアダプタと転送方向をサポートするように作られています。
 122             ファイルのアップロードやダウンロードだけでなく、転送
 123             (あるアダプタでのアップロードと別のアダプタでのダウンロードを同時に行う)
 124             にも対応できるように設計されています。
 125             しかし、Zend Framework 1.6 の時点で存在するアダプタは
 126             Http アダプタひとつだけです。
 127         </para>
 128     </sect2>
 129
 130     <sect2 id="zend.file.transfer.introduction.options">
 131         <title>Zend_File_Transfer のオプション</title>
 132
 133         <para>
 134             <classname>Zend_File_Transfer</classname> やそのアダプタはさまざまなオプションをサポートしています。
 135             オプションはコンストラクタで指定することもできますし、
 136             <methodname>setOptions($options)</methodname> で指定することもできます。
 137             <methodname>getOptions()</methodname> は、実際に設定されているオプションを返します。
 138             サポートするオプションは次のとおりです。
 139         </para>
 140
 141         <itemizedlist>
 142             <listitem>
 143                 <para>
 144                     <emphasis>ignoreNoFile</emphasis>: このオプションを <constant>TRUE</constant> にすると、
 145                     ファイルがフォームからアップロードされなかったときにバリデータは何も行いません。
 146                     このオプションの既定値は <constant>FALSE</constant> で、
 147                     この場合はファイルがアップロードされなければエラーとなります。
 148                 </para>
 149             </listitem>
 150         </itemizedlist>
 151     </sect2>
 152
 153     <sect2 id="zend.file.transfer.introduction.checking">
 154         <title>ファイルのチェック</title>
 155
 156         <para>
 157             <classname>Zend_File_Transfer</classname>
 158             のメソッドの中には、さまざまな前提条件をチェックするためのものもあります。
 159             これらは、アップロードされたファイルを処理する際に便利です。
 160         </para>
 161
 162         <itemizedlist>
 163             <listitem>
 164                 <para>
 165                     <emphasis>isValid($files = null)</emphasis>: このメソッドは、
 166                     ファイルにアタッチされたバリデータを用いてそのファイルが妥当なものかどうかを検証します。
 167                     ファイル名を省略した場合はすべてのファイルをチェックします。
 168                     <methodname>isValid()</methodname> を <methodname>receive()</methodname> の前にコールすることもできます。
 169                     この場合、<methodname>receive()</methodname> がファイルを受信する際に内部的に
 170                     <methodname>isValid()</methodname> をコールすることはありません。
 171                 </para>
 172             </listitem>
 173
 174             <listitem>
 175                 <para>
 176                     <emphasis>isUploaded($files = null)</emphasis>: このメソッドは、
 177                     指定したファイルがユーザによってアップロードされたものなのかどうかを調べます。
 178                     これは、複数のファイルを任意でアップロードできるようにする場合などに便利です。
 179                     ファイル名を省略した場合はすべてのファイルをチェックします。
 180                 </para>
 181             </listitem>
 182
 183             <listitem>
 184                 <para>
 185                     <emphasis>isReceived($files = null)</emphasis>: このメソッドは、
 186                     指定したファイルがすでに受信済みであるかどうかを調べます。
 187                     ファイル名を省略した場合はすべてのファイルをチェックします。
 188                 </para>
 189             </listitem>
 190         </itemizedlist>
 191
 192         <example id="zend.file.transfer.introduction.checking.example">
 193             <title>ファイルのチェック</title>
 194
 195             <programlisting language="php"><![CDATA[
 196 $upload = new Zend_File_Transfer();
 197
 198 // すべての既知の内部ファイル情報を返します
 199 $files = $upload->getFileInfo();
 200
 201 foreach ($files as $file => $info) {
 202     // アップロードされたファイルか ?
 203     if (!$upload->isUploaded($file)) {
 204         print "ファイルをアップロードしてください";
 205         continue;
 206     }
 207
 208     // バリデータを通過したか ?
 209     if (!$upload->isValid($file)) {
 210         print "$file は不適切です";
 211         continue;
 212     }
 213 }
 214
 215 $upload->receive();
 216 ]]></programlisting>
 217
 218         </example>
 219     </sect2>
 220
 221     <sect2 id="zend.file.transfer.introduction.informations">
 222         <title>さらなるファイル情報</title>
 223
 224         <para>
 225             <classname>Zend_File_Transfer</classname> は、ファイルについてのさらなる情報を返すことができます。
 226             次のメソッドが使用可能です。
 227         </para>
 228
 229         <itemizedlist>
 230             <listitem>
 231                 <para>
 232                     <emphasis>getFileName($file = null, $path = true)</emphasis>:
 233                     このメソッドは、転送されたファイルの実際のファイル名を返します。
 234                 </para>
 235             </listitem>
 236
 237             <listitem>
 238                 <para>
 239                     <emphasis>getFileInfo($file = null)</emphasis>:
 240                     このメソッドは、転送されたファイルのすべての内部情報を返します。
 241                 </para>
 242             </listitem>
 243
 244             <listitem>
 245                 <para>
 246                     <emphasis>getFileSize($file = null)</emphasis>:
 247                     このメソッドは、指定したaifるの実際のファイルサイズを返します。
 248                 </para>
 249             </listitem>
 250
 251             <listitem>
 252                 <para>
 253                     <emphasis>getHash($hash = 'crc32', $files = null)</emphasis>:
 254                     このメソッドは、転送されたファイルの内容のハッシュを返します。
 255                 </para>
 256             </listitem>
 257
 258             <listitem>
 259                 <para>
 260                     <emphasis>getMimeType($files = null)</emphasis>:
 261                     このメソッドは、転送されたファイルの mimetype を返します。
 262                 </para>
 263             </listitem>
 264         </itemizedlist>
 265
 266         <para>
 267             <methodname>getFileName()</methodname> の最初のパラメータには、
 268             要素の名前を渡すことができます。名前を省略した場合は、
 269             すべてのファイル名を配列で返します。
 270             multifile 形式であった場合も結果は配列となります。
 271             ファイルがひとつだけだった場合は結果を文字列で返します。
 272         </para>
 273
 274         <para>
 275             デフォルトでは、ファイル名はフルパス形式で返されます。
 276             パス抜きのファイル名だけがほしい場合は、2 番目のパラメータ
 277             <code>$path</code> を設定します。これを <constant>FALSE</constant>
 278             にするとパスの部分を取り除いた結果を返します。
 279         </para>
 280
 281         <example id="zend.file.transfer.introduction.informations.example1">
 282             <title>ファイル名の取得</title>
 283
 284             <programlisting language="php"><![CDATA[
 285 $upload = new Zend_File_Transfer();
 286 $upload->receive();
 287
 288 // すべてのファイルのファイル名を返します
 289 $names = $upload->getFileName();
 290
 291 // フォームの 'foo' 要素のファイル名を返します。
 292 $names = $upload->getFileName('foo');
 293 ]]></programlisting>
 294
 295         </example>
 296
 297         <note>
 298             <para>
 299                 ファイルを受信する際にファイル名が変わることがあることに注意しましょう。
 300                 これは、ファイルを受信した後ですべてのフィルタが適用されるからです。
 301                 <methodname>getFileName()</methodname> をコールするのは、ファイルを受信してからでなければなりません。
 302             </para>
 303         </note>
 304
 305         <para>
 306             <methodname>getFileSize()</methodname> は、デフォルトではファイルサイズを SI 記法で返します。
 307             つまり、たとえば <emphasis>2048</emphasis> ではなく <emphasis>2kB</emphasis>
 308             のようになるということです。単にサイズだけが知りたい場合は、オプション
 309             <property>useByteString</property> を <constant>FALSE</constant> に設定してください。
 310         </para>
 311
 312         <example id="zend.file.transfer.introduction.informations.example.getfilesize">
 313             <title>ファイルのサイズの取得</title>
 314
 315             <programlisting language="php"><![CDATA[
 316 $upload = new Zend_File_Transfer();
 317 $upload->receive();
 318
 319 // 複数のファイルがアップロードされた場合は、すべてのファイルのサイズを配列で返します
 320 $size = $upload->getFileSize();
 321
 322 // SI 記法を無効にし、数値のみを返すようにします
 323 $upload->setOption(array('useByteString' => false));
 324 $size = $upload->getFileSize();
 325 ]]></programlisting>
 326
 327         </example>
 328
 329         <note>
 330             <title>Client given filesize</title>
 331
 332             <para>
 333                 Note that the filesize which is given by the client is not seen as save input.
 334                 Therefor the real size of the file will be detected and returned instead of the
 335                 filesize sent by the client.
 336             </para>
 337         </note>
 338
 339         <para>
 340             <methodname>getHash()</methodname> の最初のパラメータには、ハッシュアルゴリズムの名前を指定します。
 341             使用できるアルゴリズムについては
 342             <ulink url="http://php.net/hash_algos">PHP の hash_algos メソッド</ulink>
 343             を参照ください。アルゴリズムを省略した場合は
 344             <emphasis>crc32</emphasis> をデフォルトのアルゴリズムとして使用します。
 345         </para>
 346
 347         <example id="zend.file.transfer.introduction.informations.example2">
 348             <title>ファイルのハッシュの取得</title>
 349
 350             <programlisting language="php"><![CDATA[
 351 $upload = new Zend_File_Transfer();
 352 $upload->receive();
 353
 354 // 複数のファイルがアップロードされた場合は、すべてのファイルのハッシュを配列で返します
 355 $hash = $upload->getHash('md5');
 356
 357 // フォームの 'foo' 要素のハッシュを返します。
 358 $names = $upload->getHash('crc32', 'foo');
 359 ]]></programlisting>
 360
 361         </example>
 362
 363         <note>
 364             <title>返り値</title>
 365
 366             <para>
 367                 複数のファイルを指定した場合は、返される結果が配列となることに注意しましょう。
 368             </para>
 369         </note>
 370
 371         <para>
 372             <methodname>getMimeType()</methodname> はファイルの mimetype を返します。
 373             複数のファイルがアップロードされた場合は配列、そうでない場合は文字列を返します。
 374         </para>
 375
 376         <example id="zend.file.transfer.introduction.informations.getmimetype">
 377             <title>ファイルの mimetype の取得</title>
 378
 379             <programlisting language="php"><![CDATA[
 380 $upload = new Zend_File_Transfer();
 381 $upload->receive();
 382
 383 $mime = $upload->getMimeType();
 384
 385 // フォーム要素 'foo' の mimetype を返します
 386 $names = $upload->getMimeType('foo');
 387 ]]></programlisting>
 388
 389         </example>
 390
 391         <note>
 392             <title>Client given mimetype</title>
 393
 394              <para>
 395                 Note that the mimetype which is given by the client is not seen as save input.
 396                 Therefor the real mimetype of the file will be detected and returned instead of the
 397                 mimetype sent by the client.
 398             </para>
 399         </note>
 400
 401         <warning>
 402             <title>ありえる例外</title>
 403
 404             <para>
 405                 このメソッドは、fileinfo 拡張モジュールが使用可能な場合はそれを使用することに注意しましょう。
 406                 この拡張モジュールがみつからなかった場合は、mimemagic 拡張モジュールを使用します。
 407                 それもみつからなかった場合は、例外を発生します。
 408             </para>
 409         </warning>
 410
 411         <warning>
 412             <title>Original data within $_FILES</title>
 413
 414             <para>
 415                 Due to security reasons also the original data within $_FILES will be overridden
 416                 as soon as <classname>Zend_File_Transfer</classname> is initiated. When you want
 417                 to omit this behaviour and have the original data simply set the
 418                 <property>detectInfos</property> option to <constant>FALSE</constant> at initiation.
 419             </para>
 420
 421             <para>
 422                 This option will have no effect after you initiated
 423                 <classname>Zend_File_Transfer</classname>.
 424             </para>
 425         </warning>
 426
 427     </sect2>
 428
 429     <sect2 id="zend.file.transfer.introduction.uploadprogress">
 430         <title>ファイルアップロードの進捗</title>
 431
 432         <para>
 433             <classname>Zend_File_Transfer</classname> では、ファイルアップロードの進捗状況を知ることができます。
 434             この機能を使用するには、<acronym>APC</acronym> 拡張モジュール
 435             (ほとんどの <acronym>PHP</acronym> 環境においてデフォルトで提供されています)
 436             あるいは <classname>uploadprogress</classname> 拡張モジュールが必要です。
 437             これらの拡張モジュールがインストールされていれば、自動検出してそれを使用します。
 438             進捗状況を取得するには、いくつかの事前条件があります。
 439         </para>
 440
 441         <para>
 442             まず、<acronym>APC</acronym> あるいは <classname>uploadprogress</classname>
 443             のいずれかを有効にする必要があります。<acronym>APC</acronym>
 444             の機能は <filename>php.ini</filename> で無効化できることに注意しましょう。
 445         </para>
 446
 447         <para>
 448             次に、ファイルを送信するフォームの中に適切な hidden
 449             フィールドを追加しなければなりません。<classname>Zend_Form_Element_File</classname>
 450             を使う場合は、この hidden フィールドは
 451             <classname>Zend_Form</classname> が自動的に追加します。
 452         </para>
 453
 454         <para>
 455             これらふたつの条件さえ満たせば、ファイルアップロードの進捗状況を
 456             <code>getProgress</code> メソッドで取得できます。
 457             実際には、これを処理する公式な方法は 2 通りあります。
 458         </para>
 459
 460         <sect3 id="zend.file.transfer.introduction.uploadprogress.progressadapter">
 461
 462             <title>progressbar アダプタを使用する</title>
 463
 464             <para>
 465                 <emphasis>Zend_ProgressBar</emphasis> を使用して、
 466                 実際の進捗状況を取得した上でそれをシンプルにユーザに見せることができます。
 467             </para>
 468
 469             <para>
 470                 そのためには、<methodname>getProgress()</methodname> を最初にコールするときにお望みの
 471                 <emphasis>Zend_ProgressBar_Adapter</emphasis> を追加しなければなりません。
 472                 どのアダプタを使用すればいいのかについては
 473                 <link linkend="zend.progressbar.adapters">Zend_ProgressBar の標準のアダプタ</link>
 474                 の章を参照ください。
 475             </para>
 476
 477             <example id="zend.file.transfer.introduction.uploadprogress.progressadapter.example1">
 478                 <title>progressbar アダプタを使用した実際の状態の取得</title>
 479
 480                 <programlisting language="php"><![CDATA[
 481 $adapter = new Zend_ProgressBar_Adapter_Console();
 482 $upload  = Zend_File_Transfer_Adapter_Http::getProgress($adapter);
 483
 484 $upload = null;
 485 while (!$upload['done']) {
 486     $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
 487 }
 488 ]]></programlisting>
 489
 490             </example>
 491
 492             <para>
 493                 完全な処理は、バックグラウンドで <methodname>getProgress()</methodname> によって行われます。
 494             </para>
 495
 496         </sect3>
 497
 498         <sect3 id="zend.file.transfer.introduction.uploadprogress.manually">
 499             <title>getProgress() を手動で使用する</title>
 500
 501             <para>
 502                 <classname>Zend_ProgressBar</classname> を使わずに手動で
 503                 <methodname>getProgress()</methodname> を動作させることもできます。
 504             </para>
 505
 506             <para>
 507                 <methodname>getProgress()</methodname> を何も設定なしでコールします。
 508                 すると、いくつかのキーを含む配列が返されます。
 509                 使用している <acronym>PHP</acronym> 拡張モジュールによってその内容は異なります。
 510                 しかし、次のキーは拡張モジュールにかかわらず返されます。
 511             </para>
 512
 513             <itemizedlist>
 514                 <listitem>
 515                     <para>
 516                         <emphasis>id</emphasis>:
 517                         このアップロードの ID。その拡張モジュール内でのアップロードを一意に識別します。
 518                         自動的に設定され、この値は決して変更することができません。
 519                     </para>
 520                 </listitem>
 521
 522                 <listitem>
 523                     <para>
 524                         <emphasis>total</emphasis>:
 525                         アップロードされたファイル全体のサイズをバイト単位で表した整数値。
 526                     </para>
 527                 </listitem>
 528
 529                 <listitem>
 530                     <para>
 531                         <emphasis>current</emphasis>:
 532                         現在までにアップロードされたファイルサイズをバイト単位で表した整数値。
 533                     </para>
 534                 </listitem>
 535
 536                 <listitem>
 537                     <para>
 538                         <emphasis>rate</emphasis>:
 539                         アップロードの平均速度を「バイト/秒」単位で表した整数値。
 540                     </para>
 541                 </listitem>
 542
 543                 <listitem>
 544                     <para>
 545                         <emphasis>done</emphasis>:
 546                         アップロードが終了したときは <constant>TRUE</constant> 、
 547                         そうでなければ <constant>FALSE</constant> を返します。
 548                     </para>
 549                 </listitem>
 550
 551                 <listitem>
 552                     <para>
 553                         <emphasis>message</emphasis>:
 554                         実際のメッセージ。進捗を <emphasis>10kB / 200kB</emphasis>
 555                         形式で表したテキストか、何か問題が起こった場合には有用なメッセージとなります。
 556                         「問題」とは、何もアップロード中でない場合や
 557                         進捗状況の取得に失敗した場合、あるいはアップロードがキャンセルされた場合を意味します。
 558                     </para>
 559                 </listitem>
 560
 561                 <listitem>
 562                     <para>
 563                         <emphasis>progress</emphasis>:
 564                         このオプションキーには <classname>Zend_ProgressBar_Adapter</classname> あるいは
 565                         Zend_ProgressBar のインスタンスが含まれ、
 566                         プログレスバー内から実際のアップロード状況を取得できるようになります。
 567                     </para>
 568                 </listitem>
 569
 570                 <listitem>
 571                     <para>
 572                         <emphasis>session</emphasis>:
 573                         このオプションキーには <classname>Zend_ProgressBar</classname>
 574                         内で使用するセッション名前空間の名前が含まれます。
 575                         このキーが与えられなかったときのデフォルトは
 576                         <classname>Zend_File_Transfer_Adapter_Http_ProgressBar</classname> です。
 577                     </para>
 578                 </listitem>
 579             </itemizedlist>
 580
 581             <para>
 582                 それ以外に返されるキーについては各拡張モジュールが直接返すものであり、
 583                 チェックしていません。
 584             </para>
 585
 586             <para>
 587                 次の例は、手動で使用する方法を示すものです。
 588             </para>
 589
 590             <example id="zend.file.transfer.introduction.uploadprogress.manually.example1">
 591                 <title>手動での進捗状況表示の使用法</title>
 592
 593                 <programlisting language="php"><![CDATA[
 594 $upload  = Zend_File_Transfer_Adapter_Http::getProgress();
 595
 596 while (!$upload['done']) {
 597     $upload = Zend_File_Transfer_Adapter_Http:getProgress($upload);
 598     print "\nActual progress:".$upload['message'];
 599     // 何か必要な処理をします
 600 }
 601 ]]></programlisting>
 602
 603             </example>
 604
 605         </sect3>
 606     </sect2>
 607 </sect1>
 608 <!--
 609 vim:se ts=4 sw=4 tw=80 et:
 610 -->