リーダー

導入

リーダーは、ファイルやディレクトリの一覧を表すオブジェクトです。 これらのファイルは動的に作成することもできますし、 既存の物理ファイルを使用することもできます。 たとえば、ディレクトリ用のリーダークラスや File_Archive がサポートする各種アーカイブ形式を処理するためのリーダーがあります。 そして、それぞれが同じインターフェイスを持っています。

リーダーを作成するには File_Archive ファクトリを使用します。 重要な関数は read() 関数です。

この関数の URL が、読み込みたい内容を表します。

<?php
require_once "File/Archive.php";

/*
ディレクトリを読み込むにはディレクトリ名を指定します。
デフォルトでは、そのディレクトリだけでなくすべてのサブディレクトリも
パースします (これを変更するには $directoryDepth を参照ください)
*/
$source = File_Archive::read("Path/to/dir");

/*
単一のファイルから読み込むには
そのファイルの名前を指定します。
*/
$source = File_Archive::read("Path/to/dir/file.txt");

/*
アーカイブの後にスラッシュを続けると、ディレクトリとみなされます。
この例は、アーカイブ Path/to/dir/archive.tar の内部のディレクトリ inner/dir
の中身を読み込みます。これは、archive.tar の inner ディレクトリにある
すべての .txt ファイルを読み込みます。
*/
$source = File_Archive::read("Path/to/dir/archive.tar/inner/*.txt");

/*
アーカイブの内容を伸長したい (すｂての中身を読み込みたい)
場合はこのようにします。
注意: 最後の / を忘れると、アーカイブそのものが単一のファイルとして扱われてしまいます
*/
$source = File_Archive::read("Path/to/dir/archive.tar/");
?>

symbolic 属性は、 読み込んだファイルを後でどのように表示するかを表します。 $URL がディレクトリの場合は、$URL が $symbolic ($symbolic が null の場合は '') で置き換えられます。 したがって、最初の例では、カレントディレクトリが 'Path/to/dir' であるかのようにファイルが表示されます。 デフォルトでは $symbolic は空なので、 Path/to/dir がファイル名から取り除かれます。 Path/to/dir を $symbolic に設定すれば、フルパス Path/to/dir を保持できます。

$URL がファイルの場合は、ファイル名のみが保持されて $symbolic がそこに付け加えられます。 つまり、2 番目の例では、元ファイル名は file.txt となります。 シンボリック名 foo を指定すると、 これは foo/file.txt となります。

$uncompression パラメータは、 ツリーをファイルにパースする際に何個のファイルを伸長するかを表します。 デフォルトでは伸長は行いません。したがって、 File_Archive::read('archive.tar/inner/dir', 'inner/dir') を実行した際に archive.tar の中にもし archive.tar/inner/dir/file.tgz というファイルがあれば、 この第二のアーカイブはディレクトリではなくファイルとして扱われます。 $uncompression が 0 であるため、このアーカイブは伸長されないのです。 $uncompression を 1 にすると、 file.tgz はディレクトリとして扱われます。 しかし、このアーカイブの中のファイルは伸長されません。 $uncompression を -1 にすると、 何段階でもすべてのファイルを伸長します。

$directoryDepth パラメータは、 そのリーダーが読み込むディレクトリ数の制限値を指定します。

マルチリーダー

マルチリーダーを使用すると、複数のソースをひとつにまとめることができます。 マルチリーダーを作成するには File_Archive::readMulti() 関数を使用します。

<?php
// このリーダーには、ディレクトリの内容と archive.tar が含まれます
$source = File_Archive::readMulti(
    array(
        File_Archive::read('directory'),
        File_Archive::read('archive.tar/')
    )
);
?>

データリーダーの中身の読み込み

すべてのリーダーは、次のようなインターフェイスを提供しています。

• function next()

  ソース内の次のファイルに移動します。アーカイブの末尾に達したときに false を返します。

• function getFilename()

  アーカイブ内で現在選択されているエントリのファイル名を返します。

• function getStat()

  stat() 関数と同様の値を返します。 完全な配列を返すとは限りません。array() を返す可能性もあります。

• function getDataFilename()

  最適化用に使用します。ソースが物理ファイルの場合にファイル名を、 それ以外の場合に null を返します。

• function getData($length = -1)

  データをソースから読み込みます。 この関数は文字列を返します。その大きさは、以下のうちもっとも小さいものです。

  • $length >= 0 の場合の $length

  • ファイルの終端

  ファイルの終端に達した場合は、この関数は null を返します。

• function skip($length)

  getData($length) と同じですが、データを返しません。 データリーダーの種類によっては、この関数のほうが getData() よりもずっと効率的です。

• function close()

  データリーダを使い終えた (ファイルハンドルのクローズなど...) 後でコールしなければなりません。 この関数は、最初に next() をコールする前の状態に戻します。 これをコールすると、データリーダーを再度処理できるようになります。

<?php
$source->close(); // ソースの先頭に戻ります

while($source->next()) {
    echo $source->getFilename() . "<br/>\n";
}
?>

リーダーを使用する関数

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

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

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

<?php
// このリーダーには、ディレクトリの内容と archive.tar が含まれます
File_Archive::extract(
    array(
        'directory',
        'archive.tar/'
    ),
    File_Archive::toArchive('test.zip')
);
?>