Documentation for class Archive_Tar
===================================
Last update : 2001-08-15



Overview :
----------

  The Archive_Tar class helps in creating and managing GNU TAR format
  files compressed by GNU ZIP or not. 
  The class offers basic functions like creating an archive, adding
  files in the archive, extracting files from the archive and listing
  the archive content. 
  It also provide advanced functions that allow the adding and
  extraction of files with path manipulation. 


Sample :
--------

  // ----- Creating the object (uncompressed archive)
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);

  // ----- Creating the archive
  $v_list[0]="file.txt";
  $v_list[1]="data/";
  $v_list[2]="file.log";
  $tar_object->create($v_list);

  // ----- Adding files
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/";
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);

  // ----- Adding more files
  $tar_object->add("release/newfile.log release/readme.txt");

  // ----- Listing the content
  if (($v_list  =  $tar_object->listContent()) != 0)
    for ($i=0; $i<sizeof($v_list); $i++)
    {
      echo "Filename :'".$v_list[$i][filename]."'<br>";
      echo " .size :'".$v_list[$i][size]."'<br>";
      echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
      echo " .mode :'".$v_list[$i][mode]."'<br>";
      echo " .uid :'".$v_list[$i][uid]."'<br>";
      echo " .gid :'".$v_list[$i][gid]."'<br>";
      echo " .typeflag :'".$v_list[$i][typeflag]."'<br>";
    }

  // ----- Extracting the archive in directory "install"
  $tar_object->extract("install");


Public arguments :
------------------

None


Public Methods :
----------------

Method : Archive_Tar($p_tarname, $compress = null)
Description :
  Archive_Tar Class constructor. This flavour of the constructor only
  declare a new Archive_Tar object, identifying it by the name of the
  tar file.
  If the compress argument is set the tar will be read or created as a
  gzip or bz2 compressed TAR file. 
Arguments :
  $p_tarname : A valid filename for the tar archive file.
  $p_compress : can be null, 'gz' or 'bz2'. For
                compatibility reason it can also be true. This
                parameter indicates if gzip or bz2 compression
                is required. 
Return value :
  The Archive_Tar object.
Sample :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object_compressed = new Archive_Tar("tarname.tgz", true);
How it works :
  Initialize the object.

Method : create($p_filelist)
Description :
  This method creates the archive file and add the files / directories
  that are listed in $p_filelist. 
  If the file already exists and is writable, it is replaced by the
  new tar. It is a create and not an add. If the file exists and is
  read-only or is a directory it is not replaced. The method return
  false and a PEAR error text. 
  The $p_filelist parameter can be an array of string, each string
  representing a filename or a directory name with their path if
  needed. It can also be a single string with names separated by a
  single blank. 
  See also createModify() method for more details.
Arguments :
  $p_filelist : An array of filenames and directory names, or a single
  string with names separated by a single blank space. 
Return value :
  true on success, false on error.
Sample 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
  $v_list[0]="file.txt";
  $v_list[1]="data/"; (Optional '/' at the end)
  $v_list[2]="file.log";
  $tar_object->create($v_list);
Sample 2 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
  $tar_object->create("file.txt data/ file.log");
How it works :
  Just calling the createModify() method with the right parameters.

Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "")
Description :
  This method creates the archive file and add the files / directories
  that are listed in $p_filelist. 
  If the file already exists and is writable, it is replaced by the
  new tar. It is a create and not an add. If the file exists and is
  read-only or is a directory it is not replaced. The method return
  false and a PEAR error text. 
  The $p_filelist parameter can be an array of string, each string
  representing a filename or a directory name with their path if
  needed. It can also be a single string with names separated by a
  single blank. 
  The path indicated in $p_remove_dir will be removed from the
  memorized path of each file / directory listed when this path
  exists. By default nothing is removed (empty path "") 
  The path indicated in $p_add_dir will be added at the beginning of
  the memorized path of each file / directory listed. However it can
  be set to empty "". The adding of a path is done after the removing
  of path. 
  The path add/remove ability enables the user to prepare an archive
  for extraction in a different path than the origin files are. 
  See also addModify() method for file adding properties.
Arguments :
  $p_filelist : An array of filenames and directory names, or a single
                string with names separated by a single blank space.
  $p_add_dir : A string which contains a path to be added to the
               memorized path of each element in the list. 
  $p_remove_dir : A string which contains a path to be removed from
                  the memorized path of each element in the list, when
		  relevant.
Return value :
  true on success, false on error.
Sample 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
  $v_list[0]="file.txt";
  $v_list[1]="data/"; (Optional '/' at the end)
  $v_list[2]="file.log";
  $tar_object->createModify($v_list, "install");
  // files are stored in the archive as :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... all the files and sub-dirs of data/
  //   install/file.log
Sample 2 :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->setErrorHandling(PEAR_ERROR_PRINT);  // Optional error handling
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (Optional '/' at the end)
  $v_list[2]="log/file.log";
  $tar_object->createModify($v_list, "install", "dev");
  // files are stored in the archive as :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... all the files and sub-dirs of data/
  //   install/log/file.log
How it works :
  Open the file in write mode (erasing the existing one if one),
  call the _addList() method for adding the files in an empty archive,
  add the tar footer (512 bytes block), close the tar file.


Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="")
Description :
  This method add the files / directories listed in $p_filelist at the
  end of the existing archive. If the archive does not yet exists it
  is created.
  The $p_filelist parameter can be an array of string, each string
  representing a filename or a directory name with their path if
  needed. It can also be a single string with names separated by a
  single blank. 
  The path indicated in $p_remove_dir will be removed from the
  memorized path of each file / directory listed when this path
  exists. By default nothing is removed (empty path "") 
  The path indicated in $p_add_dir will be added at the beginning of
  the memorized path of each file / directory listed. However it can
  be set to empty "". The adding of a path is done after the removing
  of path. 
  The path add/remove ability enables the user to prepare an archive
  for extraction in a different path than the origin files are. 
  If a file/dir is already in the archive it will only be added at the
  end of the archive. There is no update of the existing archived
  file/dir. However while extracting the archive, the last file will
  replace the first one. This results in a none optimization of the
  archive size. 
  If a file/dir does not exist the file/dir is ignored. However an
  error text is send to PEAR error. 
  If a file/dir is not readable the file/dir is ignored. However an
  error text is send to PEAR error. 
  If the resulting filename/dirname (after the add/remove option or
  not) string is greater than 99 char, the file/dir is
  ignored. However an error text is send to PEAR error. 
Arguments :
  $p_filelist : An array of filenames and directory names, or a single
                string with names separated by a single blank space. 
  $p_add_dir : A string which contains a path to be added to the
               memorized path of each element in the list. 
  $p_remove_dir : A string which contains a path to be removed from
                  the memorized path of each element in the list, when
		  relevant.
Return value :
  true on success, false on error.
Sample 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (Optional '/' at the end)
  $v_list[2]="log/file.log";
  $tar_object->addModify($v_list, "install");
  // files are stored in the archive as :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... all the files and sub-dirs of data/
  //   install/file.log
Sample 2 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (Optional '/' at the end)
  $v_list[2]="log/file.log";
  $tar_object->addModify($v_list, "install", "dev");
  // files are stored in the archive as :
  //   install/file.txt
  //   install/data
  //   install/data/file1.txt
  //   install/data/... all the files and sub-dirs of data/
  //   install/log/file.log
How it works :
  If the archive does not exists it create it and add the files.
  If the archive does exists and is not compressed, it open it, jump
  before the last empty 512 bytes block (tar footer) and add the files
  at this point.
  If the archive does exists and is compressed, a temporary copy file
  is created. This temporary file is then 'gzip' read block by block
  until the last empty block. The new files are then added in the
  compressed file.
  The adding of files is done by going through the file/dir list,
  adding files per files, in a recursive way through the
  directory. Each time a path need to be added/removed it is done
  before writing the file header in the archive.

Method : add($p_filelist)
Description :
  This method add the files / directories listed in $p_filelist at the
  end of the existing archive. If the archive does not yet exists it
  is created. 
  The $p_filelist parameter can be an array of string, each string
  representing a filename or a directory name with their path if
  needed. It can also be a single string with names separated by a
  single blank. 
  See addModify() method for details and limitations.
Arguments :
  $p_filelist : An array of filenames and directory names, or a single
  string with names separated by a single blank space. 
Return value :
  true on success, false on error.
Sample 1 :
  $tar_object = new Archive_Tar("tarname.tar");
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (Optional '/' at the end)
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);
Sample 2 :
  $tar_object = new Archive_Tar("tarname.tgz", true);
  [...]
  $v_list[0]="dev/file.txt";
  $v_list[1]="dev/data/"; (Optional '/' at the end)
  $v_list[2]="log/file.log";
  $tar_object->add($v_list);
How it works :
  Simply call the addModify() method with the right parameters.

Method : addString($p_filename, $p_string, $p_datetime, $p_params)
Description :
  This method add a single string as a file at the
  end of the existing archive. If the archive does not yet exists it
  is created.
Arguments :
  $p_filename : A string which contains the full filename path
                that will be associated with the string.
  $p_string :   The content of the file added in the archive.
  $p_datetime : (Optional) Timestamp of the file (default = now)
  $p_params :   (Optional) Various file metadata:
                    stamp - As above, timestamp of the file
                    mode - UNIX-style permissions (default 0600)
                    type - Is this a regular file or link (see TAR
                           format spec for how to create a hard/symlink)
                    uid - UNIX-style user ID (default 0 = root)
                    gid - UNIX-style group ID (default 0 = root)
Return value :
  true on success, false on error.
Sample 1 :
  $v_archive = & new Archive_Tar($p_filename);
  $v_archive->setErrorHandling(PEAR_ERROR_PRINT);
  $v_result = $v_archive->addString('data/test.txt', 'This is the text of the string');
  $v_result = $v_archive->addString(
                  'data/test.sh',
                  "#!/bin/sh\necho 'Hello'",
                  time(),
                  array( "mode" => 0755, "uid" => 34 )
              );


Method : extract($p_path = "")
Description :
  This method extract all the content of the archive in the directory
  indicated by $p_path.If $p_path is optional, if not set the archive
  is extracted in the current directory. 
  While extracting a file, if the directory path does not exists it is
  created. 
  See extractModify() for details and limitations.
Arguments :
  $p_path : Optional path where the files/dir need to by extracted.
Return value :
  true on success, false on error.
Sample :
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->extract();
How it works :
  Simply call the extractModify() method with appropriate parameters.

Method : extractModify($p_path, $p_remove_path)
Description :
  This method extract all the content of the archive in the directory
  indicated by $p_path. When relevant the memorized path of the
  files/dir can be modified by removing the $p_remove_path path at the
  beginning of the file/dir path. 
  While extracting a file, if the directory path does not exists it is
  created. 
  While extracting a file, if the file already exists it is replaced
  without looking for last modification date. 
  While extracting a file, if the file already exists and is write
  protected, the extraction is aborted. 
  While extracting a file, if a directory with the same name already
  exists, the extraction is aborted. 
  While extracting a directory, if a file with the same name already
  exists, the extraction is aborted. 
  While extracting a file/directory if the destination directory exist
  and is write protected, or does not exist but can not be created,
  the extraction is aborted. 
  If after extraction an extracted file does not show the correct
  stored file size, the extraction is aborted. 
  When the extraction is aborted, a PEAR error text is set and false
  is returned. However the result can be a partial extraction that may
  need to be manually cleaned. 
Arguments :
  $p_path : The path of the directory where the files/dir need to by
            extracted. 
  $p_remove_path : Part of the memorized path that can be removed if
                   present at the beginning of the file/dir path. 
Return value :
  true on success, false on error.
Sample :
  // Imagine tarname.tar with files :
  //   dev/data/file.txt
  //   dev/data/log.txt
  //   readme.txt
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->extractModify("install", "dev");
  // Files will be extracted there :
  //   install/data/file.txt
  //   install/data/log.txt
  //   install/readme.txt
How it works :
  Open the archive and call a more generic function that can extract
  only a part of the archive or all the archive. 
  See extractList() method for more details.

Method : extractInString($p_filename)
Description :
  This method extract from the archive one file identified by $p_filename.
  The return value is a string with the file content, or NULL on error. 
Arguments :
  $p_filename : The path of the file to extract in a string. 
Return value :
  a string with the file content or NULL.
Sample :
  // Imagine tarname.tar with files :
  //   dev/data/file.txt
  //   dev/data/log.txt
  //   dev/readme.txt
  $v_archive = & new Archive_Tar('tarname.tar');
  $v_archive->setErrorHandling(PEAR_ERROR_PRINT);
  $v_string = $v_archive->extractInString('dev/readme.txt');
  echo $v_string;

Method : listContent()
Description :
  This method returns an array of arrays that describe each
  file/directory present in the archive. 
  The array is not sorted, so it show the position of the file in the
  archive. 
  The file informations are :
    $file[filename] : Name and path of the file/dir.
    $file[mode] : File permissions (result of fileperms())
    $file[uid] : user id
    $file[gid] : group id
    $file[size] : filesize
    $file[mtime] : Last modification time (result of filemtime())
    $file[typeflag] : "" for file, "5" for directory
Arguments :
Return value :
  An array of arrays or 0 on error.
Sample :
  $tar_object = new Archive_Tar("tarname.tar");
  if (($v_list  =  $tar_object->listContent()) != 0)
    for ($i=0; $i<sizeof($v_list); $i++)
    {
      echo "Filename :'".$v_list[$i][filename]."'<br>";
      echo " .size :'".$v_list[$i][size]."'<br>";
      echo " .mtime :'".$v_list[$i][mtime]."' (".
           date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>";
      echo " .mode :'".$v_list[$i][mode]."'<br>";
      echo " .uid :'".$v_list[$i][uid]."'<br>";
      echo " .gid :'".$v_list[$i][gid]."'<br>";
      echo " .typeflag :'".$v_list[$i][typeflag]."'<br>";
    }
How it works :
  Call the same function as an extract however with a flag to only go
  through the archive without extracting the files. 

Method : extractList($p_filelist, $p_path = "", $p_remove_path = "")
Description :
  This method extract from the archive only the files indicated in the
  $p_filelist. These files are extracted in the current directory or
  in the directory indicated by the optional $p_path parameter. 
  If indicated the $p_remove_path can be used in the same way as it is
  used in extractModify() method. 
Arguments :
  $p_filelist : An array of filenames and directory names, or a single
                string with names separated by a single blank space. 
  $p_path : The path of the directory where the files/dir need to by
            extracted. 
  $p_remove_path : Part of the memorized path that can be removed if
                   present at the beginning of the file/dir path. 
Return value :
  true on success, false on error.
Sample :
  // Imagine tarname.tar with files :
  //   dev/data/file.txt
  //   dev/data/log.txt
  //   readme.txt
  $tar_object = new Archive_Tar("tarname.tar");
  $tar_object->extractList("dev/data/file.txt readme.txt", "install",
                           "dev");
  // Files will be extracted there :
  //   install/data/file.txt
  //   install/readme.txt
How it works :
  Go through the archive and extract only the files present in the
  list.