PhpConcept
 
 

PhpZip Library 1.1 - Manuel

PhpZip Library permet de créer des archives multi-fichiers en PHP.

PhpZip Library est le moteur utilisé par l'application PhpZip. Elle peut cependant être utilisée seule.

La description générale des fonctionnalités est diponible ici.

Vous pouvez accéder directement au manuel de l'application PhpZip.

 
 
Manuel PhpZip Library 1.1
 
 

 

Sommaire

Introduction

La PhpZip Library permet de générer des archives de plusieurs fichiers, et d'extraire des fichiers archivés.

La recommandation générale est de ne pas dépasser 1000 fichiers / 2,5 Mo en mode non compressé et 200 fichiers / 4 Mo en mode automatique (voir section Performances).

Plusieurs modes d'archivage sont possibles :

  • PhpZip compressé : chaque fichier est compressé en utilisant les fonctions classiques gzip.
  • PhpZip normal : les fichiers sont sérialisés à la suite sans compression.
  • PhpZip automatique : les fichiers sont compressés, sauf ceux ayant une extension particulière (configurable) qui ne le sont pas. Cela est en particulier utile pour les fichiers .gif et .jpg dont la compression n'apporte pas de gros avantages.

Plusieurs types d'archives sont possibles :

  • Archives PhpZip normales : elles devront être extraites à l'aide de PhpZip,
  • Archives PhpZip autounzip : elles incluent un code PHP qui permet leur auto-extraction.

Chacun de ces deux types supporte une fonction d'auto-start, qui permet de lancer automatiquement une page PHP après l'extration de l'archive.
Ce mode prend pleinement son sens dans le cas de l'archive auto-extractible.

Fonctions de la librairie

La librairie est composée de deux fichiers : phpzip.lib.php3 et du code d'auto-unzip (phpunzip.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.
Les descriptions des fonctions sont détaillées dans leur entête à l'intérieur même des fichiers, voici donc un extract :

PhpzipCreate($p_filename, $p_files, $p_startfile, $p_type) :

Cette fonction crée une archive PhpZip ayant le nom $p_filename.
Si une liste de fichiers à compresser est spécifiée dans $p_files, ceux-ci sont ajoutés dans l'archive en mode de compression automatique. La liste est de même type que pour la fonction PhpZipAddList().
Le type d'archive PhpZip est fixé par la valeur $p_type ("phpzip" ou "phpautounzip"). Par défaut c'est une archive normale sans mode d'auto-extraction ("phpzip").
Un fichier d'auto-start peut être associé à l'archive par le paramètre $p_startfile.
Cela doit être un chemin vers n'importe quel fichier valide relativement au dossier de l'archive.

IsPhpzipArchive($p_filename) :

Cette fonction permet de déterminer si le nom $p_filename est une archive PhpZip valide et lisible.
Elle vérifie d'abord que le nom existe, qu'il correspond à un fichier accessible en lecture. Ensuite elle ouvre le fichier et vérifie qu'il s'agit bien d'une archive PhpZip (voir paragraphe sur la structure des archives).
La fonction retourne TRUE ou FALSE.

PhpzipAddList($p_phpzip_file, $p_list, $p_mode) :

Cette fonction ajoute une liste de fichiers ou de dossiers ($p_list) à l'archive PhpZip identifiée par son nom (paramètre $p_phpzip_file). Elle regarde pour chaque nom s'il s'agit d'un fichier ou d'un dossier. Si c'est un dossier, tout les fichiers et sous-dossiers sont ajoutés.
Une méthode de compression spécifique peut être demandée par le paramètre $p_mode :

  • "C" impose que tous les fichiers soient compressés,
  • "N" impose qu'aucun fichier ne doit être compressé,
  • "A" indique que PhpZip va déterminer le type de compression "C"/"N" en fonction de l'extension des fichiers. Certains types de fichiers ne nécessitent pas de compression (.gif,.jpg).

Il est à noter que dans tous les cas, les fichiers de moins de 20 octets ne sont pas compressés, car la compression minimale par gzip est d'au moins 20 octets.

PhpzipAdd($p_phpzip_file, $p_filename, $p_mode),
PhpzipAddDir($p_phpzip_file, $p_dir, $p_mode) :

Ces fonctions appellent maintenant PhpZipAddList(). PhpZipAdd() est donc plus simple d'utilisation pour l'ajout d'un seul fichier ou d'un seul dossier que le passage en paramètre d'une liste. Par contre PhpZipAddDir() n'est présent que pour être compatible avec la version 1.0. Il est conseillé de ne plus l'utiliser.
Voir PhpzipAddList().

PhpzipUnzipStart($p_phpzip_file, &$p_startfile, $p_path) :

Cette fonction extrait tous les fichiers de l'archive identifiée par son nom ($p_phpzip_file) dans le sous-dossier $p_path (relatif au dossier courant).
S'il existe dans l'archive un fichier d'auto-start, celui-ci est rendu dans le paramètre $p_startfile.
Il faut noter que les chemins relatifs des fichiers compressés sont conservés dans l'archive et sont reproduits lors de l'extraction. Si $p_path est indiqué, alors ces chemins y sont relatifs.
Si le sous-dossier d'un fichier n'existe pas, il est automatiquement créé, pour peu que l'on en ait les droits.
Si un fichier existe déjà, il est remplacé par le fichier extrait sans aucun avertissement.

PhpzipUnzip($p_phpzip_file, $p_path) :

Voir PhpzipUnzipStart().

PhpzipUnzipList($p_phpzip_file, $p_file_list, $p_path) :

Cette fonction extrait de l'archive PhpZip (identifiée par $p_phpzip_file) l'ensemble des fichiers ou dossiers se trouvant dans la liste $p_file_list. Si un dossier de destination est spécifié ($p_path), les fichiers sont extraits dans ce dossier. Il faut noter que le chemin associé à chaque fichier au moment de l'archivage est conservé.

PhpzipUnzipListString($p_phpzip_file, $p_string_list, $p_path) :

Cette fonction extrait de l'archive PhpZip (identifiée par $p_phpzip_file) l'ensemble des fichiers ou dossiers se trouvant dans la chaine $p_string_list. Les noms de dossier ou fichier à extraire doivent être séparés par le caractère ':'. Le fonctionnement est alors le même que PhpUnzipList()..

PhpzipList($p_phpzip_file, &$p_list, &$p_list_detail) :

Cette fonction lit l'archive et retourne les noms des fichiers archivés et leurs propriétés.
La première liste ($p_list) contient le nom des fichiers complets (dossier + nom de fichier), la seconde ($p_list_detail) contient le nom des fichiers et les propriétés sous le format suivant :
filename:size:compressedsize:directory:type
"
filename" est le nom du fichier sans son dossier,
"size" la taille du fichier non compressé,
"compressedsize" la taille une fois compressé,
"dossier" le sous-dossier relatif,
"type" le type de compression utilisé ('C' pour compression /'N' pour Normal ou pas de compression).

Structure des archives

Il existe deux formats d'archive PhpZip : phpzip et phpautounzip. phpzip est finalement un sous ensemble de phpautounzip.

Une archive commence impérativement par le préambule suivant :
#PhpZip:1.0:phpzip:start=start.php3:

  • #PhpZip est le tag d'identification du type de fichier : archive PhpZip.
  • 1.0 identifie la version de la librairie PhpZip qui a généré cette archive.
    Il est à noter que seul le premier digit "1" identifie le format de l'archive.
    Cela veut dire que des archives "1.1", "1.2", "1.x" etc pourront toujours être lues par la librairie PhpZip 1.0. S'il y a changement de format de l'archive, la version de la librairie passera alors à "2.x" puis "3.x" etc ... Cette méthode permettra (peut-être ;-)) de mettre à jour les fonctions de la librairie avec moins d'impact sur le format des archives anciennes.
  • phpzip indique le type de l'archive PhpZip ("phpautounzip").
  • start=start.php3 indique une propriété de l'archive, ici le fichier d'auto-start fixé à "start.php3". La porte est ouverte pour d'autres propriétés (prop=value), un jour peut-être ;-).

Une archive autounzip est constituée de deux morceaux, le premier est du code PHP semblable aux fonctions PhpzipUnzipStart() mais optimisé au maximum en nombre d'octets, le second est le contenu de l'archive.

La structure est alors :

#PhpZip:1.0:phpautounzip
[... code PHP ...]
#PhpZip:1.0:phpzip:start=start.php3:
[... contenu de l'archive ...]

Les fichiers archivés sont placés les uns après les autres de la façon suivante :

#PhpZip:1.0:phpzip:
data/fichier3.txt:107:72:C:
[... fichier compressé ...]
data/fichier1.txt:18:18:N:
[... fichier non compressé ...]

  • #PhpZip:1.0:phpzip: le préambule,
  • data/fichier3.txt le nom du premier fichier. Ici fichier3.txt se trouvant dans le dossier ./data.
  • 107 Taille du fichier non compressé.
  • 72 Taille du fichier compressé (gzip).
  • C Type d'archivage "C" pour Compressé, "N" pour Normal ou non compressé.
Langage PHP supporté

La PhpZip Library a été développée en PHP 3.0.17. Elle a été testée sans soucis sur Free et Online.
En cas de soucis avec la zlib (function gzip), vous pouvez toujours l'utiliser en mode Normal, sans compression.

Performances

La quantité de fichiers compressés et leur taille dépend principalement du temps d'exécution maximum autorisé au process PHP. Quelques tests ont été réalisés sur la version 1.0 pour avoir une idée de ce qui est possible :

Plateforme
PHP maximum
execution time
Nombre de Fichiers
Taille totale
Type de compression
Taille
Archive
Status
 
PC local
60 sec.
989
2,9 Mo
Compressé
1,23 Mo
OK
*
PC local
60 sec.
989
2,9 Mo
Automatique
1,25 Mo
OK
 
PC local
60 sec.
1978
5,8 Mo
Compressé
-
NOK
 
PC local
60 sec.
1978
5,8 Mo
Automatique
2,51 Mo
OK
 
PC local
60 sec.
2967
8,7 Mo
Automatique
-
NOK
 
PC local
60 sec.
2967
8,7 Mo
Non Compressé
8,84 Mo
NOK
**
PC local
60 sec.
217
4,76 Mo
Automatique
1,2 Mo
OK
 
www.free.fr
5 sec.
217
4,76 Mo
Automatique
1,2 Mo
OK
 
www.free.fr
5 sec.
989
2,9 Mo
Automatique
-
NOK
**
www.free.fr
5 sec.
989
2,9 Mo
Non Compressé
2,94 Mo
OK
 
www.free.fr
5 sec.
72
1,58 Mo
Automatique
410 Ko
OK
 

(*) Cela correspond environ à un PHPNuke 4.2
(**) Compression OK, mais décompression NOK (execution time excess)

Le mode de compression "Normal" (Sans compression gzip) est le plus sûr en ce qui concerne le temps de compression/décompression. Les modes "Compression" ou "Auto" sont les plus performants en ce qui concerne le taux de compression.
D'une manière générale, on se méfiera surtout des très nombreux fichiers et des très grosses archives.

Méthode de publication des archives

Il faut télécharger (upload) une archive PhpZip en mode (FTP) binaire afin de ne pas avoir de surprises lors de l'extraction. Pour le cas des archives non compressées, cette restriction ne s'applique (à priori) pas.

ATTENTION : pour que quelqu'un puisse télécharger depuis votre site une archive auto-extractible, celle-ci ne peut pas avoir directement l'extension .php3 (ou .php) sinon l'extraction est lancée sur votre site (!).
Le plus simple est de nommer le fichier avec l'extension .piz.auto (par exemple), l'utilisateur devra alors le télécharger sur son site, le renommer en .piz.php(3) et le tour est joué.

Le plus performant est cependant d'utiliser un petit script 'download.php'. Vous mettez l'archive 'archive.piz.php3' sur votre site dans un dossier $dir :

<?
// ----- Renvoyer le fichier source
$dir = "download_dir";
$fp = fopen($dir.$file, "r");
header("Content-disposition: filename=".$file);
header("Content-type: application/octetstream");
header("Pragma: no-cache");
header("Expires: 0");
fpassthru($fp);
?>

Faites alors un lien vers 'download.php?file=archive.piz.php3' pour le téléchargement.

 

Conventions

Afin de s'y retrouver, on prendra comme convention d'appeler les archives PhpZip avec les extensions suivantes :

.piz pour les archives PhpZip classiques,
.piz.php3 (ou .piz.php) pour les archives auto-extractibles une fois installées.

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

La PhpZip Library 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 PhpZip. Elle sera bientôt disponible de façon indépendante sur PhpConcept.

Historique de la documentation

Vous pouvez retrouver l'historique des documentations pour les version précédentes aux liens suivants :

 

 
 
 

Member login - Stats
Copyright 2003 - PhpConcept

Powered by PcWeb