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').
