The Archive_Tar class is brought to you by PEAR, the PHP Extension and Application Repository (http://pear.php.net). In case you didn't know, PEAR is an online repository of free PHP software, including classes and modules for everything from data archiving to XML parsing. When you install PHP, a whole bunch of PEAR modules get installed as well; the Archive_Tar class is one of them.

In case your PHP distribution didn't include Archive_Tar, or if you chose not to install the PEAR component, you can get yourself a copy from the official PEAR Web site, at http://pear.php.net - simply unzip the distribution archive into your PEAR directory and you're ready to roll!

Let's begin with something simple - packing a bunch of files into a single TAR archive with Archive_Tar object methods (this tutorial uses Archive_Tar 1.11).

  <?php

// include class

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

  // specify filename for output file

  $tar = new Archive_Tar("data.tar");
// set up file list

  $files = array("package.dtd", "package.xml", "filter.xsl", 
  "../../includes/php/adodb.php");
// build archive

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

  

This is a pretty simple script, but I'll hit the high points anyway:

1. The first step, as always, is to include the required class file in your script.

  <?php

// include class

  require("Tar.php");
?>

  

You can either provide an absolute path to this file, or do what most lazy programmers do - include the path to your PEAR installation in PHP's "include_path" variable, so that you can access any of the PEAR classes without needing to type in long, convoluted file paths.

2. The next step is to instantiate an object of the Archive_Tar class.

  <?php

// create Archive_Tar() object

  // specify filename for output file

  $tar = new Archive_Tar("data.tar");
?>

  

Note that the object constructor requires, as argument, the name of the TAR file to be created. You can include a path here as well if you would like the file to be created in a location other than the current directory.

3. Third, you need to tell the newly-created object which files to include in the archive. This information is provided to the object's create() method as an array of file names.

  <?php

// set up file list

  $files = array("package.dtd", "package.xml", "filter.xsl", 
  "../../includes/php/adodb.php");
// build archive

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

  

Obviously, you should replace the file list in the example above with information that reflects your own system. If Archive_Tar cannot locate any of the files specified in the file list, it will simply skip over it to the next one.

Note that the create() method will replace a previously-existing file with the same name. If you don't want this to happen, you should wrap your call to create() in a file_exists() test.

Once you run this script through your browser, you'll see that a file named "data.tar" appears in the same directory as the script.

$ ls -l data.tar
-rwxrw-rw- 1 nobody nobody 72704 Jul 8 14:31 data.tar

This is the TAR file created by the lines of code above.

If you examine this file with the "tar" command, you'll see that it contains all the files specified in your PHP script.

$ tar -tvf data.tar
-rw-rw-rw- 0/0 2876 2002-04-09 21:04:08 package.dtd
-rw-rw-rw- 0/0 2891 2002-11-18 01:22:20 package.xml
-rw-rw-rw- 0/0 707 2003-02-19 19:18:14 filter.xsl
-rw-rw-rw- 0/0 62790 2002-06-12 17:17:20 includes/php/adodb.php