Extracting a Tar-archive

The Tar format has more than one standard. The most common formats are:

• Gnu
• POSIX
• Unix V7
• Ustar (The default when creating a tar archive)

The Archive component can extract from any of these formats. Appending entries to the archive is only available for the Unix V7 and Ustar formats.

Extracting entries can occur in two ways:

• ezcArchive->extract(), extracts all entries from the archive.
• ezcArchive->extractCurrent(), extracts only the current entry.

An ezcArchive object can be used like an iterator. After opening the file, it points to the first entry. The iterator can be moved using ezcArchive->next() and ezcArchive->rewind() to move to the next entry or go back to the first entry.

The next example demonstrates how to extract an entire archive file-by-file:

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. // Open the gzipped TAR archive.
7. $archive = ezcArchive::open( "compress.zlib:///tmp/my_archive.tar.gz" );
9. while( $archive->valid() )
10. {
11. // Returns the current entry (ezcArchiveEntry).
12. $entry = $archive->current();
14. // ezcArchiveEntry has an __toString() method.
15. echo $entry, "\n";
17. // Extract the current archive entry to /tmp/target_location/
18. $archive->extractCurrent( "/tmp/target_location/" );
20. $archive->next();
21. }
23. ?>

First, tutorial_autoload.php is included. The included file loads the correct php files for the Archive package. Hereafter the time zone is set to "UTC". The Archive component uses some date functions and might therefore produce warnings if the time zone is not specified.

The gzipped Tar archive is opened using the zlib stream. The while() method iterates over each entry, showing the name and extracting the entry itself.

The Archive component extends from the PHP Iterator class, thus the above example can be rewritten as follows:

1. <?php
2. require_once 'tutorial_autoload.php';
4. $archive = ezcArchive::open( "compress.zlib:///tmp/my_archive.tar.gz" );
6. // The foreach method calls internally the iterator methods.
7. foreach( $archive as $entry )
8. {
9. echo $entry, "\n";
11. $archive->extractCurrent( "/tmp/target_location/" );
12. }
13. ?>

Please be aware that by default archive files are opened in read/write mode. In order to prevent that, you can set an option to open the archive in read-only mode. This also prevents the modify and create timestamps of the file to be preserved. The following example shows that:

1. <?php
2. require_once 'tutorial_autoload.php';
4. $options = new ezcArchiveOptions( array( 'readOnly' => true ) );
5. $archive = ezcArchive::open(
6. "compress.zlib:///tmp/my_archive.tar.gz", null, $options );
8. // The foreach method calls internally the iterator methods.
9. foreach( $archive as $entry )
10. {
11. echo $entry, "\n";
13. $archive->extractCurrent( "/tmp/target_location/" );
14. }
15. ?>

Appending files to an archive

Unfortunately, it is not yet possible to directly append files to a gzipped or bzipped Tar archive. The ZLib and BZip2 libraries do not support opening a file for reading and writing.

ezcArchive has two methods for appending files:

• ezcArchive->append(), appends entries to the end of the archive.
• ezcArchive->appendCurrent(), appends entries after the current entry and removes the rest of the files from the archive.

To replace the first file as well, use ezcArchive->truncate(). The next example replaces all entries from an existing Zip archive with the files file1.txt and file2.txt:

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. $archive = ezcArchive::open( "/tmp/my_archive.zip" );
7. $archive->truncate();
9. $filesToAppend[] = "/tmp/file1.txt";
10. $filesToAppend[] = "/tmp/file2.txt";
12. // The second parameter specifies prefix. The prefix is normally not included
13. // in the archive.
14. $archive->appendToCurrent( $filesToAppend, "/tmp/" );
16. ?>

Appending directories to an archive

You need to append a slash '/' to the end of the directory name that is added to an archive.

The next example replaces all entries from an existing Zip archive with the 'directory' folder and the 'file.txt' file:

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. $archive = ezcArchive::open( "/tmp/my_archive.zip" );
7. $archive->truncate();
9. $filesToAppend[] = "/tmp/directory/";
10. $filesToAppend[] = "/tmp/file.txt";
12. // The second parameter specifies prefix. The prefix is normally not included
13. // in the archive.
14. $archive->appendToCurrent( $filesToAppend, "/tmp/" );
16. ?>

Appending a directory tree to an archive

Using the function ezcBase::walkRecursive() a directory tree can be added to an archive.

The next example shows how to browse a directory tree and add all the files and directories inside to an archive:

1. <?php
3. require_once 'tutorial_autoload.php';
4. date_default_timezone_set( "UTC" );
6. class ArchiveContext extends ezcBaseFileFindContext
7. {
8. public $archive;
9. public $prefix;
10. }
12. function findRecursiveCallback( ezcBaseFileFindContext $context, $sourceDir, $fileName, $fileInfo )
13. {
14. $path = "{$sourceDir}/{$fileName}";
15. if ( is_dir( $path ) )
16. {
17. $path .= '/';
18. }
19. $context->archive->append( array( $path ), $context->prefix );
20. }
22. function appendRecursive( $archive, $sourceDir, $prefix )
23. {
24. $context = new ArchiveContext();
25. $context->archive = $archive;
26. $context->prefix = $prefix;
27. ezcBaseFile::walkRecursive( $sourceDir, array(), array(), 'findRecursiveCallback', $context );
28. }
30. $archive = ezcArchive::open( "my_archive.zip", ezcArchive::ZIP );
31. $archive->truncate();
33. // the 2nd parameter is the directory, the 3rd parameter is the prefix
34. appendRecursive( $archive, '/tmp/directory/', '/tmp/directory/' );
36. ?>

The ArchiveContext class will hold the archive object which is passed to the callback function findRecursiveCallback. The appendRecursive function sets up the context object (of class ArchiveContext) and calls the findRecursiveCallback function. In the findRecursiveCallback function the current file or directory is appended to the archive object inside the context.