## Apache Zeta Components Manual :: Docs For Class ezcArchive

### Archive::ezcArchive

### Class ezcArchive

The ezcArchive class provides the common interface for reading and writing the archive formats Tar and Zip.

ezcArchive provides the main API for reading and writing to an archive. The archive itself can be compressed with GZip or BZip2 and will be handled transparently.

The open() method creates a new archive instance. For existing archives, ezcArchive determines the correct archive format by the mime-type and returns an instance of a subclass handling this format. New archives should force a format type via a parameter in the open() method.

The instance of an ezcArchive class is also an iterator, which points to the first file in the archive by default. Moving this pointer can be done via the iterator methods: rewind(), next(), valid(), key(), and current(). This iterator is defined as an object iterator and allows, for example, the foreach statement to iterate through the files.

Extra methods that operate on the current iterator are: extractCurrent() and appendToCurrent(). Which can be used, respectively, to extract the files and to append a new file to the archive. To append a directory to an archive you need to add a slash '/' at the end of the directory name.

The following example will open an existing tar.gz file and will append each file to a zip archive:

1. $tar=ezcArchive :: open ("/tmp/archive.tar.gz");
2. $newZip=ezcArchive :: open ("/tmp/new_archive.zip", ezcArchive ::ZIP);
4. foreach($taras$entry)
5. {
6. // $entry contains the information of the current entry in the archive.
7. $tar-> extractCurrent ("/tmp/");
8. $newZip-> appendToCurrent ($entry->getPath(),"/tmp/");
9. $newZip-> next ();
10. }

In order to extract an entire archive at once, use the extract() method.

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

### Implements interfaces:

- Iterator (internal interface)

Version: | //autogentag//

### Descendants

Child Class | Description
--- | ---
ezcArchiveV7Tar | The ezcArchiveV7Tar class implements the Tar v7 archive format.
ezcArchiveZip | The ezcArchiveZip class implements the Zip archive format.

### Constants

`BZIP2 = 30` | BZIP2 compression format.
`GZIP = 20` | Gnu ZIP compression format.
`TAR = 0` | Normal tar archive.
`TAR_GNU = 4` | GNU tar archive.
`TAR_PAX = 3` | PAX tar archive.
`TAR_USTAR = 2` | USTAR tar archive.
`TAR_V7 = 1` | Tar version 7 archive.
`ZIP = 10` | ZIP archive.

### Member Variables

protected bool | `$completed = false` Is true when the archive is read until the end, otherwise false.
protected array(ezcArchiveEntry) | `$entries` Stores the entries read from the archive. The array is not complete when the $completed variable is set to false. The array may be over-complete, so the $entriesRead should be checked if the $completed variable is set to true.
protected int | `$entriesRead = 0` The number of entries currently read from the archive.
protected ezcArchiveFile | `$file = null` Direct access to the archive file.
protected int | `$fileNumber = 0` The entry or file number to which the iterator points. The first $fileNumber starts with 0.
protected ezcArchiveOptions | `$options` Holds the options if passed to the open method.

### Method Summary

protected static ezcArchive | `createInstance( $archiveName , $type , [ $options = null] )` Returns an instance of the archive with the given type.
public static ezcArchive | `getTarInstance( $blockFile , $type )` Open a tar instance.
public static ezcArchive | `getZipInstance( $charFile )` Open a zip instance. This method is made public for testing purposes, and should not be used.
public static ezcArchive | `open( $archiveName , [ $forceType = null] , [ $options = null] )` Returns a new ezcArchive instance.
public abstract bool | `algorithmCanWrite( )` Returns true if writing to the archive is implemented, otherwise false.
public abstract 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 abstract bool | `appendToCurrent( $files , $prefix )` Appends a file to the archive after the current entry.
public void | `close( )` Close the current archive.
protected void | `createDefaultDirectory( $file )` Creates all the directories needed to create the file $file.
public ezcArchiveEntry | `current( )` Returns the current ezcArchiveEntry if it is valid, otherwise false is returned.
public void | `extract( $target , [ $keepExisting = false] )` Extract entries from the archive to the target directory.
public bool | `extractCurrent( $target , [ $keepExisting = false] )` Extract the current entry to which the iterator points.
public abstract int | `getAlgorithm( )` Returns the algorithm that is used currently.
protected ezcArchiveEntry | `getEntries( $files , $prefix )` Get the file entries from the archive.
public array(string) | `getListing( )` Returns an array that lists the content of the archive.
public bool | `isEmpty( )` Returns true if the current archive is empty, otherwise false.
public int | `key( )` Returns the current key, entry number, if it is valid, otherwise false is returned.
public ezcArchiveEntry | `next( )` Forwards the iterator to the next entry.
public void | `rewind( )` Rewinds the iterator to the first entry.
public bool | `seek( $offset , [ $whence = SEEK_SET] )` Search for the entry number.
public void | `setOptions( $options )` This method associates a new $options object with this archive.
public abstract bool | `truncate( [ $fileNumber = 0] )` Truncates the archive to $fileNumber of files.
public bool | `valid( )` Returns true if the iterator points to a valid entry, otherwise false.
protected abstract void | `writeCurrentDataToFile( $targetPath )` Writes the file data from the current entry to the given file.
public string | `__toString( )` Returns a string which represents all the entries from the archive.

### Methods

#### createInstance

static ezcArchive createInstance( string $archiveName , int $type , [ezcArchiveOptions $options = null] )

Returns an instance of the archive with the given type.

Similar to open(), but the type is required.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$archiveName` | string | The path of the archive.
`$type` | int | Open the archive with the $forceType algorithm. Possible values are: ezcArchive::ZIP, ezcArchive::TAR, ezcArchive::TAR_V7, ezcArchive::TAR_USTAR, ezcArchive::TAR_PAX, ezcArchive::TAR_GNU. TAR will use the TAR_USTAR algorithm by default.
`$options` | ezcArchiveOptions |

#### getTarInstance

static ezcArchive getTarInstance( $blockFile , int $type )

Open a tar instance.

This method is made public for testing purposes, and should not be used.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$blockFile` | ezcArchiveBlockFile |
`$type` | int | The algorithm type. Possible values are: ezcArchive::TAR, ezcArchive::TAR_V7, ezcArchive::TAR_USTAR, ezcArchive::TAR_PAX, ezcArchive::TAR_GNU. TAR will use the TAR_USTAR algorithm by default.

#### getZipInstance

static ezcArchive getZipInstance( $charFile )

Open a zip instance. This method is made public for testing purposes, and should not be used.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$charFile` | ezcArchiveCharacterFile | The character file which contains the archive.

#### open

static ezcArchive open( string $archiveName , [int $forceType = null] , [ezcArchiveOptions $options = null] )

Returns a new ezcArchive instance.

This method returns a new instance according to the mime-type or the given $forceType.

- If $forceType is set to null, this method will try to determine the archive format via the file data. Therefore the $forceType can only be null when the archive contains data.
- If $forceType is set, it will use the specified algorithm. Even when the given archive is from another type than specified.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$archiveName` | string | Absolute or relative path to the archive.
`$forceType` | int | Open the archive with the $forceType algorithm. Possible values are: ezcArchive::ZIP, ezcArchive::TAR, ezcArchive::TAR_V7, ezcArchive::TAR_USTAR, ezcArchive::TAR_PAX, ezcArchive::TAR_GNU. TAR will use the TAR_USTAR algorithm by default.
`$options` | ezcArchiveOptions |

##### Exceptions:

Type | Description
--- | ---
`ezcArchiveUnknownTypeException` | if the type of the archive cannot be determined.

#### algorithmCanWrite

bool algorithmCanWrite( )

Returns true if writing to the archive is implemented, otherwise false.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::algorithmCanWrite()` | Returns true because the TAR_V7 algorithm can write.
`ezcArchiveUstarTar::algorithmCanWrite()` | Returns true because the TAR_USTAR algorithm can write.
`ezcArchiveGnuTar::algorithmCanWrite()` | Returns false because the TAR_PAX algorithm cannot write (yet).
`ezcArchivePaxTar::algorithmCanWrite()` | Returns false because the TAR_PAX algorithm cannot write (yet).
`ezcArchiveZip::algorithmCanWrite()` | Returns true because the ZIP algorithm can write.

#### 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
--- | ---
`ezcArchiveWriteException` | if one of the files cannot be written to the archive.
`ezcFileReadException` | if one of the files cannot be read from the local filesystem.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::append()` | Append 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.
`ezcArchiveZip::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:

1. $tar=ezcArchive ("/tmp/my_archive.tar", ezcArchive ::TAR);
3. // Append two files to the end of the archive.
4. $tar-> seek (0,SEEK_END);
5. $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
--- | ---
`ezcArchiveWriteException` | if one of the files cannot be written to the archive.
`ezcFileReadException` | if one of the files cannot be read from the local filesystem.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::appendToCurrent()` | Appends a file to the archive after the current entry.
`ezcArchiveZip::appendToCurrent()` | Appends a file to the archive after the current entry.

#### close

void close( )

Close the current archive.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::close()` | Closes the archive correctly.

#### createDefaultDirectory

void createDefaultDirectory( string $file )

Creates all the directories needed to create the file $file.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$file` | string | Path to a file, where all the base directory names will be created.

#### current

ezcArchiveEntry current( )

Returns the current ezcArchiveEntry if it is valid, otherwise false is returned.

##### Implementation of:

Method | Description
--- | ---
`Iterator::current` |

#### extract

void extract( string $target , [bool $keepExisting = false] )

Extract entries from the archive to the target directory.

All entries from the archive are extracted to the target directory. By default the files in the target directory are overwritten. If the $keepExisting is set to true, the files from the archive will not overwrite existing files.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$target` | string | Absolute or relative path of the directory.
`$keepExisting` | bool | If set to true then the file will be overwritten, otherwise not.

##### Exceptions:

Type | Description
--- | ---
`ezcArchiveException` | if the archive is closed
`ezcArchiveEmptyException` | if the archive is invalid

#### extractCurrent

bool extractCurrent( string $target , [bool $keepExisting = false] )

Extract the current entry to which the iterator points.

Extract the current entry to which the iterator points, and return true if the current entry is extracted. If the iterator doesn't point to a valid entry, this method returns false.

True if the file is extracted correctly, otherwise false.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$target` | string | The full path to which the target should be extracted.
`$keepExisting` | bool | True if the file shouldn't be overwritten if they already exist. For the opposite behaviour, false should be given.

##### Exceptions:

Type | Description
--- | ---
`ezcBaseFileNotFoundException` | if the link cannot be found.
`ezcArchiveValueException` | if the archive contains invalid values.

#### getAlgorithm

int getAlgorithm( )

Returns the algorithm that is used currently.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::getAlgorithm()` | Returns the value which specifies a TAR_V7 algorithm.
`ezcArchiveUstarTar::getAlgorithm()` | Returns the value which specifies a TAR_USTAR algorithm.
`ezcArchiveGnuTar::getAlgorithm()` | Returns the value which specifies a TAR_GNU algorithm.
`ezcArchivePaxTar::getAlgorithm()` | Returns the value which specifies a TAR_PAX algorithm.
`ezcArchiveZip::getAlgorithm()` | Returns the value which specifies a ZIP algorithm.

#### getEntries

ezcArchiveEntry getEntries( string|array(string) $files , string $prefix )

Get the file entries from the archive.

##### 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.

#### getListing

array(string) getListing( )

Returns an array that lists the content of the archive.

Use the getArchiveEntry method to get more information about an entry.

##### Exceptions:

Type | Description
--- | ---
`ezcArchiveException` | if the archive is closed

#### isEmpty

bool isEmpty( )

Returns true if the current archive is empty, otherwise false.

#### key

int key( )

Returns the current key, entry number, if it is valid, otherwise false is returned.

##### Implementation of:

Method | Description
--- | ---
`Iterator::key` |

#### next

ezcArchiveEntry next( )

Forwards the iterator to the next entry.

If there is no next entry all iterator methods except for rewind() will return false.

##### Implementation of:

Method | Description
--- | ---
`Iterator::next` |

#### rewind

void rewind( )

Rewinds the iterator to the first entry.

##### Implementation of:

Method | Description
--- | ---
`Iterator::rewind` |

#### seek

bool seek( int $offset , [int $whence = SEEK_SET] )

Search for the entry number.

The two parameters here are the same as the PHP fseek() method. The internal iterator position will be set by $offset added to $whence iterations forward. Where $whence is:

- SEEK_SET, Set the position equal to $offset.
- SEEK_CUR, Set the current position plus $offset.
- SEEK_END, Set the last file in archive position plus $offset.

This method returns true if the new position is valid, otherwise false.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$offset` | int |
`$whence` | int |

##### Exceptions:

Type | Description
--- | ---
`ezcArchiveException` | if the archive is closed

#### setOptions

void setOptions( ezcArchiveOptions $options )

This method associates a new $options object with this archive.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcArchiveOptions |

#### 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 |

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::truncate()` | Truncates the archive to $fileNumber of files.
`ezcArchiveZip::truncate()` | Truncates the archive to $fileNumber of files.

#### valid

bool valid( )

Returns true if the iterator points to a valid entry, otherwise false.

##### Implementation of:

Method | Description
--- | ---
`Iterator::valid` |

#### writeCurrentDataToFile

void 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.

##### Redefined in descendants as:

Method | Description
--- | ---
`ezcArchiveV7Tar::writeCurrentDataToFile()` | Writes the file data from the current entry to the given file.
`ezcArchiveZip::writeCurrentDataToFile()` | Writes the file data from the current entry to the given file.

#### __toString

string __toString( )

Returns a string which represents all the entries from the archive.

##### Exceptions:

Type | Description
--- | ---
`ezcArchiveException` | if the archive is closed

Documentation generated by phpDocumentor 1.4.3