Readers

Introduction

A reader is an object that represents a list of files and directories. Those files can be generated dynamically or exist physically. For example, there is a reader class for a directory, or for each archive format handled by File_Archive, and they all have the same interface.

To create a reader, you will have to use the File_Archive factory. The important function is the read() function:

In this function the URL will represent what you want to read.

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

/*
To read a directory, just give the directory name
By default, the directory and all the subdirectories
will be parsed (see $directoryDepth to change this)
*/
$source = File_Archive::read("Path/to/dir");

/*
To read from one single file,
simply provide the name of the file
*/
$source = File_Archive::read("Path/to/dir/file.txt");

/*
An archive will be considered as a directory if a slash follows
This example reads the directory and all the subdirectories of inner/dir
contained in archive Path/to/dir/archive.tar
This reads all the .txt files in the inner directory of the archive.tar
*/
$source = File_Archive::read("Path/to/dir/archive.tar/inner/*.txt");

/*
If you want to uncompress the archive (read all its content)
Note: if you ommit the trailing /, the archive will be treated as a single file
*/
$source = File_Archive::read("Path/to/dir/archive.tar/");
?>

The symbolic attribute says how the files read will be displayed for future use. If $URL is a directory, $URL will be replaced by $symbolic (or '' if $symbolic is null). So, in our first example, the files will be displayed as if the current directory was 'Path/to/dir': Since by default $symbolic is empty, Path/to/dir will be simply removed from the file. You may want to put Path/to/dir as $symbolic to keep the full path Path/to/dir.

If $URL is a file, then only the filename will be kept, and $symbolic will be added to it. So, in our second example, the source contains a file with symbolic name file.txt. If a symbolic name foo had been specified, the source would contain foo/file.txt.

The $uncompression parameter indicate how many files will be uncompressed while parsing the tree to files. By default the files are not uncompressed. So, if you do File_Archive::read('archive.tar/inner/dir', 'inner/dir'), and if archive.tar contains a file called archive.tar/inner/dir/file.tgz, this second archive will appear as a file and not as a directory. It won't be uncompressed because $uncompression is 0. If $uncompression is set to 1, file.tgz would appear as a directory, but the files inside this archive would not be uncompressed. If $uncompression is set to -1, all the files would be uncompressed, regardless of the depth.

The $directoryDepth parameter gives a limit to the number of directory read by the reader.

Multi readers

Using a multi reader, you can make several sources appear as one. You can create a multi reader using the File_Archive::readMulti() function.

<?php
//This reader contains the content of directory and archive.tar
$source = File_Archive::readMulti(
    array(
        File_Archive::read('directory'),
        File_Archive::read('archive.tar/')
    )
);
?>

Reading the content of a data reader

Any reader provides the following interface:

• function next()

  Go to the next file in the source. Returns false when the end of the archive is reached.

• function getFilename()

  Returns the filename of the currently selected entry in the archive.

• function getStat()

  Returns the stat as the stat() function does. This function may not return a complete array, it may even return array().

• function getDataFilename()

  For optimisation purposes: if the source is a physical file, this function returns the name of the file; otherwise it returns null.

• function getData($length = -1)

  Reads some data from the source. This function will return a string which size is determined by the smallest of

  • $length if $length >= 0

  • the end of the file.

  If the end of the file is reached, the function will return null.

• function skip($length)

  Equivalent to getData($length), but does not return any data. Depending on the data reader, this function can be far more efficient than getData().

• function close()

  Should be called after having used the data reader (closes the file handles...). This function moves the object in the same state as it was before the first call to next(). After this call, you can iterate again on the data reader.

<?php
$source->close(); //Move back to the begining of the source

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

Functions that use readers

All File_Archive functions that take a reader as an argument also accept strings and arrays. The strings will be automatically interpreted as a reader using File_Archive::read function. The arrays will be interpreted as a multi reader.

Since the readers are passed by reference, you will have to pass a variable and not the raw string or array.

It is thus possible to rewrite the previous example like that:

<?php
//This reader contains the content of directory and archive.tar
File_Archive::extract(
    array(
        'directory',
        'archive.tar/'
    ),
    File_Archive::toArchive('test.zip')
);
?>