ライターは、データを扱うオブジェクトです。 データを変換する (アーカイブライターの場合) ライターもあれば、ディスクに保存する (ファイルライターの場合) ものやメモリに保存する (メモリライターの場合) もあります。これらはみな同じインターフェイスを実装しています。

リーダーからのデータをライターに移すには File_Archive::extract 関数を使用します。

すべてのライターは File_Archive ファクトリで作成されます。 より正確に言うと、File_Archive::to* 関数を使用します。

アーカイブを生成するライターは、 toArchive() 関数で作成します。

• $filename は、生成されるアーカイブの名前です。

• $innerWriter は、アーカイブファイルを書き込む別のライターです。

• $type は Tar か Gzip、Zip のいずれかで、 圧縮方式を表します。指定しなかった場合は、 ファイル名の拡張子から判断します。

• $stat はオプションの配列で、 アーカイブに関する状態を表します (使用できるインデックスについては PHP の stat 関数を参照ください)。

• $autoClose は、 データを送信した後に内部のライターをクローズするかどうかを表します。 書き込んだ後に何らかのデータを追記したいのなら、 ライターをクローズしないほうが便利でしょう。 一般には、ライターをオープンし続ける必要はありません。 したがって、デフォルト値のままにしておくことになります。

ライターは、ファイルの内容を物理ファイルに書き込むことができます。 そのようなライターを作成するには File_Archive::toFiles(); をコールします。ディレクトリが存在しない場合は自動的に作成します。

メールの添付ファイルとして送信するには、 File_Archive::toMail 関数でメールライターを作成します。

この関数は PEAR の Mail および Mail_Mime ライブラリを使用しており、 パラメータはこれらのクラスと同じです。

• $to は、配列あるいはカンマ区切りの文字列で受信者を指定します。

• $headers は Mail_Mime と $mail に送られる、ヘッダの連想配列です。ヘッダの名前が連想配列のキー、 ヘッダの値が連想配列の値となります。

• $message はメールの本文にあたるテキストです。 HTML 形式にするには、ライターの setHTMLBody() および addHTMLImage() を使用します。これらの関数のシグネチャは Mail_Mime のものと同じです。

• $mail はメールを送る方法です。 Mail::factory() 関数で作成したオブジェクトを使用します。 null の場合は Mail::factory('mail') を使用します (そして、PHP の mail 関数を用いてメールを送信します)。

ファイルをリモートユーザに送信する (つまり、データを標準出力に送る) には、特別なライターが必要です。これは、関数 File_Archive::toOutput() をコールして作成します。

このライターは、ファイルをダウンロードさせるようなヘッダを自動的に送信します。

ヘッダを送信させたくない場合は File_Archive::toOutput(false) とコールします。

マルチライターを使用すれば、 ふたつ以上の場所にデータを平行に書き出すことができます。

典型的な使用法は、ユーザ向けにデータを送信すると同時にファイルにも書き出すといったものです。

また、複数の形式のアーカイブを作成する際にも使用できます。

マルチライターを作成するには File_Archive::toMulti($dest1, $dest2) を使用します。

リーダーを使わずに、データを直接ライターに書き込むこともできます。 そのためには、各ライターが実装している以下のインターフェイスを使用します。

• function newFile($URL, $stat)

  ライター内に新しいファイルを作成します。

  $URL はファイルの名前、 $stat はデータについての情報の配列 (詳細は PHP の stat() 関数を参照ください) です。

  情報の配列にはすべての情報を含める必要はありません。 必須なのは、インデックス 7 (データのサイズ) だけです。

• function writeData($data)

  指定したデータをライターに追記します。 事前に newFile() をコールしておく必要があります。

• function close()

  ライターをクローズし、データをフラッシュし、 そしてフッターを書き出します。 この関数は、ファイルの終端に達する前にコールしなければなりません。 そうしないとライターがデータを取りこぼしてしまうかもしれません。

newFile() 関数で情報の配列を指定しない場合は、 ファイルの終端に達するまでアーカイブの大半のデータをバッファリングする必要が生じます (通常は、ファイルのサイズがわからなければヘッダを書き込めないからです)。

巨大なファイルを扱う際には、これはメモリの問題を引き起こす可能性があります。

引数としてライターを受け取る File_Archive のすべての関数は、文字列および配列の両方の形式を受け付けます。 文字列は、File_Archive::appender() 関数を用いて自動的にライターとして解釈されます。 配列はマルチライターと解釈されます。

ライターは参照渡しとなるので、生の文字列や配列ではなく変数を渡す必要があります。

したがって、先ほどの例は次のように書き換えることもできます。