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:
read
(
string
$url
,
string
$symbolic = null
,
integer
$uncompression = 0
,
integer
$directoryDepth = -0
)
In this function the URL will represent what you want to read.
Generation of sources
<?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 compressed files that may appear in
$URLare not taken into account by$uncompressionvariable.
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.
Multi reader
<?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
falsewhen 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
-
$lengthif$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.
Listing the content of a 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:
Multi reader
<?php
//This reader contains the content of directory and archive.tar
File_Archive::extract(
array(
'directory',
'archive.tar/'
),
File_Archive::toArchive('test.zip')
);
?>