Zeta Components - high quality PHP components

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 );
3.  
4.  foreach ( $tar as $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.

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

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

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.

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 );
2.  
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.

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.

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.

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

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

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.

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.