[ Mini Kiebo ]
Server: Windows NT AKFAR_SERVER 10.0 build 26200 (Windows 10) AMD64
Path:
D:
/
xampp.bak
/
php
/
docs
/
Archive_Tar
/
docs
/
[
Home
]
File: Archive_Tar.txt
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.