PhpConcept
 
 

PclTar 1.3 - PhpConcept Library Tar

La libriairie PclTar offre des fonctions d'archivage et d'extraction de fichiers au format GNU TAR.

 
 

Fonctionnalités - Manuel - Téléchargements - Nouveautés - Historique

 
 
Fonctionnalités
 
 

 

PclTar permet d'archiver une liste de fichiers ou de dossiers avec une option de compression ou non. Les archives obtenues par PclTar sont lisibles par la plupart des codes gzip/tar et par l'application sous Windows WinZip.

PclTar permet l'extraction des fichiers contenus dans une archive GNU TAR, compressée ou non. Seules les archives contenant exclusivement des headers POSIX sont interprétées (c'est le cas général).

L'application PhpZip utilise PclTar, n'hésitez pas à la regarder pour voir l'usage que l'on peut faire de PclTar.

PclTar 1.3 est la quatrième version de PclTar, il est cependant bien probable que des bugs restent encore. Vous pouvez les traquer vous même en utilisant la librairie PclTrace incluse dans PclTar. Dans tous les cas merci de nous avertir des bugs découverts ! (webmaster@phpconcept.net).

La version 1.3 de PclTar offre les fonctions suivantes :

1. La création d'une archive :

  • Création d'une archive au format GNU TAR ou GNU TAR compressée par GNU ZIP (gzip lib),
  • L'ajout optionnel d'une liste de fichiers ou de dossiers lors de la création de l'archive.
  • La possibilité de manipuler les chemins mémorisés dans l'archive pour chaque fichier/dossier. Cela permet d'extraire ensuite l'archive dans un dossier qui n'est pas celui d'origine des fichiers.

2. Ajout de fichiers ou dossiers :

  • Ajout d'une liste de fichiers ou d'une liste de dossiers dans une archive déjà existante,
  • Le chemin des fichiers/dossiers mémorisé peut être manipulé en ajoutant un chemin ou en supprimant une partie de celui d'origine. Cela permet d'extraire ensuite l'archive dans un dossier qui n'est pas celui d'origine des fichiers.

3. L'extraction :

  • Extraction de l'ensemble de l'archive,
  • Extraction partielle des fichiers ou dossiers de l'archive en spécifiant une liste de fichiers ou de dossiers,
  • Extraction partielle des fichiers ou dossiers de l'archive en spécifiant les index des fichiers ou dossiers à extraire,
  • L'extraction est effectuée dans le dossier courant ou un dossier qui peut être spécifié,
  • Les chemins relatifs des fichiers archivés sont conservés lors de l'extraction. Il est cependant aussi possible d'ignorer une partie du chemin mémorisé.

4. La liste du contenu :

  • Permet la récupération de la liste des fichiers contenus dans l'archive et leurs propriétés.

5. La suppression de fichiers/dossiers :

  • Permet de supprimer de l'archive une liste de fichiers/dossiers.

6. Mise à jours :

  • Mise à jour d'une liste de fichiers/dossiers présents dans l'archive :
  • Si le fichier existe dans l'archive et aété modifié plus recemment, il remplace alors le fichier mémorizé dans l'archive.
  • Si le fichier n'existait pas dans l'archive, il est ajouté à la fin de l'archive.

7. Concaténation d'archives :

  • Ajout du contenu d'une archive à la fin de celui d'une autre archive.
  • Chaque archive peut avoir des options de compression différents.
 
 
 
 

Fonctionnalités - Manuel - Téléchargements - Nouveautés - Historique

 
 
Manuel Utilisateur
 
 

 

Sommaire

Fonctions de la librairie

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

Structure des archives

La structure des archives est celle des archive GNU TAR. Cependant seul les header POSIX sont supportés. En particulier les extra_header, les sparse_header et les oldgnu_header ne sont pas supportés. Les deux premiers sont normalement utilisés lors de l'archivage de fichiers de type base de données qui sont potentiellement plein de vide. Cela permettait de limiter la taille.
L'utilisation d'archive GNU TAR en association avec la compression GZIP permet de resoudre ce problème de façon plus simple.

La structure des archives est la suivante :

  • Chaque archive GNU TAR est un ensemble de blocs de 512 octets,
  • Un fichier est représenté par :
    • Un entête POSIX de 512 octets décrivant le fichier et comprenant un code de contrôle d'erreur (checksum),
    • Un ensemble de blocs de 512 octets archivant le contenu du fichier non compressé. Le dernier bloc est eventuellement complété avec des 0 pour faire 512 octets.
  • Et l'on passe au fichier suivant et ainsi de suite.

La structure officielle des archives, avec les valeurs des différents paramètres peuvent être trouvés sur le site du GNU : GNU TAR Standard Format.

Langage PHP supporté

PclTar a été développée en PHP 3.0.17.
En cas de soucis avec la zlib (function gzip), vous pouvez toujours l'utiliser en mode GNU TAR, sans compression.

Performances

Aucun test de performance n'a encore été réalisé pour avoir une idée plus précise de ce que l'on peut archiver/extraire en fonction des temps d'execution maximum alloués au process PHP et en local ou chez un hébergeur (Free pour ne pas le nommer).

Il s'agit cependant d'être prudent et eventuellement de morceller les actions d'ajout et d'extraction.

Conventions

Afin de s'y retrouver, on gardera les conventions communes :

.tar pour les archives GNU TAR classiques,
.tar.gz, .tgz pour les archives GNU TAR compressées par gzip.

Ces considérations ne sont qu'informatives.

Langues supportées

Le code est documenté en anglais, la description générale est en français dans un premier temps, mais devrait arriver en anglais.

Méthode de trace

PclTar utilise une librairie de trace développée par PhpConcept. Celle-ci permet de mettre des points de trace dans le code avec différents niveaux de profondeur. En particulier tous les appels fonctions et leur code retour sont tracés.

La PhpTrace Library 1.0 n'est disponible qu'avec PclTar. Elle sera bientôt disponible de façon indépendante sur PhpConcept.

 
 
 
 

Fonctionnalités - Manuel - Téléchargements - Nouveautés - Historique

 
 
Nouveautés
 
 

 

Version 1.3 :

  • Ajout de la fonction PclTarExtractIndex()
  • Correction d'un bug avec l'archivage des dossiers. Parfois la taille des dossiers archivés était non nul ce qui entrainait une erreur lors de l'extraction.
    PclTar force désormais la taille à zéro lorsqu'il s'agit d'un dossier. De même lors de l'extraction il ignore la taille éventuellement incorrecte.
  • Modification de la fonction PclTarDelete() : Lorsque l'on donne le nom d'un dossier à supprimer, le dossier et les fichiers se trouvant dedans sont supprimés.
    Avant la version 1.3 seulement l'entrée concernant le dossier était supprimée.
  • Correction d'un bug dans les propriétés d'ajout/suppression de chemin. Lorsque l'on indiquait un chemin à supprimer, cela se passait bien pour les fichiers et sous-dossiers, mais le dossier en lui-même n'était pas ignoré.
  • Correction d'un bug dans l'extraction d'un dossier : Le dossier est normalement créé, mais le status de l'opération pour ce dossier était en 'write_erreor'.
  • Correction d'un bug sur la validité des dates de dernière modification des fichiers. Utilisation plus systèmatique de clearstatcache().

Version 1.2 :

  • Ajout d'une nouvelle fonction PclTarMerge(), qui permet d'ajouter à une archive le contenu d'une autre.
  • Ajout des propriétés "ajout de path/suppression de path" pour la fonction PclTarCreate().
  • Les archives générées par PclTar supportent maintenant les dossiers vide. Avant la version 1.2, un dossier n'était ajouté que lorsqu'il y avait au moins un fichier dedans.
  • Optimisation du code de PclTarHandleAddList()

Version 1.1 :

  • Ajout de la vérification du checksum lors de l'extraction d'un fichier.
  • Amélioration de la création des entêtes POSIX. En version 1.0 PclTar utilisait un fichier temporaire pour calculer le checksum. Ce n'est plus le cas à partir de la version 1.2.
  • Ajout d'un champ "status" dans le tableau de description des propriétés d'un fichier.
    Les champs "link", "magic", "version", "uname", "gname", "devmajor" and "devminor" sont eux supprimés car ils ne contiennent aucune information interessante.
  • Lors de l'extraction une vérification est faite pour savoir si le fichier existe déjà ou non.
    Si une erreur arrive lors de l'extraction le fichier est sauté et la fonction cherche à extraire le fichier suivant. Dans la version précédente l'extraction était arrêtée.
  • Lors de l'extraction d'un fichier la date de dernière modification est mise à jour avec celle mémorisée dans l'archive.
    Notez que ce n'est pas le cas pour le mode (R/W) qui reste celui par défaut.
  • Nouvelle fonction PclTarDelete($tarname, $filelist), qui supprime de l'archive les fichiers spécifiés dans $filelist.
  • Nouvelle fonction PclTarUpdate(), qui remplace les anciens fichiers par les nouveaux (en fonction de la date de dernière modification). Si le fichier n'existe pas il est ajouté en fin d'archive.
  • Le tableau contenant les propriétés d'un fichier a les champs suivants :
    • 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)
  • Ajout d'une propriété "chemin à retirer" dans les fonctions d'extraction. Cela permet d'extraire un fichier ou un dossier dans un dossier différent de celui qui a été mémorizé.
  • Ajout de la fonction PclTarAddList()
  • Ajout du parametre $p_mode dans PclTarList()

 

 
 
 
 

Fonctionnalités - Manuel - Téléchargements - Nouveautés - Historique

 
 
Historique
 
 

 

Version 1.3 :

Ajout d'une fonction, améliorations et correction de bugs. Janvier 2002.

Version 1.2 :

Ajout d'une fonction et d'amélioration. Diffusion officielle de la version 1.1. Août 2001.

Version 1.1 :

Cette version n'a jamais été distribuée seule. Elle a été distribuée en même temps que PhpZip 1.6. Tout cela parceque je n'ai pas eu le temps de mettre à jour la documentation.

Version 1.0 :

Première version de PclTar. Mars 2001.

 

 
 
 
 

Fonctionnalités - Manuel - Téléchargements - Nouveautés - Historique

 

Member login - Stats
Copyright 2003 - PhpConcept

Powered by PcWeb