La librairie
est composée d'un seul fichier : pcltar.lib.php3 et deux librairies
annexes, l'une de trace (pcltrace.lib.php3) et l'autre de gestion
d'erreurs (pclerror.lib.php3).
La librairie définit des fonctions publiques d'accès pour l'utilisateur,
ainsi que des fonctions internes appelées par les premières. Seules
les fonctions externes seront présentées dans ce manuel.
Il est à
noter que seules les fonctions publiques ferront l'objet d'un
effort de compatibilité ascendante d'une version sur l'autre
(dans le cas contraire, les modifications seront indiquées
dans la release note). Ce ne sera pas le cas des fonctions internes
qui ne doivent donc jamais être utilisées directement.
Les descriptions
des fonctions sont détaillées dans leur entête à l'intérieur
même des fichiers, voici donc un extract :
PclTarCreate($p_tarname,
$p_list, $p_mode, $p_add_dir, $p_remove_dir) :
Creation d'une
nouvelle archive ayant pour nom $p_tarname et contenant les fichiers
ou dossiers indiqués dans la liste $p_list.
Si l'extension de $p_tarname est '.tar' alors l'archive ne sera
pas compressée, si elle est '.tar.gz' ou '.tgz' elle sera compressée
en utilisant les fonctions gzip. Si vous souhaitez utiliser une
autre extension, le type d'archive souhaité doit être précisé
dans $p_mode ('tar' ou 'tgz').
La description
des paramètres $p_list, $p_add_dir et $p_remove_dir se
trouve dans PclTarAddList(), ainsi que la description de la méthode
d'ajout des fichiers dans la nouvelle archive.
PclTarAdd($p_tarname,
$p_list) :
Cette fonction
ne doit plus être utilisée, il faut lui préférer
PclTarAddList(). Elle reste cependant présente dans un
soucis de maintenance de l'existant.
PclTarAddList($p_tarname,
$p_list, $p_add_dir, $p_remove_dir, $p_mode) :
Ajoute à une
archive existante la liste des fichiers ou dossiers indiqués dans
$p_list.
Suivant l'extension de l'archive (.tar, .tar.gz ou .tgz) la fonction
va déterminer le type d'archive et agir en conséquence. Si vous
souhaitez utiliser une autre extension, le type d'archive souhaité
doit être précisé dans $p_mode ('tar' ou 'tgz').
Le paramètre
$p_list peut être :
- Soit une
liste de chaine de caractères représentant un
nom de fichier ou de dossier à archiver,
- Soit une
chaine de caractère représentant un nom de fichier
ou de dossier à archiver,
- Soit une
chaine de caractère représentant une liste de
nom de fichier ou de dossier à archiver séparés
par un espace.
PclTarAddList()
reconnait automatiquement si le nom donné est un fichier
ou un dossier, s'il est accessible en lecture ou non. S'il s'agit
d'un dossier il ouvre le dossier et ajoute tous les fichiers et
sous-dossiers de façon récursive.
A partir de la version 1.2, PclTar ajoute aussi dans l'archive
les dossiers qui ne possèdent aucun fichier.
Le chemin
relatif du fichier est mémorisé dans l'archive,
cependant celui-ci est réduit lorsque cela est nécessaire.
Ainsi les chemins suivant donneront :
- data/../include/file.txt
sera archivé en include/file.txt
- ./include/file.txt
sera archivé en include/file.txt
- ../../include/file.txt
sera archivé en include/file.txt
- etc ...
$p_add_dir
et $p_remove_dir permettent de mémoriser avec un fichier
un chemin qui n'est pas le chemin réel du fichier d'origine.
Lorsque l'on
fait PclTarAddList("archive.tgz", "dev/include/conf.txt",
"release", "dev"), l'archive contiendra un
fichier avec comme chemin "release/include/conf.txt".
Lors de l'ajout
d'un trés grand nombre de fichiers il faut être méfiant
quant au temps d'execution maximum alloué au process PHP
afin que celui-ci ne s'interrompe pas en cours d'archivage. On
se méfiera donc en particulier de l'ajout de dossier dont
on ne maitrise pas le contenu.
PclTarList($p_tarname)
:
Donne la liste
des fichiers contenu dans l'archive $p_tarname.
La fonction
retourne une liste contenant une liste de propriétés pour chaque
fichier, elle retourne 0 en cas d'erreur.
Suivant l'extension de l'archive (.tar, .tar.gz ou .tgz) la fonction
va déterminer le type d'archive et agir en conséquence. Si vous
souhaitez utiliser une autre extension, le type d'archive souhaité
doit être précisé dans $p_mode ('tar' ou 'tgz').
Les propriétés
de chaque fichier correspondent dans la première version
(1.0) à une liste exhautive des informations se trouvant
dans les header POSIX des archives GNU TAR. La plupart de ces
informations sont inutiles, et seuls les informations suivantes
seront maintenues dans les futures versions :
- list[0][filename]
: Nom du fichier 0,
- list[0][mode]
: Mode d'accès du fichier 0 (voir chmod()),
- list[0][size]
: Taille du fichier 0,
- list[0][uid]
: Owner du fichier 0,
- list[0][gid]
: Groupe du fichier 0,
- list[0][mtime]
: Date de dernière modification du fichier 0,
- list[0][typeflag]
: Type du fichier 0 (0 pour "fichier", 1 pour "link",
5 pour "directory"),
- list[0][status]
: Résultat de l'action sur un fichier (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) :
Extrait tous
les fichiers de l'archive dans le dossier $p_path. Le chemin relatif
de chaque fichier est maintenu de façon relative à
$p_path. Cependant en utilisant le paramètre optionnel
$p_remove_path, une partie du chemin mémorisé peut
être ignoré.
Si un fichier
est mémorisé "dev/include/conf.txt" dans
l'archive et extrait par PclTarExtract("archive.tgz",
"data", "dev"), le fichier se retrouvera dans
"data/include/conf.txt".
Si un fichier
avec le même nom existe il sera remplacé que si celui
de l'archive est plus récent. Sinon le fichier n'est pas
extrait et le champ status du descripteur de fichier prendra comme
valeur "newer_exist".
Lors de l'extraction d'un fichier, si un dossier existe avec le
méme nom, le fichier n'est pas extrait. Le champs "status"
prend la valeur "already_a_directory".
Lors de l'extraction
d'un fichier, si un fichier existe et est protégé
en écriture, le fichier n'est pas extrait. Le champs "status"
prend la valeur "write_protected".
Le même comportement est réalisé pour les
dossiers.
La fonction
retourne la liste de fichiers extraits avec le même format
que celui de PclTarList().
Suivant l'extension
de l'archive (.tar, .tar.gz ou .tgz) la fonction va déterminer
le type d'archive et agir en conséquence. Si vous souhaitez utiliser
une autre extension, le type d'archive souhaité doit être précisé
dans $p_mode ('tar' ou 'tgz').
PclTarExtractList($p_tarname,
$p_list, $p_path, $p_remove_path, $p_mode) :
Cette fonction
est similaire à la précédente mais n'extrait que les fichiers
ou dossiers indiqués dans $p_list.
PclTarExtractIndex($p_tarname,
$p_index, $p_path, $p_remove_path, $p_mode) :
Cette fonction
est similaire à PclTarExtract(), mais elle n'extrait que les fichiers
et dossiers dont les index dans l'archive sont spécifiés
dans $p_index.
Le paramètre
$p_index est soit une simple chaine de catactère contenant
l'index unique du fichier/dossier à extraire, soit un ensemble
d'intervalles d'index des fichiers à extraires. Dans ce
dernier cas le format de $p_index est le suivant : '2,5-10,11,14,19-33',
c'est à dire une suite de valeurs séparées
par des ','. Chaque valeur est soit un index unique, soit un intervalle.
Il est alors composé de deux index (début et fin
inclus) séparés par '-'.
A noter que le format de $p_index ne supporte donc que des nombres
et les caractères ',' et '-'. (En particulier les espaces
et les ';' ne sont pas supportés).
De plus si
l'index correspond à un dossier, seul le dossier sera créé.
Les fichiers archivés et appartenant à ce dossier
ne seront pas archivés.
PclTarDelete($p_tarname,
$p_filelist, $p_mode) :
Supprime de
l'archive les fichiers/dossiers indiqués dans $p_filelist.
$p_filelist
peut être une liste de chaines de caractères contenant
les nom des fichiers/dossiers ou une simple chaine de caractères
contenant une liste de noms séparés par un seul
espace.
Suivant l'extension
de l'archive (.tar, .tar.gz ou .tgz) la fonction va déterminer
le type d'archive et agir en conséquence. Si vous souhaitez utiliser
une autre extension, le type d'archive souhaité doit être précisé
dans $p_mode ('tar' ou 'tgz').
Lorsque vous
indiquez un dossier à supprimer, le dossier et tous les
fichiers et sous-dossiers archivés se trouvant dans ce
dossier sont supprimés (depuis la version 1.3).
PclTarUpdate($p_tarname,
$p_filelist, $p_mode, $p_add_dir, $p_remove_dir) :
Les fichiers/dossiers
indiqués dans $p_filelist sont mis à jour dans l'archive
$p_tarname si leur date de dernière modification est meilleure
que celle du fichier déjà dans l'archive. Si le
fichier n'existe pas dans l'archive, il est ajouté à
la fin.
$p_filelist
peut être une liste de chaines de caractères contenant
les nom des fichiers/dossiers ou une simple chaine de caractères
contenant une liste de noms séparés par un seul
espace.
Suivant l'extension
de l'archive (.tar, .tar.gz ou .tgz) la fonction va déterminer
le type d'archive et agir en conséquence. Si vous souhaitez utiliser
une autre extension, le type d'archive souhaité doit être précisé
dans $p_mode ('tar' ou 'tgz').
PclTarMerge($p_tarname,
$p_tarname_add, $p_mode, $p_mode_add) :
Le contenu
de l'archive $p_tarname_add est ajouté à la fin
de l'archive $p_tarname. $p_tarname_add n'est pas modifié.
Le type des archives (compressées, non compressées)
peut être différent. Chaque archive conservant ses
propriétés.
Suivant l'extension
de l'archive (.tar, .tar.gz ou .tgz) la fonction va déterminer
le type d'archive et agir en conséquence. Si vous souhaitez utiliser
une autre extension, le type d'archive souhaité doit être précisé
dans $p_mode et $p_mode_add ('tar' ou 'tgz').
