PhpConcept
 
 

PclTar 1.3 - PhpConcept Library Tar

PclTar library offers archive and extraction functions using GNU TAR format.

 
 

Functions - Manual - Downloads - What's new - Historic

 
 
Functions
 
 

 

PclTar offer the ability to archive a list of files or directories with or without compression. The archives created by PclTar are readeable by most of gzip/tar applications and by the Windows WinZip application.

PclTar offer the ability to extract files contained in a GNU TAR archive, compressed or not. Only the archive using POSIX headers are understand.

The application PhpZip use PclTar, have a look on it to see what can be done by PclTar.

PclTar 1.3 is the fourth version of PclTar, but some bugs may still be present. You can track the bugs by using the PclTrace library released in the PclTar package. In any case, if you find a bug, please let us know ! (webmaster@phpconcept.net).

PclTar 1.3 offers :

1. Archive creation :

  • Create a GNU TAR or Compressed GNU TAR (using GNU ZIP library zlib) archive,
  • Optionally add a list of files or folders while creating the archive,
  • The stored path of the files / directories can be manipulated by adding a path or removing part of the file path. This is usefull when you want to have the files extracted in a different path than the original files.

2. Adding files or directories :

  • Add a list of files or a list of directories in an existing archive,
  • The stored path of the files / directories can be manipulated by adding a path or removing part of the file path. This is usefull when you want to have the files extracted in a different path than the original files.

3. Extraction :

  • Extract all the content of the archive,
  • Extract part of the archive by giving a list of files or folders,
  • Extract part of the archive by giving a range of the files or folders indexes to extract,
  • Extraction is done in the current folder or a specific folder,
  • Relative path of the archived files are memorized and restored at the extraction. You can also ignore part of the stored path while extracting the files.

4. Content list :

  • Read the list of files archived and their properties.

5. Delete files :

  • Remove a list of files from the archive.

6. Update files :

  • Add a list of files / directories in the archive.
  • If the file already exists and was modified recently, it will replace the stored file in the archive.
  • If the file is not present in the archive it is added at the end.

7. Merge archives :

  • Add the content of an archive at the end of an archive.
  • Each archive can have different compression option.

 

 
 
 
 

Functions - Manual - Downloads - What's new - Historic

 
 
User Manual
 
 

 

Table of content

Functions description

The library is made of one file : pcltar.lib.php3 and two secondary libraries, the first one for trace management (pcltrace.lib.php3) and the other one for error management (pclerror.lib.php3).

The library define public functions available for the user, and internal functions which are called by the first ones. Only the public functions are described in this manual.

Please note that effort for compatibility will only be done on public functions while releasing new version. Modifications will be indicated in release notes. Internal function must not be used directly and may change without any notice.

Functions are also detailed in their header in the PHP file, here is only an other description:

 

PclTarCreate($p_tarname, $p_list, $p_mode, $p_add_dir, $p_remove_dir) :

Create a new archive with name $p_tarname. If files or folders are listed in $p_list, they will be added.
If the archive extension ($p_tarname) is '.tar', then the archive will not be compressed (standard GNU TAR), if it is '.tar.gz' or '.tgz', the archive will be compressed with gzip functions. If you want to use an other extension, the archive format must be indicated in $p_mode ('tar' ou 'tgz').

The $p_list, $p_add_dir and $p_remove_dir parameters and the adding methodology are fully described in PclTarAddList().

 

PclTarAddList($p_tarname, $p_list, $p_add_dir, $p_remove_dir, $p_mode) :

Add to an already existing archive a list of files or folders which names are in $p_list.
Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

The $p_list parameter may be :

  • An array of strings, each one representing the name of a file or a folder,
  • A string with the name of a file or a folder to archive,
  • A string which contains a list of file or folder names, separated by a space character.

PclTarAddList() automatically recognize if the given name is a file or a folder and if it is readable or not. If it is a folder, all the files and sub-folders are added in the archive (kind of recursive function).
Note that since version 1.2 if a folder is empty, a directory entry is created for this folder without files inside.

The relative path of the file is stored in the archive, however it is reduced as far as possible :

  • data/../include/file.txt will give include/file.txt
  • ./include/file.txt will give include/file.txt
  • ../../include/file.txt will give include/file.txt
  • etc ...

$p_add_dir and $p_remove_dir gives the ability to store with the file / directory a path which is not the real path of the original file / directory :

When using PclTarAddList("archive.tgz", "dev/include/conf.txt", "release", "dev"), the archive will contain a file with path "release/include/conf.txt".

While adding a large number of files the maximum script execution time may be reached. Be carefull also with folder when their contents are unknown.

 

PclTarAdd($p_tarname, $p_list) :

This function must not be used anymore. Please prefer PclTarAddList().

 

PclTarList($p_tarname, $p_mode) :

Give the list of files included int he archive $p_tarname.
The return value of the function is an array which contains an array of files properties on success, 0 on error.
Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

The files properties are :

  • list[0][filename] : filename of file 0,
  • list[0][mode] : Access mode of file 0 (see chmod()),
  • list[0][size] : Size of file 0,
  • list[0][uid] : Owner of file 0,
  • list[0][gid] : Group of file 0,
  • list[0][mtime] : Last modification date of file 0,
  • list[0][typeflag] : File type 0 (0 for "file", 1 for "link", 5 for "directory"),
  • list[0][status] : Status of the action on the file (ok, added, updated, not_updated, already_a_directory, write_protected, newer_exist, path_creation_fail, write_error).

 

PclTarExtract($p_tarname, $p_path, $p_remove_path, $p_mode) :

Extract all the files of the archive in the directory $p_path. The relative path of each file is maintained relative to $p_path. However, by using $p_remove_path the first part of the archived file path can be removed.

If a file is stored as "dev/include/conf.txt" in the archive and extracted by PclTarExtract("archive.tgz", "data", "dev"), the file will be written in "data/include/conf.txt".

If a file with the same name exists it will be replaced only if the archived file is newer. If older, the file is not extracted and the "status" field in the file descriptor is set with value "newer_exist".
While extracting a file if a directory exists with the same name, the file is not extracted. The "status" field in the file descriptor is set with value "already_a_directory".

While extracting a file if a file exists with the same name and is write protected, the file is not extracted. The "status" field in the file descriptor is set with value "write_protected".
The same behavior is implemented for directory extracting.

The function returns the extracted list of files in the same format as PclTarList().

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

 

PclTarExtractList($p_tarname, $p_list, $p_path, $p_remove_path, $p_mode) :

This function is the same as PcltarExtract(), but only the files or folders indicated in $p_list are extracted.

 

PclTarExtractIndex($p_tarname, $p_index, $p_path, $p_remove_path, $p_mode) :

This function is the same as PcltarExtract(), but only the files or folders which indexes in the archive are secified in the $p_index parameter are extracted.

The $p_index parameter is a single string with the index of the file or folder to extract, or several ranges of indexes of files/folders to extract. In this case th $p_index format is : '2,5-10,11,14,19-33', a list of values separated by a comma ','. Each value is an index or a range of indexes. The range is composed by two values (star and end included) separated by a '-'.
Please note that the $p_index format does not support any other characters than the numbers, ',' and '-'. (Spaces and ';' are not supported).

Moreover, if the index identify a folder in the archive, only the folder is created (extracted) but not the sub-directories and nor the files of this folder.

 

PclTarDelete($p_tarname, $p_filelist, $p_mode) :

Delete the files indicated in list $p_filelist from the archive $p_tarname.

The $p_filelist can be an array of filenames or directories, or a single string containing a list of filenames or directories separated by a single space.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

When a folder is specified to be removed, all the sub-directories and files which are archived under this folder are also removed (new as of release 1.3).

 

PclTarUpdate($p_tarname, $p_filelist, $p_mode, $p_add_dir, $p_remove_dir) :

The files indicated in $p_filelist are updated in the archive $p_tarname if their last modification date is better than the one already stored. If the file does not exist in the archive, it is added at the end (same behavior as PclTarAddList()).

The $p_filelist can be an array of filenames or directories, or a single string containing a list of filenames or directories separated by a single space.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

PclTarMerge($p_tarname, $p_tarname_add, $p_mode, $p_mode_add) :

The content of archive $p_tarname_add is added at the end of archive $p_tarname. $p_tarname_add is not modified. The type of archives (compressed or not) can be mixed. Each archive will keep its origin mode.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode and $p_mode_add if the archive is compressed ('tgz') or not ('tar').

 

Archive structure

Only POSIX header are supported.

The official stricture of GNU TAR archive, with all the values of file properties can be found on the GNU web site : GNU TAR Standard Format.

Supported PHP language

PclTar was developped with PHP 3.0.17.

 

Supported spoken languages

The source code is documented in english, the general description and user guide on PhpConcept is in english and in french.

 
 
 
 

Functions - Manual - Downloads - What's new - Historic

 
 
What's new
 
 

 

Version 1.3 :

  • Add the function PclTarExtractIndex()
  • Correction of a bug with folders. When folder are archived, the size is sometime not null. PclTar now force the size to be zero when the archived file is a folder. When un-archiving the size is also forced to 0 when the item is a folder.
  • Modify function PclTarDelete() : When you give the name of a directory to be deleted, the directory entry and the files of the directory are deleted.
  • Correct bug in the path add/remove options in functions. When a path is removed, sometime the 'home' path was not.
  • Correct a bug in directory extraction : The directory is created but the status in the resulting file list is set to write_error.
  • Correct a bug : missing update of file cache (clearstatcache())

Version 1.2 :

  • Add a new function PclTarMerge(), which allow to merge two archives.
  • Add the add_path/remove_path ability to the PclTarCreate() function
  • The add list/dir function now support empty directory. Before version 1.2, directories where not identified as separate entries, there where in the archive, only if there is at least one file.
  • Optimization of PclTarHandleAddList()

Version 1.1 :

  • Adding check of header checksum while extracting a file from the archive,
  • Enhancement in POSIX header creation. In the first version PclTar use a temporary file for checksum calculation. It is now directly computed.
  • Adding field "status" in file description, remove fields "link", "magic", "version", "uname", "gname", "devmajor" and "devminor", because they do not carry interesting info.
  • While extracting, a check is done if the file exists or not. If an error occurs in the file extraction, the file is skipped, and the function tries to extract the next one. In previous release, the extraction was stopped.
  • While extracting a file, the mtime is now updated with the value stored in the archive.
    Note that the mode (R/W) is not set today (default RW).
  • New function PclTarDelete($tarname, $filelist), which deletes the files specified in $filelist.
  • New function PclTarUpdate(), which replace old files with new ones (depending of last modification date). If the file does not exist, it is added at the end of the archive.
  • Values for the file properties array :
    • filename (with path),
    • size,
    • mode (decimal value of the octal value),
    • uid,
    • gid,
    • mtime (last modification date like time() function result),
    • typeflag ("0" or "" = file, "5" = directory, "1" = link),
    • status (ok, added, updated, not_updated, already_a_directory,
      write_protected, newer_exist, path_creation_fail, write_error)
  • Add a "remove path" property in the extract functions. This allow to extract file in an other directory than the expected directory.
  • Add new function PclTarAddList()
  • Add parameter $p_mode in PclTarList()

 

 
 
 
 

Functions - Manual - Downloads - What's new - Historic

 
 
Historic
 
 

 

Version 1.3 :

Add a new function, improvments and bug corrections. January 2002.

Version 1.2 :

Official distribution of Version 1.1, and some new functions and improvment. August 2001.

Version 1.1 :

Not released version ! Version 1.1 was distributed with PhpZip 1.6, but was never distributed as a stand alone application. This is only because I didn't take the time to document it ....

Version 1.0 :

First release of PclTar. March 2001.

 

 
 
 
 

Functions - Manual - Downloads - What's new - Historic

 

Member login - Stats
Copyright 2003 - PhpConcept

Powered by PcWeb