Chris@18: Documentation for class Archive_Tar Chris@18: =================================== Chris@18: Last update : 2001-08-15 Chris@18: Chris@18: Chris@18: Chris@18: Overview : Chris@18: ---------- Chris@18: Chris@18: The Archive_Tar class helps in creating and managing GNU TAR format Chris@18: files compressed by GNU ZIP or not. Chris@18: The class offers basic functions like creating an archive, adding Chris@18: files in the archive, extracting files from the archive and listing Chris@18: the archive content. Chris@18: It also provide advanced functions that allow the adding and Chris@18: extraction of files with path manipulation. Chris@18: Chris@18: Chris@18: Sample : Chris@18: -------- Chris@18: Chris@18: // ----- Creating the object (uncompressed archive) Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->setErrorHandling(PEAR_ERROR_PRINT); Chris@18: Chris@18: // ----- Creating the archive Chris@18: $v_list[0]="file.txt"; Chris@18: $v_list[1]="data/"; Chris@18: $v_list[2]="file.log"; Chris@18: $tar_object->create($v_list); Chris@18: Chris@18: // ----- Adding files Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->add($v_list); Chris@18: Chris@18: // ----- Adding more files Chris@18: $tar_object->add("release/newfile.log release/readme.txt"); Chris@18: Chris@18: // ----- Listing the content Chris@18: if (($v_list = $tar_object->listContent()) != 0) Chris@18: for ($i=0; $i"; Chris@18: echo " .size :'".$v_list[$i][size]."'
"; Chris@18: echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")
"; Chris@18: echo " .mode :'".$v_list[$i][mode]."'
"; Chris@18: echo " .uid :'".$v_list[$i][uid]."'
"; Chris@18: echo " .gid :'".$v_list[$i][gid]."'
"; Chris@18: echo " .typeflag :'".$v_list[$i][typeflag]."'
"; Chris@18: } Chris@18: Chris@18: // ----- Extracting the archive in directory "install" Chris@18: $tar_object->extract("install"); Chris@18: Chris@18: Chris@18: Public arguments : Chris@18: ------------------ Chris@18: Chris@18: None Chris@18: Chris@18: Chris@18: Public Methods : Chris@18: ---------------- Chris@18: Chris@18: Method : Archive_Tar($p_tarname, $compress = null) Chris@18: Description : Chris@18: Archive_Tar Class constructor. This flavour of the constructor only Chris@18: declare a new Archive_Tar object, identifying it by the name of the Chris@18: tar file. Chris@18: If the compress argument is set the tar will be read or created as a Chris@18: gzip or bz2 compressed TAR file. Chris@18: Arguments : Chris@18: $p_tarname : A valid filename for the tar archive file. Chris@18: $p_compress : can be null, 'gz' or 'bz2'. For Chris@18: compatibility reason it can also be true. This Chris@18: parameter indicates if gzip or bz2 compression Chris@18: is required. Chris@18: Return value : Chris@18: The Archive_Tar object. Chris@18: Sample : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object_compressed = new Archive_Tar("tarname.tgz", true); Chris@18: How it works : Chris@18: Initialize the object. Chris@18: Chris@18: Method : create($p_filelist) Chris@18: Description : Chris@18: This method creates the archive file and add the files / directories Chris@18: that are listed in $p_filelist. Chris@18: If the file already exists and is writable, it is replaced by the Chris@18: new tar. It is a create and not an add. If the file exists and is Chris@18: read-only or is a directory it is not replaced. The method return Chris@18: false and a PEAR error text. Chris@18: The $p_filelist parameter can be an array of string, each string Chris@18: representing a filename or a directory name with their path if Chris@18: needed. It can also be a single string with names separated by a Chris@18: single blank. Chris@18: See also createModify() method for more details. Chris@18: Arguments : Chris@18: $p_filelist : An array of filenames and directory names, or a single Chris@18: string with names separated by a single blank space. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample 1 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling Chris@18: $v_list[0]="file.txt"; Chris@18: $v_list[1]="data/"; (Optional '/' at the end) Chris@18: $v_list[2]="file.log"; Chris@18: $tar_object->create($v_list); Chris@18: Sample 2 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling Chris@18: $tar_object->create("file.txt data/ file.log"); Chris@18: How it works : Chris@18: Just calling the createModify() method with the right parameters. Chris@18: Chris@18: Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "") Chris@18: Description : Chris@18: This method creates the archive file and add the files / directories Chris@18: that are listed in $p_filelist. Chris@18: If the file already exists and is writable, it is replaced by the Chris@18: new tar. It is a create and not an add. If the file exists and is Chris@18: read-only or is a directory it is not replaced. The method return Chris@18: false and a PEAR error text. Chris@18: The $p_filelist parameter can be an array of string, each string Chris@18: representing a filename or a directory name with their path if Chris@18: needed. It can also be a single string with names separated by a Chris@18: single blank. Chris@18: The path indicated in $p_remove_dir will be removed from the Chris@18: memorized path of each file / directory listed when this path Chris@18: exists. By default nothing is removed (empty path "") Chris@18: The path indicated in $p_add_dir will be added at the beginning of Chris@18: the memorized path of each file / directory listed. However it can Chris@18: be set to empty "". The adding of a path is done after the removing Chris@18: of path. Chris@18: The path add/remove ability enables the user to prepare an archive Chris@18: for extraction in a different path than the origin files are. Chris@18: See also addModify() method for file adding properties. Chris@18: Arguments : Chris@18: $p_filelist : An array of filenames and directory names, or a single Chris@18: string with names separated by a single blank space. Chris@18: $p_add_dir : A string which contains a path to be added to the Chris@18: memorized path of each element in the list. Chris@18: $p_remove_dir : A string which contains a path to be removed from Chris@18: the memorized path of each element in the list, when Chris@18: relevant. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample 1 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling Chris@18: $v_list[0]="file.txt"; Chris@18: $v_list[1]="data/"; (Optional '/' at the end) Chris@18: $v_list[2]="file.log"; Chris@18: $tar_object->createModify($v_list, "install"); Chris@18: // files are stored in the archive as : Chris@18: // install/file.txt Chris@18: // install/data Chris@18: // install/data/file1.txt Chris@18: // install/data/... all the files and sub-dirs of data/ Chris@18: // install/file.log Chris@18: Sample 2 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; (Optional '/' at the end) Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->createModify($v_list, "install", "dev"); Chris@18: // files are stored in the archive as : Chris@18: // install/file.txt Chris@18: // install/data Chris@18: // install/data/file1.txt Chris@18: // install/data/... all the files and sub-dirs of data/ Chris@18: // install/log/file.log Chris@18: How it works : Chris@18: Open the file in write mode (erasing the existing one if one), Chris@18: call the _addList() method for adding the files in an empty archive, Chris@18: add the tar footer (512 bytes block), close the tar file. Chris@18: Chris@18: Chris@18: Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="") Chris@18: Description : Chris@18: This method add the files / directories listed in $p_filelist at the Chris@18: end of the existing archive. If the archive does not yet exists it Chris@18: is created. Chris@18: The $p_filelist parameter can be an array of string, each string Chris@18: representing a filename or a directory name with their path if Chris@18: needed. It can also be a single string with names separated by a Chris@18: single blank. Chris@18: The path indicated in $p_remove_dir will be removed from the Chris@18: memorized path of each file / directory listed when this path Chris@18: exists. By default nothing is removed (empty path "") Chris@18: The path indicated in $p_add_dir will be added at the beginning of Chris@18: the memorized path of each file / directory listed. However it can Chris@18: be set to empty "". The adding of a path is done after the removing Chris@18: of path. Chris@18: The path add/remove ability enables the user to prepare an archive Chris@18: for extraction in a different path than the origin files are. Chris@18: If a file/dir is already in the archive it will only be added at the Chris@18: end of the archive. There is no update of the existing archived Chris@18: file/dir. However while extracting the archive, the last file will Chris@18: replace the first one. This results in a none optimization of the Chris@18: archive size. Chris@18: If a file/dir does not exist the file/dir is ignored. However an Chris@18: error text is send to PEAR error. Chris@18: If a file/dir is not readable the file/dir is ignored. However an Chris@18: error text is send to PEAR error. Chris@18: If the resulting filename/dirname (after the add/remove option or Chris@18: not) string is greater than 99 char, the file/dir is Chris@18: ignored. However an error text is send to PEAR error. Chris@18: Arguments : Chris@18: $p_filelist : An array of filenames and directory names, or a single Chris@18: string with names separated by a single blank space. Chris@18: $p_add_dir : A string which contains a path to be added to the Chris@18: memorized path of each element in the list. Chris@18: $p_remove_dir : A string which contains a path to be removed from Chris@18: the memorized path of each element in the list, when Chris@18: relevant. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample 1 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: [...] Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; (Optional '/' at the end) Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->addModify($v_list, "install"); Chris@18: // files are stored in the archive as : Chris@18: // install/file.txt Chris@18: // install/data Chris@18: // install/data/file1.txt Chris@18: // install/data/... all the files and sub-dirs of data/ Chris@18: // install/file.log Chris@18: Sample 2 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: [...] Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; (Optional '/' at the end) Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->addModify($v_list, "install", "dev"); Chris@18: // files are stored in the archive as : Chris@18: // install/file.txt Chris@18: // install/data Chris@18: // install/data/file1.txt Chris@18: // install/data/... all the files and sub-dirs of data/ Chris@18: // install/log/file.log Chris@18: How it works : Chris@18: If the archive does not exists it create it and add the files. Chris@18: If the archive does exists and is not compressed, it open it, jump Chris@18: before the last empty 512 bytes block (tar footer) and add the files Chris@18: at this point. Chris@18: If the archive does exists and is compressed, a temporary copy file Chris@18: is created. This temporary file is then 'gzip' read block by block Chris@18: until the last empty block. The new files are then added in the Chris@18: compressed file. Chris@18: The adding of files is done by going through the file/dir list, Chris@18: adding files per files, in a recursive way through the Chris@18: directory. Each time a path need to be added/removed it is done Chris@18: before writing the file header in the archive. Chris@18: Chris@18: Method : add($p_filelist) Chris@18: Description : Chris@18: This method add the files / directories listed in $p_filelist at the Chris@18: end of the existing archive. If the archive does not yet exists it Chris@18: is created. Chris@18: The $p_filelist parameter can be an array of string, each string Chris@18: representing a filename or a directory name with their path if Chris@18: needed. It can also be a single string with names separated by a Chris@18: single blank. Chris@18: See addModify() method for details and limitations. Chris@18: Arguments : Chris@18: $p_filelist : An array of filenames and directory names, or a single Chris@18: string with names separated by a single blank space. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample 1 : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: [...] Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; (Optional '/' at the end) Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->add($v_list); Chris@18: Sample 2 : Chris@18: $tar_object = new Archive_Tar("tarname.tgz", true); Chris@18: [...] Chris@18: $v_list[0]="dev/file.txt"; Chris@18: $v_list[1]="dev/data/"; (Optional '/' at the end) Chris@18: $v_list[2]="log/file.log"; Chris@18: $tar_object->add($v_list); Chris@18: How it works : Chris@18: Simply call the addModify() method with the right parameters. Chris@18: Chris@18: Method : addString($p_filename, $p_string, $p_datetime, $p_params) Chris@18: Description : Chris@18: This method add a single string as a file at the Chris@18: end of the existing archive. If the archive does not yet exists it Chris@18: is created. Chris@18: Arguments : Chris@18: $p_filename : A string which contains the full filename path Chris@18: that will be associated with the string. Chris@18: $p_string : The content of the file added in the archive. Chris@18: $p_datetime : (Optional) Timestamp of the file (default = now) Chris@18: $p_params : (Optional) Various file metadata: Chris@18: stamp - As above, timestamp of the file Chris@18: mode - UNIX-style permissions (default 0600) Chris@18: type - Is this a regular file or link (see TAR Chris@18: format spec for how to create a hard/symlink) Chris@18: uid - UNIX-style user ID (default 0 = root) Chris@18: gid - UNIX-style group ID (default 0 = root) Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample 1 : Chris@18: $v_archive = & new Archive_Tar($p_filename); Chris@18: $v_archive->setErrorHandling(PEAR_ERROR_PRINT); Chris@18: $v_result = $v_archive->addString('data/test.txt', 'This is the text of the string'); Chris@18: $v_result = $v_archive->addString( Chris@18: 'data/test.sh', Chris@18: "#!/bin/sh\necho 'Hello'", Chris@18: time(), Chris@18: array( "mode" => 0755, "uid" => 34 ) Chris@18: ); Chris@18: Chris@18: Chris@18: Method : extract($p_path = "") Chris@18: Description : Chris@18: This method extract all the content of the archive in the directory Chris@18: indicated by $p_path.If $p_path is optional, if not set the archive Chris@18: is extracted in the current directory. Chris@18: While extracting a file, if the directory path does not exists it is Chris@18: created. Chris@18: See extractModify() for details and limitations. Chris@18: Arguments : Chris@18: $p_path : Optional path where the files/dir need to by extracted. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->extract(); Chris@18: How it works : Chris@18: Simply call the extractModify() method with appropriate parameters. Chris@18: Chris@18: Method : extractModify($p_path, $p_remove_path) Chris@18: Description : Chris@18: This method extract all the content of the archive in the directory Chris@18: indicated by $p_path. When relevant the memorized path of the Chris@18: files/dir can be modified by removing the $p_remove_path path at the Chris@18: beginning of the file/dir path. Chris@18: While extracting a file, if the directory path does not exists it is Chris@18: created. Chris@18: While extracting a file, if the file already exists it is replaced Chris@18: without looking for last modification date. Chris@18: While extracting a file, if the file already exists and is write Chris@18: protected, the extraction is aborted. Chris@18: While extracting a file, if a directory with the same name already Chris@18: exists, the extraction is aborted. Chris@18: While extracting a directory, if a file with the same name already Chris@18: exists, the extraction is aborted. Chris@18: While extracting a file/directory if the destination directory exist Chris@18: and is write protected, or does not exist but can not be created, Chris@18: the extraction is aborted. Chris@18: If after extraction an extracted file does not show the correct Chris@18: stored file size, the extraction is aborted. Chris@18: When the extraction is aborted, a PEAR error text is set and false Chris@18: is returned. However the result can be a partial extraction that may Chris@18: need to be manually cleaned. Chris@18: Arguments : Chris@18: $p_path : The path of the directory where the files/dir need to by Chris@18: extracted. Chris@18: $p_remove_path : Part of the memorized path that can be removed if Chris@18: present at the beginning of the file/dir path. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample : Chris@18: // Imagine tarname.tar with files : Chris@18: // dev/data/file.txt Chris@18: // dev/data/log.txt Chris@18: // readme.txt Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->extractModify("install", "dev"); Chris@18: // Files will be extracted there : Chris@18: // install/data/file.txt Chris@18: // install/data/log.txt Chris@18: // install/readme.txt Chris@18: How it works : Chris@18: Open the archive and call a more generic function that can extract Chris@18: only a part of the archive or all the archive. Chris@18: See extractList() method for more details. Chris@18: Chris@18: Method : extractInString($p_filename) Chris@18: Description : Chris@18: This method extract from the archive one file identified by $p_filename. Chris@18: The return value is a string with the file content, or NULL on error. Chris@18: Arguments : Chris@18: $p_filename : The path of the file to extract in a string. Chris@18: Return value : Chris@18: a string with the file content or NULL. Chris@18: Sample : Chris@18: // Imagine tarname.tar with files : Chris@18: // dev/data/file.txt Chris@18: // dev/data/log.txt Chris@18: // dev/readme.txt Chris@18: $v_archive = & new Archive_Tar('tarname.tar'); Chris@18: $v_archive->setErrorHandling(PEAR_ERROR_PRINT); Chris@18: $v_string = $v_archive->extractInString('dev/readme.txt'); Chris@18: echo $v_string; Chris@18: Chris@18: Method : listContent() Chris@18: Description : Chris@18: This method returns an array of arrays that describe each Chris@18: file/directory present in the archive. Chris@18: The array is not sorted, so it show the position of the file in the Chris@18: archive. Chris@18: The file informations are : Chris@18: $file[filename] : Name and path of the file/dir. Chris@18: $file[mode] : File permissions (result of fileperms()) Chris@18: $file[uid] : user id Chris@18: $file[gid] : group id Chris@18: $file[size] : filesize Chris@18: $file[mtime] : Last modification time (result of filemtime()) Chris@18: $file[typeflag] : "" for file, "5" for directory Chris@18: Arguments : Chris@18: Return value : Chris@18: An array of arrays or 0 on error. Chris@18: Sample : Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: if (($v_list = $tar_object->listContent()) != 0) Chris@18: for ($i=0; $i"; Chris@18: echo " .size :'".$v_list[$i][size]."'
"; Chris@18: echo " .mtime :'".$v_list[$i][mtime]."' (". Chris@18: date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")
"; Chris@18: echo " .mode :'".$v_list[$i][mode]."'
"; Chris@18: echo " .uid :'".$v_list[$i][uid]."'
"; Chris@18: echo " .gid :'".$v_list[$i][gid]."'
"; Chris@18: echo " .typeflag :'".$v_list[$i][typeflag]."'
"; Chris@18: } Chris@18: How it works : Chris@18: Call the same function as an extract however with a flag to only go Chris@18: through the archive without extracting the files. Chris@18: Chris@18: Method : extractList($p_filelist, $p_path = "", $p_remove_path = "") Chris@18: Description : Chris@18: This method extract from the archive only the files indicated in the Chris@18: $p_filelist. These files are extracted in the current directory or Chris@18: in the directory indicated by the optional $p_path parameter. Chris@18: If indicated the $p_remove_path can be used in the same way as it is Chris@18: used in extractModify() method. Chris@18: Arguments : Chris@18: $p_filelist : An array of filenames and directory names, or a single Chris@18: string with names separated by a single blank space. Chris@18: $p_path : The path of the directory where the files/dir need to by Chris@18: extracted. Chris@18: $p_remove_path : Part of the memorized path that can be removed if Chris@18: present at the beginning of the file/dir path. Chris@18: Return value : Chris@18: true on success, false on error. Chris@18: Sample : Chris@18: // Imagine tarname.tar with files : Chris@18: // dev/data/file.txt Chris@18: // dev/data/log.txt Chris@18: // readme.txt Chris@18: $tar_object = new Archive_Tar("tarname.tar"); Chris@18: $tar_object->extractList("dev/data/file.txt readme.txt", "install", Chris@18: "dev"); Chris@18: // Files will be extracted there : Chris@18: // install/data/file.txt Chris@18: // install/readme.txt Chris@18: How it works : Chris@18: Go through the archive and extract only the files present in the Chris@18: list. Chris@18: