--- /dev/null
+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 = false)
+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 compressed TAR file.
+Arguments :
+ $p_tarname : A valid filename for the tar archive file.
+ $p_compress : true/false. Indicate if the archive need to be
+ compressed or not.
+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 : 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 : 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.
+
projects / php / commitdiff