The Archive_Tar object also allows you to extract the contents of a compressed (or uncompressed) TAR file with its extract() method, which accepts the target directory as argument. Consider the following example, which demonstrates by extracting the contents of the named archive to the temporary directory:

  <?php

// include class

  require("Tar.php");
// use tar file

  $tar = new Archive_Tar("uudeview-0.5.18.tar.gz");
// extract contents of tar file into named directory

  $tar->extract("/tmp/xfiles") or die ("Could not extract files!"); 
  ?> 

A quick look in "/tmp/xfiles" after running the script above will show you that the files have been successfully extracted.

$ ls -lR /tmp/xfiles/
/tmp/xfiles/:
total 4
drwxr-xr-x 8 nobody nobody 4096 Jul 10 12:22 uudeview-0.5.18

Note that if the target directory does not exist, Archive_Tar will attempt to create it for you.

You can also selectively extract certain files from the source archive with the Archive_Tar object's extractList() method, which additionally accepts a list of the file names to be pulled out of the archive. Here's an example:

  <?php

// include class

  require("Tar.php");
// use tar file

  $tar = new Archive_Tar("uudeview-0.5.18.tar.gz");
// extract selected files from tar file>

$tar->extractList(array("uudeview-0.5.18/configure",

  "uudeview-0.5.18/install-sh"), "/tmp/xfiles") or die ("Could 
  not extract files!");
?>

  

The example above would extract only the files "configure" and "install-sh" from the TAR archive into the target directory.

$ ls -lR /tmp/xfiles/
/tmp/xfiles/:
total 4
drwxr-xr-x 2 nobody nobody 4096 Jul 10 12:24 uudeview-0.5.18

/tmp/xfiles/uudeview-0.5.18:
total 108
-rwxrw-rw- 1 nobody nobody 94247 Apr 2 2002 configure
-rwxrw-rw- 1 nobody nobody 4772 Jun 7 1996 install-sh

Note that you will have to specify the full path (within the archive) to the files to be extracted in order to successfully use the extractList() function. If the path to any of the files specified in the file list is incorrect, extractList() will simply skip over that file.

For users who need more fine-grained control over the archive creation and extraction process, Archive_Tar offers the createModify(), addModify() and
extractModify() methods. These methods work in the same manner as the create(), add() and extract() methods discussed previously, except that they also allow you to determine the directory structure of the TAR package and its output.

What does this mean? Consider the following simple directory structure:

tempstuff/
tempstuff/menu.php
tempstuff/menu.xml
tempstuff/config.inc

Now, if you were to create an archive of these files using the create() method, as in the script below,

  <?php

// include class

  require("Tar.php");
// create Archive_Tar() object

  // specify filename for output file and compression method

  $tar = new Archive_Tar("menu.tar.gz", "gz");
// set up file list

  $files = array("tempstuff/menu.xml", "tempstuff/config.inc", 
  "tempstuff/menu.php");
// build archive

  $tar->create($files) or die("Could not create archive!");
?>

  

the resulting TAR file would look (and be extracted) like this:

tempstuff/
tempstuff/menu.php
tempstuff/menu.xml
tempstuff/config.inc

What the functions above let you do is control the directory structure inside the TAR archive, and thereby determine the output when the archive is exploded. So, if you wanted (for example) to replace the outer directory "tempstuff/" in the archive above with something more descriptive, like "menutools-0.51/scripts/", you could use the createModify() method instead, as in the script below:

  <?php

// include class

  require("Tar.php");
// create Archive_Tar() object

  // specify filename for output file and compression method

  $tar = new Archive_Tar("menu.tar.gz", "gz");
// set up file list

  $files = array("tempstuff/menu.xml", "tempstuff/config.inc", 
  "tempstuff/menu.php");
// build archive

  // set up new directory hierarchy within archive>

   $tar->createModify($files, 
  "menutools-0.51/scripts/", "tempstuff") or die("Could 
  not create archive!");
?>

  

The only difference between this script and previous ones: this one uses the createModify() method instead of the create() method, and passes that method two additional arguments. The first of these arguments is the directory path to be added to each file ("menutools-0.51/scripts/" in this example); the second is the directory to be amputated when packing the files into the archive ("tempstuff/" in this example).

Now, if you attempt to explode the resulting TAR archive (either using the "tar" command or the Archive_Tar extract() method), the addition of the custom path above will result in the files within the archive being placed in a "menutools-0.51/scripts/" directory in your extraction area.

menutools-0.51/scripts/
menutools-0.51/scripts/menu.php
menutools-0.51/scripts/menu.xml menutools-0.51/scripts/config.inc

In a similar manner, when using the extractList() function, there may arise a situation when you don't want the directory structure maintained within the TAR file to be preserved during the extraction of specific files. In such a case, you can tell Archive_Tar to ignore the relative path and directory tree hierarchy associated with each file, by adding a third, optional, parameter to extractList().

In the following example, even though the files within the archive are organized in a particular hierarchical structure, the third argument to
extractList() tells Archive_Tar to ignore a section of the hierarchy while extracting files.

  <?php

// include class

  require("Tar.php");
// use tar file

  $tar = new Archive_Tar("uudeview-0.5.18.tar.gz");
// extract selected files from tar file

$tar->extractList(array("uudeview-0.5.18/configure",

  "uudeview-0.5.18/install-sh"), "/tmp/xfiles", "uudeview-0.5.18") 
  or die ("Could not extract files!");
?>

  

The addModify() method lets you do something similar, but with an existing archive.

Look in the class documentation for more examples of how this feature can be used.