Subversion-Projekte lars-tiefland.php_share

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)

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.

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');

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.