1 // --------------------------------------------------------------------------------
2 // PclTar 1.3.1 - readme.txt
3 // --------------------------------------------------------------------------------
4 // License GNU/GPL - Vincent Blavet - January 2003
5 // http://www.phpconcept.net
6 // --------------------------------------------------------------------------------
8 (Voir version Française à la fin)
26 PclTar is a library that allow you to create a GNU TAR archive,
27 to add files or directories, to extract all the archive or a part of it.
28 So far tests show that the files generated by PclTar are readable by
29 gzip tools and WinZip application.
31 PclTar is made of the following files, placed in the same 'lib' directory :
36 Today the libraries PclTrace and PclError are mandatory to run PclTar.
38 The extension of the files can be modified to .php (or other) without any
39 internal modification.
41 The files can be put into any directory as far as the calling script/application
42 has a valid path to it (see section using PclTar).
48 PclTar 1.3 is released in three format :
50 - Zip traditionnal format (pcltar-1-3.zip),
51 - Compressed GNU TAR format (pcltar-1-3.tgz),
52 - PhpZip auto-extract PhpZip (pcltar-1-3.piz).
54 The Zip and compressed GNU TAR file also include the auto-extract PhpZip file, which
55 might be usefull for a remote auto-install.
58 Unzip the Zip file in a folder.
59 The files are in the 'lib' directory, but may be moved in any other directory.
61 b. Compressed GNU TAR archive
62 Extract the Compressed GNU TAR file in a folder.
63 The files are in the 'lib' directory, but may be moved in any other directory.
65 c. Auto-extract PhpZip archive
66 Download *** IN BINARY MODE *** the auto-extract PhpZip archive on your web site
67 in the destination directory 'myfolder'.
68 Launch the extract by calling http://mydomain.com/myfolder/pcltar-1-3.piz.php3.
69 The files are automatically placed in the 'lib' directory of the 'myfolder'
77 - Remove deprecated call to functions with references
81 - Add the function PclTarExtractIndex()
82 - Correction of a bug with folders. When folder are archived, the size is sometime not
83 null. PclTar now force the size to be zero when the archived file is a folder. When
84 un-archiving the size is also forced to 0 when the item is a folder.
85 - Modify function PclTarDelete() : When you give the name of a directory to be deleted, the
86 directory entry and the files of the directory are deleted.
87 - Correct bug in the path add/remove options in functions. When a path is removed,
88 sometime the 'home' path was not.
89 - Correct a bug in directory extraction : The directory is created but the status in
90 the resulting file list is set to write_error.
91 - Correct a bug : missing update of file cache (clearstatcache())
95 - Add a new function PclTarMerge(), which allow to merge two archives.
96 - Add the add_path/remove_path ability to the PclTarCreate() function
97 - The add list/dir function now support empty directory. Before version 1.2, directories
98 where not identified as separate entries, there where in the archive, only if there is at
100 - Optimization of PclTarHandleAddList()
104 - Adding check of header checksum while extracting a file from the archive,
105 - Enhancement in POSIX header creation. In the first version PclTar use a temporary
106 file for checksum calculation. It is now directly computed.
107 - Adding field "status" in file description, remove fields "link", "magic", "version",
108 "uname", "gname", "devmajor" and "devminor", because they do not carry interesting info.
109 - While extracting, a check is done if the file exists or not. If an error occurs in the
110 file extraction, the file is skipped, and the function tries to extract the next one.
111 In previous release, the extraction was stopped.
112 - While extracting a file, the mtime is now updated with the value stored in the archive.
113 Note that the mode (R/W) is not set today (default RW).
115 - New function PclTarDelete($tarname, $filelist), which deletes the files specified in
117 - New function PclTarUpdate(), which replace old files with new ones (depending of last
118 modification date). If the file does not exist, it is added at the end of the archive.
119 - Values for the file properties array :
120 filename (with path),
122 mode (decimal value of the octal value),
125 mtime (last modification date like time() function result),
126 typeflag ("0" or "" = file, "5" = directory, "1" = link),
127 status (ok, added, updated, not_updated, already_a_directory,
128 write_protected, newer_exist, path_creation_fail, write_error)
129 - Add a "remove path" property in the extract functions. This allow to extract file
130 in an other directory than the expected directory.
131 - Add new function PclTarAddList()
132 - Add parameter $p_mode in PclTarList()
135 ========================
137 In order to use PclTar 1.3, an application (or a script) must include
138 the PclTar file pcltar.lib.php3.
139 Because PclTar 1.3 include two other libraries (PclTrace and PclError), a
140 way to include these libraries must be done. Several solutions are available :
142 - Include each library in the application/script (in this order) :
144 include ("my_lib_dir/pclerror.lib.php3");
145 include ("my_lib_dir/pcltrace.lib.php3");
146 include ("my_lib_dir/pcltar.lib.php3");
150 - Give the library path knownledge to PclTar :
152 $g_pcltar_lib_dir = "my_lib_dir";
153 include ("my_lib_dir/pcltar.lib.php3");
157 - Modify the $g_pcltar_lib_dir value in pcltar.lib.php3
159 - Use the global include directory configured in php.ini, and modify the
160 $g_pcltar_lib_dir value in pcltar.lib.php3 and set it to ''
162 Note that PclTar file (pcltar.lib.php3) may be included several time without any
163 problem. However this is not recomended for performance reason.
165 After the include(s), the functions defined by PclTar can be directly used
166 (see manual section).
172 PclTar introduce functions to create, add, list, delete and extract files in a GNU
173 TAR archive. The GNU TAR archive can be compressed or not.
175 A more complete documentation of the PclTar function is available at
176 http://www.phpconcept.net
178 Each public function is documented in an appropriate header directly in the source
186 PclTar was developped in PHP3 but is compatible with PHP4. The files
187 extension can be modified without any action needed inside the files.
189 PclTar code is fully documented (nearly step by step) in english.
195 Here is a list of known bugs in PclTar 1.0 (not exhaustive list) :
197 - Only GNU TAR archive with POSIX header are supported
198 - While extracting a file, the header checksum is not checked.
199 - While extracting a file, the last modified date is not checked with the one
200 of the file that will be replaced.
201 - While extracting a file, the file mode (access right by user, ...) is not
203 - While archiving a full directory, the directory it self is not archived.
204 - While extracting a directory name the directory is created only if there is
205 a file inside. Should be created even if no file is inside.
207 Known bugs will be updated in http://www.phpconcept.net
213 PclTar 1.3 Library is released under GNU/GPL license.
214 This library is free, so you can use it at no cost.
216 HOWEVER, if you release a script, an application, a library or any kind of
217 code including PclTar library (or a part of it), YOU MUST :
218 - Release your work under GNU/GPL license (free software),
219 - You must indicate in the documentation (or a readme file), that your work
220 include PclTar Library, and make a reference to the author and the web site
221 http://www.phpconcept.net
223 I will also appreciate that you send me a mail (vincent@blavet.net), just to
224 be aware that someone is using PclTar (but this is not mandatory ;-) ).
226 For more information : http://www.gnu.org
231 This library and the associated files are non commercial, non professional work.
232 It should not have unexpected results. However if any damage is caused by this software
233 the author can not be responsible.
234 The use of this software is at the risk of the user.
239 This software was written by Vincent Blavet (vincent@blavet.net) on its leasure time.
243 ********************************************************************************
244 * VERSION FRANCAISE *
245 ********************************************************************************
253 4 - Démarrer avec PclTar
265 PclTar est une librairie qui vous permet de créer des archives au format GNU TAR ou GNU
266 TAR compressé, d'ajouter des fichiers ou des dossiers entiers et d'extraire le contenu
267 total ou partiel des archives.
268 A présent les tests ont montré que les archives créées par PclTar sont lisibles par les
269 outils tar et gzip, ainsi que l'application WinZip.
271 PclTar est constituée des fichiers suivants, ils sont placés dans le dossier 'lib' :
276 Aujourd'hui les librairies PclTrace et PclError sont obligatoires pour faire fonctionner
279 Les extensions de fichiers (.php3) peuvent être modifiés (en .php par exemple) sans
280 nécessité d'intervenir à l'intérieur du fichier.
282 Les fichiers peuvent être placés dans n'importe quel dossier pour peu que l'application
283 ou le script appelant utilise un chemin d'appel valide.
289 PclTar 1.3 est distribué sous trois formats :
291 - Format Zip traditionnel (pcltar-1-3.zip),
292 - Format GNU TAR compressé (pcltar-1-3.tgz),
293 - Format PhpZip auto-extract (pcltar-1-3.piz).
295 Les fichiers Zip and GNU TAR compressés contiennent aussi le format PhpZip
299 Décompressez l'archive Zip dans un dossier.
300 Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
302 b. Archive GNU TAR compressée
303 Décompressez l'archive GNU TAR dans un dossier.
304 Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
306 c. Auto-extract PhpZip archive
307 Téléchargez *** EN MODE BINAIRE *** l'archive PhpZip sur votre site Web dans
308 le dossier souhaité 'mondossier'.
309 Lancer l'extraction en appelant http://mondomaine.com/mondossier/pcltar-1-3.piz.php3
310 Les fichiers sont dans le dossier 'lib' du dossier 'mondossier'.
318 - Suppression des appels de fonctions par références
322 - Ajout de la fonction PclTarExtractIndex()
323 - Correction d'un bug avec l'archivage des dossiers. Parfois la taille des
324 dossiers archivés était non nul ce qui entrainait une erreur lors de l'extraction.
325 PclTar force désormais la taille à zéro lorsqu'il s'agit d'un dossier. De même lors
326 de l'extraction il ignore la taille éventuellement incorrecte.
327 - Modification de la fonction PclTarDelete() : Lorsque l'on donne le nom d'un dossier
328 à supprimer, le dossier et les fichiers se trouvant dedans sont supprimés.
329 Avant la version 1.3 seulement l'entrée concernant le dossier était supprimée.
330 - Correction d'un bug dans les propriétés d'ajout/suppression de chemin. Lorsque l'on
331 indiquait un chemin à supprimer, cela se passait bien pour les fichiers et
332 sous-dossiers, mais le dossier en lui-même n'était pas ignoré.
333 - Correction d'un bug dans l'extraction d'un dossier : Le dossier est normalement créé,
334 mais le status de l'opération pour ce dossier était en 'write_erreor'.
335 - Correction d'un bug sur la validité des dates de dernière modification des
336 fichiers. Utilisation plus systèmatique de clearstatcache().
340 - Ajout d'une nouvelle fonction PclTarMerge(), qui permet d'ajouter à une archive le
342 - Ajout des propriétés "ajout de path/suppression de path" pour la fonction PclTarCreate().
343 - Les archives générées par PclTar supportent maintenant les dossiers vide. Avant la
344 version 1.2, un dossier n'était ajouté que lorsqu'il y avait au moins un fichier dedans.
345 - Optimisation du code de PclTarHandleAddList()
349 - Ajout de la vérification du checksum lors de l'extraction d'un fichier.
350 - Amélioration de la création des entêtes POSIX. En version 1.0 PclTar utilisait un fichier
351 temporaire pour calculer le checksum. Ce n'est plus le cas à partir de la version 1.2.
352 - Ajout d'un champ "status" dans le tableau de description des propriétés d'un fichier.
353 Les champs "link", "magic", "version", "uname", "gname", "devmajor" and "devminor" sont
354 eux supprimés car ils ne contiennent aucune information interessante.
355 - Lors de l'extraction une vérification est faite pour savoir si le fichier existe déjà ou non.
356 Si une erreur arrive lors de l'extraction le fichier est sauté et la fonction cherche à
357 extraire le fichier suivant. Dans la version précédente l'extraction était arrêtée.
358 - Lors de l'extraction d'un fichier la date de dernière modification est mise à jour avec
359 celle mémorisée dans l'archive.
360 Notez que ce n'est pas le cas pour le mode (R/W) qui reste celui par défaut.
361 - Nouvelle fonction PclTarDelete($tarname, $filelist), qui supprime de l'archive les fichiers
362 spécifiés dans $filelist.
363 - Nouvelle fonction PclTarUpdate(), qui remplace les anciens fichiers par les nouveaux
364 (en fonction de la date de dernière modification). Si le fichier n'existe pas il est
365 ajouté en fin d'archive.
366 - Le tableau contenant les propriétés d'un fichier a les champs suivants :
367 filename (with path),
369 mode (decimal value of the octal value),
372 mtime (last modification date like time() function result),
373 typeflag ("0" or "" = file, "5" = directory, "1" = link),
374 status (ok, added, updated, not_updated, already_a_directory,
375 write_protected, newer_exist, path_creation_fail, write_error)
376 - Ajout d'une propriété "chemin à retirer" dans les fonctions d'extraction. Cela permet
377 d'extraire un fichier ou un dossier dans un dossier différent de celui qui a été mémorizé.
378 - Ajout de la focntion PclTarAddList()
379 - Ajout du parametre $p_mode dans PclTarList()
381 3 - Démarrer avec PclTar
382 ========================
384 Pour utiliser PclTar, une application ou un script doivent inclure le fichier
386 PclTar utilisant deux librairies annexes (PclTrace et PclError), une configuration
387 est nécessaire pour que PclTar retrouve le chemin d'inclusion des deux librairies.
388 Plusieurs solutions, au choix, sont possibles :
390 - Inclure chaque librarie dans l'application/script :
392 include ("my_lib_dir/pclerror.lib.php3");
393 include ("my_lib_dir/pcltrace.lib.php3");
394 include ("my_lib_dir/pcltar.lib.php3");
398 - Donner à PclTar la connaissance du chemin d'inclusion :
400 $g_pcltar_lib_dir = "my_lib_dir";
401 include ("my_lib_dir/pcltar.lib.php3");
405 - Modifier la variable $g_pcltar_lib_dir dans pcltar.lib.php3
407 - Utiliser le chemin d'include par défaut (configuré dans php.ini), sans oublier de
408 modifier la variable $g_pcltar_lib_dir pour la mettre à ''.
410 Il est à noter que le fichier pcltar.lib.php3 peut être inclu plusieurs fois sans
411 impact autre qu'une légère perte de performance.
417 PclTar définit des fonctions pour créer, ajouter, lister, détruire et extraire des
418 fichiers depuis une archive GNU TAR. Cette archive peut être compressée ou non.
420 Une description plus complète de PclTar est disponible sur
421 http://www.phpconcept.net
423 Chaque fonction est aussi documentée dans un entête associé, directement dans
430 PclTar a été développé en PHP3 mais est compatible avec PHP4. Les
431 extensions de fichiers (.php3) peuvent être modifié sans toucher à l'intérieur
434 Le code de PclTar est entièrement documenté en anglais.
440 Liste des problèmes connus dans PclTar 1.0 (liste non exhaustive) :
442 - Seuls les archives GNU TAR au format "header POSIX" sont supportées
443 - Lors de l'extraction d'un fichier le checksupm de l'entête n'est pas vérifié
444 - Lors de l'extraction d'un fichier la date de dernière modification d'un
445 fichier n'est pas comparé avec celle du fichier existant.
446 - Lors de l'extraction d'un fichier les droits d'accès d'un fichier ne sont pas
448 - Lors de l'archivage d'un dossier entier, le nom du dossier lui même n'est pas
449 archivé comme une entrée indépendante
450 - Lors de l'extraction de l'entrée décrivant un dossier, le dossier n'est créé que si
451 au moins un fichier est archivé pour ce dossier.
453 Les bugs connus et les contournements possibles ou les versions de correction
454 seront mis à jour sur le site http://www.phpconcept.net
456 Merci d'y documenter les bugs que vous rencontrez afin qu'ils soient pris en compte
457 dans les versions futures !
462 La librairie PclTar 1.3 est distribuées sous license GNU/GPL.
463 Vous pouvez donc l'utiliser gratuitement.
465 CEPENDANT, si vous publiez un script, une application, une librairie ou tout
466 code incluant PclTar (entier ou partiel), VOUS DEVEZ :
467 - Publier votre travail sous license GNU/GPL (c'est à dire gratuitement),
468 - Indiquer quelque part dans la documentation (le fichier readme par exemple) que
469 vous utilisez PclTar, faire référence à l'auteur et au site Web
470 http://www.phpconcept.net
472 J'apprécierai aussi que vous m'envoyez un mail (vincent@blavet.net) afin que
473 je sache que PclTar est utilisé quelque part (mais ce n'est pas obligatoire ;-) ).
475 Pour plus d'information voir http://www.gnu.org
481 Cette application a été créée de façon non professionnelle.
482 Son usage est au risque et péril de celui qui l'utilise, en aucun cas l'auteur
483 de ce code ne pourra être tenu pour responsable des éventuels dégats qu'il pourrait
485 Il est entendu cependant que l'auteur a réalisé ce code par plaisir et n'y a
486 caché aucun virus ni malveillance.
492 Ce code a été écrit par Vincent Blavet (vincent@blavet.net) sur ses temps de loisir.