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 où
"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).
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.