476 lines
		
	
	
		
			19 KiB
		
	
	
	
		
			Plaintext
		
	
	
	
	
	
		
		
			
		
	
	
			476 lines
		
	
	
		
			19 KiB
		
	
	
	
		
			Plaintext
		
	
	
	
	
	
| 
								 | 
							
								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. 
							 | 
						||
| 
								 | 
							
								
							 |