Docs For Class File

File_Archive_Writer appender(

$URL, [
$unique = null], [
$type = null], [
$stat = array()], File_Archive_Reader
$source)

Create a writer that allows appending new files to an existing archive This function actes as appendToSource with source being the system files $URL can't be null here

Return: a writer that you can use to append files to the reader

Parameters:

File_Archive_Reader	`$source`	—	A reader where some files will be appended
	`$URL`	—
	`$unique`	—
	`$type`	—
	`$stat`	—

[ Top ]

File_Archive_Writer appenderFromSource(

&$toConvert, [string
$URL = null], [bool
$unique = null], [string
$type = null], [array
$stat = array()], File_Archive_Reader
$source)

Create a writer that can be used to append files to an archive inside a source

If the archive can't be found in the source, it will be created If source is set to null, File_Archive::toFiles will be assumed If type is set to null, the type of the archive will be determined looking at the extension in the URL stat is the array of stat (returned by stat() PHP function of Reader getStat()) to use if the archive must be created

This function allows to create or append data to nested archives. Only one archive will be created and if your creation requires creating several nested archives, a PEAR error will be returned

After this call, $source will be closed and should not be used until the returned writer is closed.

Return: a writer that you can use to append files to the reader

Parameters:

File_Archive_Reader	`$source`	—	A reader where some files will be appended
string	`$URL`	—	URL to reach the archive in the source. if $URL is null, a writer to append files to the $source reader will be returned
bool	`$unique`	—	If true, the duplicate files will be deleted on close Default is false (and setting it to true may have some performance consequences)
string	`$type`	—	Extension of the archive (or null to use the one in the URL)
array	`$stat`	—	Used only if archive is created, array of stat as returned by PHP stat function or Reader getStat function: stats of the archive) Time (index 9) will be overwritten to current time
	`&$toConvert`	—

[ Top ]

void cache(

&$toConvert, mixed
$toConvert)

Adds a cache layer above the specified reader The data of the reader is saved in a temporary file for future access.

The cached reader will be read only once, even if you read it several times. This can be usefull to read compressed files or downloaded files (from http or ftp)

Parameters:

mixed	`$toConvert`	—	The reader to cache It can be a File_Archive_Reader or a string, which will be converted using the read function
	`&$toConvert`	—

[ Top ]

File_Archive_Reader changeName(
Callable
$function, 
&$toConvert, File_Archive_Reader
$toConvert)

Changes the name of each file in a reader by applying a custom function The function must return false if the file is to be discarded, or the new name of the file else

Return: a new reader that contains the same files as $toConvert but with a different name

Parameters:

Callable	`$function`	—	Function called to modify the name of the file $function takes the name of the file as a parameter and returns the new name, or false if the file must be discarded
File_Archive_Reader	`$toConvert`	—	The files of this source will be modified
	`&$toConvert`	—

[ Top ]

null extract(

&$sourceToConvert, 
&$destToConvert, [bool
$autoClose = true], [int
$bufferSize = 0], File_Archive_Reader
$source, File_Archive_Writer
$dest)

File_Archive::extract($source, $dest) is equivalent to $source->extract($dest)

If $source is a PEAR error, the error will be returned It is thus easier to use this function than $source->extract, since it reduces the number of error checking and doesn't force you to define a variable $source

You may use strings as source and dest. In that case the source is automatically converted to a reader using File_Archive::read and the dest is converted to a writer using File_Archive::appender Since PHP doesn't allow to pass literal strings by ref, you will have to use temporary variables. File_Archive::extract($src = 'archive.zip/', $dest = 'dir') will extract the archive to 'dir' It is the same as File_Archive::extract( File_Archive::read('archive.zip/'), File_Archive::appender('dir') ); You may use any variable in the extract function ($from/$to, $a/$b...).

Return: or a PEAR error if an error occured

Parameters:

File_Archive_Reader	`$source`	—	The source that will be read
File_Archive_Writer	`$dest`	—	Where to copy $source files
bool	`$autoClose`	—	if true (default), $dest will be closed after the extraction
int	`$bufferSize`	—	Size of the buffer to use to move data from the reader to the buffer If $bufferSize <= 0 (default), the blockSize option is used You shouldn't need to change that
	`&$sourceToConvert`	—
	`&$destToConvert`	—

[ Top ]

void filter(
File_Archive_Predicate
$predicate, 
&$toConvert, File_Archive_Reader
$source)

Removes from a source the files that do not follow a given predicat

See: File_Archive_Reader_Filter

Parameters:

File_Archive_Predicate	`$predicate`	—	Only the files for which $predicate->isTrue() will be kept
File_Archive_Reader	`$source`	—	Source that will be filtered
	`&$toConvert`	—

[ Top ]

void getOption(

$name)

Retrieve the value of an option

Parameters:

$name —

[ Top ]

bool isKnownExtension(
string
$extension)

Check if a file with a specific extension can be read as an archive with File_Archive::read* This function is case sensitive.

Return: whether this file can be understood reading its extension Currently, supported extensions are tar, zip, jar, gz, tgz, tbz, bz2, bzip2, ar, deb

Parameters:

string $extension — the checked extension

[ Top ]

void predAnd(
File_Archive_Predicate
0)

Predicate that evaluates to the logical AND of the parameters You can add other predicates thanks to the File_Archive_Predicate_And::addPredicate() function

See: File_Archive_Predicate_And

Parameters:

File_Archive_Predicate 0 — (any number of them)

[ Top ]

void predCustom(
string
$expression)

Custom predicate built by supplying a string expression

Here are different ways to create a predicate that keeps only files with names shorter than 100 chars <sample> File_Archive::predCustom("return strlen($name)<100;") File_Archive::predCustom("strlen($name)<100;") File_Archive::predCustom("strlen($name)<100") File_Archive::predCustom("strlen($source->getFilename())<100") </sample>

See: File_Archive_Predicate_Custom

Parameters:

string $expression — String containing an expression that evaluates to a boolean. If the expression doesn't contain a return statement, it will be added at the begining of the expression A ';' will be added at the end of the expression so that you don't have to write it. You may use the $name variable to refer to the current filename (with path...), $time for the modification time (unix timestamp), $size for the size of the file in bytes, $mime for the MIME type of the file

[ Top ]

void predEreg(
string
$ereg)

Evaluates to true iif the name of the file follow a given regular expression

See: File_Archive_Predicate_Ereg, ereg()
Deprecated: Make use of predPreg instead for PHP 5.3+ compatability

Parameters:

string $ereg — regular expression that the filename must follow

[ Top ]

void predEregi(
string
$ereg)

Evaluates to true iif the name of the file follow a given regular expression (case insensitive version)

See: File_Archive_Predicate_Eregi, eregi
Deprecated: Make use of predPreg instead for PHP 5.3+ compatability

Parameters:

string $ereg — regular expression that the filename must follow

[ Top ]

void predExtension(
array
$list)

Evaluates to true iif the extension of the file is in a given list

See: File_Archive_Predicate_Extension

Parameters:

array $list — or string $list List or comma separated string of possible extension of the files

[ Top ]

void predFalse(
)

Predicate that always evaluate to false

See: File_Archive_Predicate_False

[ Top ]

void predIndex(
array
$indexes)

Evaluates to true only after a given number of evaluations This can be used to select files by index since the evaluation is done once per file

Parameters:

array $indexes — The indexes for which the returned predicate will return true are the keys of the array The predicate will return true if isset($indexes[$pos])

[ Top ]

void predMaxDepth(
int
$depth)

Evaluates to true iif the file has less that a given number of directories in its path

See: File_Archive_Predicate_MaxDepth

Parameters:

int $depth — Maximal number of directories in path of the files

[ Top ]

void predMIME(
array
$list)

Evaluates to true iif the MIME type of the file is in a given list

See: File_Archive_Predicate_MIME, MIME_Type::isWildcard()

Parameters:

array $list — or string $list List or comma separated string of possible MIME types of the files. You may enter wildcards like "image/*" to select all the MIME in class image

[ Top ]

void predMinSize(
int
$size)

Evaluates to true iif the file is larger than a given size

See: File_Archive_Predicate_MinSize

Parameters:

int $size — the minimal size of the files (in Bytes)

[ Top ]

void predMinTime(
int
$time)

Evaluates to true iif the file has been modified after a given time

See: File_Archive_Predicate_MinTime

Parameters:

int $time — Unix timestamp of the minimal modification time of the files

[ Top ]

void predNot(
File_Archive_Predicate
$pred)

Negate a predicate

See: File_Archive_Predicate_Not

Parameters:

File_Archive_Predicate $pred — Predicate to negate

[ Top ]

void predOr(
File_Archive_Predicate
0)

Predicate that evaluates to the logical OR of the parameters You can add other predicates thanks to the File_Archive_Predicate_Or::addPredicate() function

See: File_Archive_Predicate_Or

Parameters:

File_Archive_Predicate 0 — (any number of them)

[ Top ]

void predPreg(
string
$preg)

Evaluates to true iif the name of the file follow a given regular expression

See: File_Archive_Predicate_Preg, preg_match()

Parameters:

string $preg — regular expression that the filename must follow

[ Top ]

void predTrue(
)

Predicate that always evaluate to true

See: File_Archive_Predicate_True

[ Top ]

void read(

$URL, [
$symbolic = null], [
$uncompression = 0], [
$directoryDepth = -1])

Parameters:

	`$URL`	—
	`$symbolic`	—
	`$uncompression`	—
	`$directoryDepth`	—

[ Top ]

A readArchive(
string
$extension, 
&$toConvert, [bool
$sourceOpened = false], File_Archive_Reader
$source)

Create a reader that will read the single file source $source as a specific archive

Return: File_Archive_Reader that uncompresses the archive contained in $source interpreting it as a $extension archive If $extension is not handled return false

Parameters:

string	`$extension`	—	determines the kind of archive $source contains $extension is case sensitive
File_Archive_Reader	`$source`	—	stores the archive
bool	`$sourceOpened`	—	specifies if the archive is already opened if false, next will be called on source Closing the returned archive will close $source iif $sourceOpened is true
	`&$toConvert`	—

[ Top ]

void readConcat(

&$toConvert, string
$filename, [array
$stat = array()], [string
$mime = null], File_Archive_Reader
$toConvert)

Make the files of a source appear as one large file whose content is the concatenation of the content of all the files

See: File_Archive_Reader_Concat

Parameters:

File_Archive_Reader	`$toConvert`	—	The source whose files must be concatened
string	`$filename`	—	name of the only file of the created reader
array	`$stat`	—	statistics of the file. Index 7 (size) will be overwritten to match the total size of the files
string	`$mime`	—	mime type of the file. Default will determine the mime type thanks to the extension of $filename
	`&$toConvert`	—

[ Top ]

void readMemory(
string
$memory, string
$filename, [array
$stat = array()], [string
$mime = null])

Contains only one file with data read from a memory buffer

See: File_Archive_Reader_Memory

Parameters:

string	`$memory`	—	content of the file
string	`$filename`	—	public name of the file
array	`$stat`	—	statistics of the file. Index 7 (size) will be overwritten to match the size of $memory
string	`$mime`	—	mime type of the file. Default will determine the mime type thanks to the extension of $filename

[ Top ]

void readMulti(
[array
$sources = array()])

Contains several other sources. Take care the sources don't have several files with the same filename. The sources are given as a parameter, or can be added thanks to the reader addSource method

See: File_Archive_Reader_Multi, File_Archive::read()

Parameters:

array $sources — Array of strings or readers that will be added to the multi reader. If the parameter is a string, a reader will be built thanks to the read function

[ Top ]

void readSource(

&$source, 
$URL, [
$symbolic = null], [
$uncompression = 0], [
$directoryDepth = -1])

Create a reader to read the URL $URL.

If the URL is a directory, it will recursively read that directory. If $uncompressionLevel is not null, the archives (files with extension tar, zip, gz or tgz) will be considered as directories (up to a depth of $uncompressionLevel if $uncompressionLevel > 0). The reader will only read files with a directory depth of $directoryDepth. It reader will replace the given URL ($URL) with $symbolic in the public filenames The default symbolic name is the last filename in the URL (or '' for directories)

Examples: Considere the following file system

 a.txt
 b.tar (archive that contains the following files)
     c.txt
     d.tgz (archive that contains the following files)
         e.txt
         dir1/
             f.txt
 dir2/
     g.txt
     dir3/
         h.tar (archive that contains the following files)
             i.txt

read('.') will return a reader that gives access to following files (recursively read current dir):

 a.txt
 b.tar
 dir2/g.txt
 dir2/dir3/h.tar

read('.', 'myBaseDir') will return the following reader:

 myBaseDir/a.txt
 myBaseDir/b.tar
 myBaseDir/dir2/g.txt
 myBaseDir/dir2/dir3/h.tar

read('.', '', -1) will return the following reader (uncompress everything)

 a.txt
 b.tar/c.txt
 b.tar/d.tgz/e.txt
 b.tar/d.tgz/dir1/f.txt
 dir2/g.txt
 dir2/dir3/h.tar/i.txt

read('.', '', 1) will uncompress only one level (so d.tgz will not be uncompressed):

 a.txt
 b.tar/c.txt
 b.tar/d.tgz
 dir2/g.txt
 dir2/dir3/h.tar/i.txt

read('.', '', 0, 0) will not recurse into subdirectories

 a.txt
 b.tar

read('.', '', 0, 1) will recurse only one level in subdirectories

 a.txt
 b.tar
 dir2/g.txt

read('.', '', -1, 2) will uncompress everything and recurse in only 2 levels in subdirectories or archives

 a.txt
 b.tar/c.txt
 b.tar/d.tgz/e.txt
 dir2/g.txt

The recursion level is determined by the real path, not the symbolic one. So read('.', 'myBaseDir', -1, 2) will result to the same files:

 myBaseDir/a.txt
 myBaseDir/b.tar/c.txt
 myBaseDir/b.tar/d.tgz/e.txt (accepted because the real depth is 2)
 myBaseDir/dir2/g.txt

Use readSource to do the same thing, reading from a specified reader instead of reading from the system files

To read a single file, you can do read('a.txt', 'public_name.txt') If no public name is provided, the default one is the name of the file read('dir2/g.txt') contains the single file named 'g.txt' read('b.tar/c.txt') contains the single file named 'c.txt'

Note: This function uncompress files reading their extension The compressed files must have a tar, zip, gz or tgz extension Since it is impossible for some URLs to use is_dir or is_file, this function may not work with URLs containing folders which name ends with such an extension

Parameters:

	`&$source`	—
	`$URL`	—
	`$symbolic`	—
	`$uncompression`	—
	`$directoryDepth`	—

[ Top ]

File_Archive_Reader readUploadedFile(
string
$name)

Create a file reader on an uploaded file. The reader will read $_FILES[$name]['tmp_name'] and will have $_FILES[$name]['name'] as a symbolic filename.

A PEAR error is returned if one of the following happen

$_FILES[$name] is not set
$_FILES[$name]['error'] is not 0
is_uploaded_file returns false

Return: File reader on the uploaded file

Parameters:

string $name — Index of the file in the $_FILES array

[ Top ]

void remove(
$URL
$pred, 
$URL)

Remove the files that follow a given predicate from the archive specified in $URL

Parameters:

$URL	`$pred`	—	URL of the archive where some files must be removed
	`$URL`	—

[ Top ]

void removeDuplicates(

$URL)

Remove duplicates from the archive specified in the URL

Parameters:

$URL —

[ Top ]

void removeDuplicatesFromSource(
File_Archive_Reader
&$toConvert, [
$URL = null])

Remove duplicates from a source, keeping the most recent one (or the one that has highest pos in the archive if the files have same date or no date specified)

Parameters:

File_Archive_Reader	`&$toConvert`	—	a reader that may contain duplicates
	`$URL`	—

[ Top ]

void removeFromSource(

&$pred, 
&$toConvert, [
$URL = null], File_Archive_Predicate
$pred, File_Archive_Reader
$source)

Remove the files that follow a given predicate from the source If URL is null, the files will be removed from the source directly Else, URL must link to a source from which the files will be removed

Parameters:

File_Archive_Predicate	`$pred`	—	The files that follow the predicate (for which $pred->isTrue($source) is true) will be erased
File_Archive_Reader	`$source`	—	A reader that contains the files to remove
	`&$pred`	—
	`&$toConvert`	—
	`$URL`	—

[ Top ]

void setOption(

$name, 
$value)

Sets an option that will be used by default by all readers or writers Option names are case sensitive Currently, the following options are used:

"cache" Instance of a Cache_Lite object used to cache some compressed data to speed up future compressions of files Default: null (no cache used)

"zipCompressionLevel" Value between 0 and 9 specifying the default compression level used by Zip writers (0 no compression, 9 highest compression) Default: 9

"gzCompressionLevel" Value between 0 and 9 specifying the default compression level used by Gz writers (0 no compression, 9 highest compression) Default: 9

"tmpDirectory" Directory where the temporary files generated by File_Archive will be created Default: '.'

"appendRemoveDuplicates" If set to true, the appender created will by default remove the file present in the archive when adding a new one. This will slow the appending of files to archives Default: false

"blockSize" To transfer data from a reader to a writer, some chunks a read from the source and written to the writer. This parameter controls the size of the chunks Default: 64kB

"cacheCondition" This parameter specifies when a cache should be used. When the cache is used, the data of the reader is saved in a temporary file for future access. The cached reader will be read only once, even if you read it several times. This can be usefull to read compressed files or downloaded files (from http or ftp) The possible values for this option are

false: never use cache
a regexp: A cache will be used if the specified URL matches the regexp preg_match is used

Default: false Example: '/^(http|ftp):\/\//' will cache all files downloaded via http or ftp

Parameters:

	`$name`	—
	`$value`	—

[ Top ]

void toArchive(
string
$filename, 
&$toConvert, [string
$type = null], [array
$stat = array()], [bool
$autoClose = true], File_Archive_Writer
$innerWriter)

Compress the data to a tar, gz, tar/gz or zip format

Parameters:

string	`$filename`	—	name of the archive file
File_Archive_Writer	`$innerWriter`	—	writer where the archive will be written
string	`$type`	—	can be one of tgz, tbz, tar, zip, gz, gzip, bz2, bzip2 (default is the extension of $filename) or any composition of them (for example tar.gz or tar.bz2). The case of this parameter is not important.
array	`$stat`	—	Statistics of the archive (see stat function)
bool	`$autoClose`	—	If set to true, $innerWriter will be closed when the returned archive is close. Default value is true.
	`&$toConvert`	—

[ Top ]

void toFiles(
[string
$baseDir = ""])

Write the files on the hard drive

See: File_Archive_Writer_Files

Parameters:

string $baseDir — if specified, the files will be created in that directory. If they don't exist, the directories will automatically be created

[ Top ]

void toMail(

$to, array
$headers, string
$message, [Mail
$mail = null])

Send the files as a mail attachment

See: File_Archive_Writer_Mail

Parameters:

Mail	`$mail`	—	Object used to send mail (see Mail::factory)
array	`$headers`	—	or String $to An array or a string with comma separated recipients
string	`$message`	—	Text body of the mail
	`$to`	—

[ Top ]

void toMemory(
out
$data)

Send the content of the files to a memory buffer

toMemory returns a writer where the data will be written. In this case, the data is accessible using the getData member

toVariable returns a writer that will write into the given variable

See: File_Archive_Writer_Memory

Parameters:

out $data — if specified, the data will be written to this buffer Else, you can retrieve the buffer with the File_Archive_Writer_Memory::getData() function

[ Top ]

void toMulti(

&$aC, 
&$bC, File_Archive_Writer
$a,)

Duplicate the writing operation on two writers

See: File_Archive_Writer_Multi

Parameters:

File_Archive_Writer	`$a,`	—	$b writers where data will be duplicated
	`&$aC`	—
	`&$bC`	—

[ Top ]

void toOutput(
[bool
$sendHeaders = true])

Send the content of the files to the standard output (so to the client for a website)

See: File_Archive_Writer_Output

Parameters:

bool $sendHeaders — If true some headers will be sent to force the download of the file. Default value is true

[ Top ]

void toVariable(

&$v)

Parameters:

&$v —

[ Top ]

Class: File_Archive

Class Overview

Methods

Inherited Variables

Inherited Methods

Class Details

Method Detail

appender [line 1361]

Parameters:

appenderFromSource [line 1269]

Parameters:

cache [line 549]

Parameters:

changeName [line 783]

Parameters:

extract [line 1230]

Parameters:

filter [line 802]

Parameters:

getOption [line 140]

Parameters:

isKnownExtension [line 620]

Parameters:

predAnd [line 840]

Parameters:

predCustom [line 1015]

Parameters:

predEreg [line 961]

Parameters:

predEregi [line 974]

Parameters:

predExtension [line 921]

Parameters:

predFalse [line 827]

predIndex [line 988]

Parameters:

predMaxDepth [line 909]

Parameters:

predMIME [line 934]

Parameters:

predMinSize [line 885]

Parameters:

predMinTime [line 897]

Parameters:

predNot [line 874]

Parameters:

predOr [line 858]

Parameters:

predPreg [line 947]

Parameters:

predTrue [line 817]

read [line 474]

Parameters:

readArchive [line 651]

Parameters:

readConcat [line 759]

Parameters:

readMemory [line 716]

Parameters:

readMulti [line 732]

Parameters:

readSource [line 257]

Parameters:

readUploadedFile [line 494]

Parameters:

remove [line 1404]

Parameters:

removeDuplicates [line 1443]

Parameters:

removeDuplicatesFromSource [line 1416]

Parameters:

removeFromSource [line 1376]

Parameters:

setOption [line 127]

Parameters:

toArchive [line 1125]

Parameters:

toFiles [line 1045]

Parameters:

toMail [line 1032]