Zeta Components - high quality PHP components

Tutorial
API

Zeta Components Manual :: Docs For Class ezcArchiveZip

Archive::ezcArchiveZip

Class ezcArchiveZip

The ezcArchiveZip class implements the Zip archive format.

ezcArchiveZip is a subclass from ezcArchive that provides the common interface. Zip algorithm specific methods are implemented in this class.

ezcArchiveZip tries on creation to read the entire archive. Every ezcArchiveEntry will be appended to the ezcArchive::$entries array. (ezcArchiveTarV7 archive format reads only an entry when needed the first time.)

All the archive entries are read, because we need to find the ezcArchiveCentralDirectoryHeader that contains extra file information. Some other Zip implementations search back from the end of the archive, but:

Not all of them take the comment section at the end of the archive into account.
The file pointer can only forward, so they seek over the entire archive anyway.

The current implementation can handle Non-Zip64 archives. The following extra Zip information can be read:

The Unix Extra field.
The Unix Extra field 2.
The Universal Timestamp field.

Source for this file: /Archive/src/zip/zip.php

Implements interfaces:

Iterator (internal interface)

ezcArchive
   |
   --ezcArchiveZip

Version:

//autogentag//

Inherited Constants

From ezcArchive:
`ezcArchive::BZIP2`	BZIP2 compression format.
`ezcArchive::GZIP`	Gnu ZIP compression format.
`ezcArchive::TAR`	Normal tar archive.
`ezcArchive::TAR_GNU`	GNU tar archive.
`ezcArchive::TAR_PAX`	PAX tar archive.
`ezcArchive::TAR_USTAR`	USTAR tar archive.
`ezcArchive::TAR_V7`	Tar version 7 archive.
`ezcArchive::ZIP`	ZIP archive.

Member Variables

protected array(int)	`$centralHeaderPositions` Stores the byte number where the central directory header starts (fileNumber is the index of the array).
protected array(ezcArchiveCentralDirectoryHeader)	`$centralHeaders` Stores the ezcArchiveCentralDirectoryHeader for each entry.
protected ezcArchiveCentralDirectoryEndHeader	`$endRecord` Stores the ezcArchiveCentralDirectoryEndHeader.
protected array(int)	`$localHeaderPositions` Stores the byte number where the local file header starts for each entry.
protected array(ezcArchiveLocalFileHeader)	`$localHeaders` Stores the ezcArchiveLocalFileHeader for each entry.

Inherited Member Variables

From ezcArchive
protected	`ezcArchive::$completed`
protected	`ezcArchive::$entries`
protected	`ezcArchive::$entriesRead`
protected	`ezcArchive::$file`
protected	`ezcArchive::$fileNumber`
protected	`ezcArchive::$options`

Method Summary

public ezcArchiveZip	`__construct( $file )` Initializes the Zip archive and reads the entire archive.
public bool	`algorithmCanWrite( )` Returns true because the ZIP algorithm can write.
public bool	`append( $files , $prefix )` Appends a file or directory to the end of the archive. Multiple files or directory can be added to the archive when an array is used as input parameter.
public bool	`appendToCurrent( $files , $prefix )` Appends a file to the archive after the current entry.
public int	`getAlgorithm( )` Returns the value which specifies a ZIP algorithm.
public string	`getFileData( $fileNumber )` Returns the file data of the given fileNumber.
public void	`getLocalHeader( $fileNumber )` Returns the local header of the specified file number.
public bool	`isWritable( )` Returns true if it is possible to write to the archive, otherwise false.
protected void	`readCentralHeaders( )` Reads the entire archive and creates all the entries.
protected void	`setEndRecord( )` Creates and sets a new ezcArchiveCentralDirectoryEndHeader.
public bool	`truncate( [ $fileNumber = 0] )` Truncates the archive to $fileNumber of files.
protected bool	`writeCurrentDataToFile( $targetPath )` Writes the file data from the current entry to the given file.
public void	`writeFile( $fileNumber , $writeTo )` Reads the file data from the archive and writes it the the $writeTo file.

Inherited Methods

From ezcArchive
public abstract bool	`ezcArchive::algorithmCanWrite()` Returns true if writing to the archive is implemented, otherwise false.
public abstract bool	`ezcArchive::append()` Appends a file or directory to the end of the archive. Multiple files or directory can be added to the archive when an array is used as input parameter.
public abstract bool	`ezcArchive::appendToCurrent()` Appends a file to the archive after the current entry.
public void	`ezcArchive::close()` Close the current archive.
protected void	`ezcArchive::createDefaultDirectory()` Creates all the directories needed to create the file $file.
protected static ezcArchive	`ezcArchive::createInstance()` Returns an instance of the archive with the given type.
public ezcArchiveEntry	`ezcArchive::current()` Returns the current ezcArchiveEntry if it is valid, otherwise false is returned.
public void	`ezcArchive::extract()` Extract entries from the archive to the target directory.
public bool	`ezcArchive::extractCurrent()` Extract the current entry to which the iterator points.
public abstract int	`ezcArchive::getAlgorithm()` Returns the algorithm that is used currently.
protected ezcArchiveEntry	`ezcArchive::getEntries()` Get the file entries from the archive.
public array(string)	`ezcArchive::getListing()` Returns an array that lists the content of the archive.
public static ezcArchive	`ezcArchive::getTarInstance()` Open a tar instance.
public static ezcArchive	`ezcArchive::getZipInstance()` Open a zip instance. This method is made public for testing purposes, and should not be used.
public bool	`ezcArchive::isEmpty()` Returns true if the current archive is empty, otherwise false.
public int	`ezcArchive::key()` Returns the current key, entry number, if it is valid, otherwise false is returned.
public ezcArchiveEntry	`ezcArchive::next()` Forwards the iterator to the next entry.
public static ezcArchive	`ezcArchive::open()` Returns a new ezcArchive instance.
public void	`ezcArchive::rewind()` Rewinds the iterator to the first entry.
public bool	`ezcArchive::seek()` Search for the entry number.
public void	`ezcArchive::setOptions()` This method associates a new $options object with this archive.
public abstract bool	`ezcArchive::truncate()` Truncates the archive to $fileNumber of files.
public bool	`ezcArchive::valid()` Returns true if the iterator points to a valid entry, otherwise false.
protected abstract void	`ezcArchive::writeCurrentDataToFile()` Writes the file data from the current entry to the given file.
public string	`ezcArchive::__toString()` Returns a string which represents all the entries from the archive.

Methods

__construct

ezcArchiveZip __construct( $file )

Initializes the Zip archive and reads the entire archive.

The constructor opens the archive as a ezcArchiveCharacterFile.

Parameters:

Name	Type	Description
`$file`	ezcArchiveCharacterFile

algorithmCanWrite

bool algorithmCanWrite( )

Returns true because the ZIP algorithm can write.

Redefinition of:

Method	Description
`ezcArchive::algorithmCanWrite()`	Returns true if writing to the archive is implemented, otherwise false.

append

bool append( string|array(string) $files , string $prefix )

Appends a file or directory to the end of the archive. Multiple files or directory can be added to the archive when an array is used as input parameter.

Parameters:

Name	Type	Description
`$files`	string\|array(string)	Array or a single path to a file.
`$prefix`	string	First part of the path used in $files.

Exceptions:

Type	Description
`ezcArchiveException`	if one of the files cannot be written to the archive.

Redefinition of:

Method	Description
`ezcArchive::append()`	Appends a file or directory to the end of the archive. Multiple files or directory can be added to the archive when an array is used as input parameter.

appendToCurrent

bool appendToCurrent( string|array(string) $files , string $prefix )

Appends a file to the archive after the current entry.

One or multiple files can be added directly after the current file. The remaining entries after the current are removed from the archive!

The $files can either be a string or an array of strings. Which, respectively, represents a single file or multiple files.

$prefix specifies the begin part of the $files path that should not be included in the archive. The files in the archive are always stored relatively.

Example:

$tar = ezcArchive( "/tmp/my_archive.tar", ezcArchive::TAR );
// Append two files to the end of the archive.
$tar->seek( 0, SEEK_END );
$tar->appendToCurrent( array( "/home/rb/file1.txt", "/home/rb/file2.txt" ), "/home/rb/" );

When multiple files are added to the archive at the same time, thus using an array, does not necessarily produce the same archive as repeatively adding one file to the archive. For example, the Tar archive format, can detect that files hardlink to each other and will store it in a more efficient way.

Parameters:

Name	Type	Description
`$files`	string\|array(string)	Array or a single path to a file.
`$prefix`	string	First part of the path used in $files.

Exceptions:

Type	Description
`ezcArchiveException`	if the archive is closed or read-only
`ezcBaseFileNotFoundException`	if one of the specified files is missing
`ezcBaseFilePermissionException`	if the archive is not writable

Redefinition of:

Method	Description
`ezcArchive::appendToCurrent()`	Appends a file to the archive after the current entry.

getAlgorithm

int getAlgorithm( )

Returns the value which specifies a ZIP algorithm.

Redefinition of:

Method	Description
`ezcArchive::getAlgorithm()`	Returns the algorithm that is used currently.

getFileData

string getFileData( int $fileNumber )

Returns the file data of the given fileNumber.

This method doesn't handle compression and reads the whole file in memory. This method is used to get the symbolic links, since these are stored in files.

For larger or compressed files, use the writeFile() method.

Parameters:

Name	Type	Description
`$fileNumber`	int

getLocalHeader

void getLocalHeader( int $fileNumber )

Returns the local header of the specified file number.

Parameters:

Name	Type	Description
`$fileNumber`	int

Exceptions:

Type	Description
`ezcArchiveException`	if the signature from the file is invalid

isWritable

bool isWritable( )

Returns true if it is possible to write to the archive, otherwise false.

This method returns false if the archive is read-only, the algorithm didn't implement any write methods, or both.

Exceptions:

Type	Description
`ezcArchiveException`	if the archive is closed

readCentralHeaders

void readCentralHeaders( )

Reads the entire archive and creates all the entries.

To find the central directory structure we need to read all the headers. Some algorithms search backwards, but these don't expect comments at the end of the archive.

The central directory structure gives us extra information about the stored file like: symlinks and permissions.

Exceptions:

Type	Description
`ezcArchiveException`	if the comment length is different than 0 or if the signature from the file is invalid or if the directory central header or size are missing

setEndRecord

void setEndRecord( )

Creates and sets a new ezcArchiveCentralDirectoryEndHeader.

The new ezcArchiveCentralDirectoryEndHeader is based on the current file position, the centralHeaderPositions, and the number of entries read.

truncate

bool truncate( [int $fileNumber = 0] )

Truncates the archive to $fileNumber of files.

The $fileNumber parameter specifies the amount of files that should remain. If the default value, zero, is used then the entire archive file is cleared.

Parameters:

Name	Type	Description
`$fileNumber`	int

Exceptions:

Type	Description
`ezcBaseFilePermissionException`	if the file is read-only or if the current algorithm cannot write

Redefinition of:

Method	Description
`ezcArchive::truncate()`	Truncates the archive to $fileNumber of files.

writeCurrentDataToFile

bool writeCurrentDataToFile( string $targetPath )

Writes the file data from the current entry to the given file.

Parameters:

Name	Type	Description
`$targetPath`	string	The absolute or relative path of the target file.

Redefinition of:

Method	Description
`ezcArchive::writeCurrentDataToFile()`	Writes the file data from the current entry to the given file.

writeFile

void writeFile( int $fileNumber , string $writeTo )

Reads the file data from the archive and writes it the the $writeTo file.

The data from the entry with $fileNumber is read from the archive. If the data is compressed or deflated it will be, respectively, decompressed or inflated.

Parameters:

Name	Type	Description
`$fileNumber`	int
`$writeTo`	string

Exceptions:

Type	Description
`ezcArchiveChecksumException`	if the checksum is invalid from the created file.

Documentation generated by phpDocumentor 1.4.3