Les nouveautés de PHP 5.3

Et comment migrer de PHP 5.2 vers PHP 5.3


précédentsommairesuivant

IV. Création et utilisation d'archives Phar

Cette section est une traduction de : http://www.ibm.com/developerworks/opensource/library/os-php-5.3new4/

IV-A. Introduction

Dans cette quatrième partie, voyons de près Phar, un format d'archive qui peut être utilisé dans PHP. Il peut être utilisé non seulement pour archiver des fichiers, mais aussi pour envoyer et pour exécuter une application complète depuis un seul fichier. Il peut être utilisé avec PHP au moyen d'une extension du répertoire PECL, mais ce sera une extension officielle de PHP à partir de la version 5.3.

Le concept des archives Phar provient de la technologie d'archives JAR de Java™, qui permet d'empaqueter une application dans un fichier unique contenant tout le nécessaire pour l'exécuter. C'est différent du concept des exécutables uniques habituellement produits par les langages comme le C, dans la mesure où le fichier est en réalité une archive et non une application compilée. Ainsi, l'archive JAR contient en réalité les fichiers constituant l'application, qui peuvent être rendus impénétrables pour des raisons de sécurité. L'extension Phar est fondée sur un concept similaire mais elle est conçue davantage pour l'environnement Web de PHP. De plus, à l'inverse des archives JAR, les archives Phar peuvent être utilisées par PHP lui-même et elles ne nécessitent pas d'outil externe pour les créer ou pour les lire.

L'extension Phar n'est pas totalement nouvelle pour PHP. Elle était initialement écrite en PHP sous le nom de PHP_Archive, et fut ajoutée au répertoire PEAR en 2005. Toutefois, une solution à ce problème, écrite en PHP, est trop lente dans le monde réel, c'est pourquoi PHP_Archive fut réécrite en extension C en 2007. Dans le même temps, le support d'ArrayAccess de la SPL fut ajouté pour parcourir une archive Phar. Depuis lors, des efforts considérables ont été produits pour améliorer les performances des archives Phar.

IV-B. Créer une archive Phar

Pour créer un fichier Phar, il faut suivre certaines étapes. Toutes nécessitent des commandes PHP sous une forme ou sous une autre, puisqu'il n'existe aucun outil autonome pour créer ces archives. De plus, afin de créer et de modifier des fichiers Phar, le paramètre phar.readonly de php.ini doit être mis à la valeur zéro. Ce paramètre n'est pas requis pour ouvrir ou pour référencer des fichiers d'une archive Phar dans PHP.

Voyons les étapes nécessaires pour créer une archive Phar qui puisse être utilisée pour lancer une application. Cette application sera conçue pour être chargée directement depuis le serveur Web ou la ligne de commande. La première étape est de créer le fichier Phar, ce que nous allons faire en créant l'objet Phar avec lequel nous allons travailler pour cet exemple dans Listing 1. La référence à l'objet vous permettra de contrôler tous les aspects de l'archive Phar.

Listing 1. Création de l'objet Phar
Sélectionnez
$p = new Phar(
	'/chemin/vers/mon.phar', 
	Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME, 
	'mon.phar');

$p->startBuffering();

Le premier paramètre du constructeur est le chemin vers l'emplacement de sauvegarde du fichier Phar. Le second paramètre transmet tous les paramètres à la classe parent RecursiveDirectoryIterator. Le troisième paramètre est un alias pour la manière dont ce fichier Phar est référencé dans le contexte des flux. Ainsi, pour le Listing 1, vous pouvez appeler un fichier de ce Phar grâce à phar://mon.phar. Vous pouvez également appeler la méthode Phar::startBuffering() pour mettre en tampon les modifications faites à l'archive jusqu'à ce que vous appeliez la commande Phar::stopBuffering(). Bien qu'il ne soit pas nécessaire de le faire, cela améliore les performances de création et de modification de l'archive puisque cela évite de modifier le fichier chaque fois que votre script le modifie.

Par défaut, le Phar créé utilisera le format de fichier fondé sur Phar. Vous pouvez également utiliser un format ZIP ou TAR pour le fichier Phar en le convertissant dans ce format, comme indiqué en Listing 2.

Listing 2. Changer le format d'enregistrement à ZIP
Sélectionnez
$p = $p->convertToExecutable(Phar::ZIP);

Il y a des avantages et des inconvénients à modifier le format de l'archive. L'avantage principal est la capacité d'inspecter le contenu de l'archive avec n'importe quel outil pour traiter des fichiers ZIP ou TAR. Cependant, utiliser une archive Phar qui n'utilise pas le format d'archive natif basé sur Phar ne nécessite pas l'utilisation de l'extension Phar pour charger l'archive, contrairement aux archives formatées en ZIP ou en TAR.

Ensuite, vous avez besoin de définir le fichier bouchon, qui est le premier code appelé lorsque le fichier Phar est chargé.

IV-C. Le fichier bouchon de Phar

Le fichier bouchon est simplement un segment de code très court qui est exécuté au départ lorsque le fichier Phar est lancé, et il se termine par la commande __HALT_COMPILER(). Le Listing 3 est un fichier bouchon typique.

Listing 3. Fichier bouchon pour Phar
Sélectionnez
<?php
Phar::mapPhar();
include 'phar://monphar.phar/index.php';
__HALT_COMPILER();

L'appel de la méthode Phar::mapPhar() montré ci-dessus initialise l'archive Phar en lisant le manifeste. Vous devez le faire avant de référencer des fichiers à l'intérieur de l'archive au moyen du gestionnaire de flux phar://. Le fichier à charger initialement est ce que votre application chargerait en premier dans une situation normale ; dans cet exemple : index.php.

La manière d'ajouter ce fichier bouchon dépend du format d'archive utilisé. Pour des archives basées sur le format Phar, utilisez la méthode Phar::setStub() qui admet un seul paramètre : le code PHP à mettre dans le bouchon, en tant que chaîne. Le Listing 4 illustre cette approche.

Listing 4. Utiliser Phar::setStub() pour créer le fichier bouchon
Sélectionnez
$p->setStub("<?php Phar::mapPhar(); 
include 'phar://monphar.phar/index.php'; __HALT_COMPILER(); ?>"); 

Si vous n'avez pas prévu de faire davantage de choses avec le bouchon que de rediriger vers une page index.php, vous pouvez utiliser la méthode raccourci Phar::createDefaultStub() afin de créer le bouchon à votre place. Pour cela, vous aurez simplement besoin de transmettre le nom du fichier que vous désirez inclure dans le fichier bouchon. Dans le Listing 5, nous réécrivons l'appel à la méthode Phar::setStub() pour utiliser cette méthode raccourci.

Listing 5. Utiliser Phar::createDefaultStub() pour créer le fichier bouchon
Sélectionnez
$p->setStub($p->createDefaultStub('index.php')); 

Un second argument facultatif de la méthode Phar::createDefaultStub() permet d'inclure un fichier différent si le Phar est chargé depuis un serveur Web. C'est pratique dans le cas où votre application est conçue pour être utilisée en lignes de commandes et dans un contexte de navigateur Web.

Pour les implémentations basées sur ZIP et TAR, vous enregistrez le contenu du bouchon ci-dessus dans le fichier .phar/stub.php, plutôt que d'utiliser la commande setStub().

IV-D. Ajouter des fichiers à l'archive

L'objet Phar utilise l'interface ArrayAccess de la SPL pour permettre l'accès au contenu de l'archive comme un tableau, ce qui donne l'opportunité d'utiliser de nombreuses manières d'ajouter des fichiers à l'archive. La manière la plus simple est d'utiliser directement l'interface ArrayAccess.

Listing 6. Ajouter des fichiers à l'archive
Sélectionnez
$p['fichier.txt'] = 'Ceci est un fichier texte';
$p['index.php'] = file_get_contents('index.php'); 

Le Listing 6 montre que le nom de fichier est précisé comme clef, et le contenu comme valeur. Vous pouvez utiliser la fonction file_get_contents() pour donner comme valeur le contenu d'un fichier existant. Cela laisse un peu de flexibilité sur la manière d'ajouter un fichier à l'archive, soit en référençant un fichier existant soit en construisant un fichier à la volée. Cette dernière approche est utile en tant qu'élément d'un script de compilation d'une application.

Si le fichier que vous enregistrez dans l'archive Phar est gros, vous pouvez comprimer le fichier dans l'archive en utilisant une compression gzip ou bzip2, respectivement au moyen des méthodes PharFileInfo::setCompressedGZ() et PharFileInfo::setCompressedBZIP2(). Dans le Listing 7, nous allons comprimer une archive en utilisant bzip2.

Listing 7. Comprimer une archive en utilisant bzip2
Sélectionnez
$p['gros.txt'] = 'Ceci est un gros fichier texte';
$p['gros.txt']->setCompressedBZIP2(); 

Pour comprimer un fichier ou pour utiliser une archive contenant un fichier comprimé, l'extension bzip2 ou zlib (pour les archives comprimées en gz) doit être activée dans l'installation PHP.

Admettons que vous souhaitiez ajouter de nombreux fichiers à l'archive. Les ajouter un à un en utilisant l'interface ArrayAccess peut devenir fastidieux, ainsi il y a plusieurs raccourcis pour le faire. Un moyen est d'utiliser la méthode Phar::buildFromDirectory(), qui traverse un répertoire défini et qui ajoute les fichiers qui s'y trouvent. Elle permet également de filtrer les fichiers à ajouter en transmettant un second paramètre avec le modèle d'expression régulière validant les fichiers à ajouter à l'archive. Le Listing 8 montre comment utiliser cela.

Listing 8. Ajouter des fichiers à une archive en utilisant Phar::buildFromDirectory()
Sélectionnez
$p->buildFromDirectory('/chemin/vers/les/fichiers', './\.php$/');

Le Listing 8 ajoute à l'archive Phar tous les fichiers PHP du répertoire indiqué. Vous pouvez alors revenir à l'utilisation de l'interface ArrayAccess si vous souhaitez apporter des modifications aux fichiers ajoutés, tel que les marquer pour une compression.

Vous pouvez également utiliser la méthode Phar::buildFromIterator() pour ajouter des fichiers en utilisant un itérateur. Deux types d'itérateurs sont supportés : ceux qui lient le nom de fichier au sein du Phar au nom de fichier sur le disque, et ceux qui renvoient des objets SplFileInfo. Un opérateur compatible est RecursiveDirectoryIterator, utilisé ci-dessous pour ajouter à l'archive les fichiers d'un répertoire.

Listing 9. Ajouter des fichiers à une archives au moyen de Phar::buildFromIterator()
Sélectionnez
$p->buildFromIterator(new RecursiveIteratorIterator
(new RecursiveDirectoryIterator('/chemin/vers/les/fichiers')), '/chemin/vers/les/fichiers');

La méthode Phar::buildFromIterator() accepte l'itérateur lui-même comme seul argument. Dans l'exemple ci-dessus, nous avons englobé l'objet RecursiveDirectoryIterator dans un objet RecursiveIteratorIterator, ce dernier donnant le type compatible d'itérateur dont la méthode Phar::buildFromIterator() a besoin.

Nous avons créé une archive Phar qui peut être utilisée dans n'importe quelle application. Voyons comment utiliser facilement cette archive.

IV-E. Utiliser des archives Phar

L'avantage des fichiers Phar est à quel point ils sont faciles à intégrer dans n'importe quelle application, surtout si vous avez utilisé le format d'archive basé sur Phar. Dans ce cas, vous n'avez pas même besoin de l'extension Phar, puisque PHP sait nativement charger le fichier et en extraire le contenu. Les archives basées sur ZIP et TAR requièrent le chargement de l'extension Phar.

Les archives Phar sont conçues pour être incluses dans une application tel que n'importe quel fichier, ce qui rend leur utilisation très simple pour les développeurs déjà habitués à inclure du code tiers. Voyons comme il est facile d'intégrer un Phar dans notre application.

IV-E-1. Intégrer le code d'une archive Phar dans votre application

Le moyen le plus facile d'intégrer du code d'une archive Phar est de simplement inclure l'archive Phar, puis d'inclure le fichier de l'archive Phar que vous souhaitez utiliser. Le gestionnaire de flux phar:// peut être utilisé pour avoir accès à un fichier situé dans une archive Phar chargée, comme indiqué ci-dessous :

Listing 10. Charger du code d'une archive Phar
Sélectionnez
include 'monphar.phar';  
include 'phar://monphar.phar/fichier.php'; 

La première inclusion charge l'archive monphar.phar, ainsi que le code défini dans le fichier bouchon. La seconde inclusion utilise le gestionnaire de flux pour ouvrir l'archive Phar et se charge uniquement d'inclure le fichier indiqué dans l'archive. Notons qu'il n'est pas nécessaire d'inclure l'archive Phar elle-même avant d'inclure un fichier de l'archive.

IV-E-2. Exécuter une application PHP depuis une archive Phar

Une fonctionnalité intéressante des archives Phar est la capacité d'empaqueter une application entière dans une archive Phar et de la distribuer de cette manière. L'avantage de cette approche est que le déploiement devient plus simple sans pénalité de performances, grâce à plusieurs améliorations de Phar en PHP 5.3. Cependant, lorsque vous développez une application pour être exécutée depuis un Phar, voici quelques considérations à prendre en compte relativement à la conception de l'application :

  1. Tout fichier qu'il est nécessaire de créer et qui soit spécifique à une instance de l'application, comme les fichiers de configuration, ne peuvent faire partie de l'archive, de telle sorte que vous devrez les écrire à un emplacement distinct mais accessible. Il en vaut de même si votre application créé des fichiers de cache lors de son exécution.
  2. Pour une portabilité maximale, vous devriez vous tenir au format d'archive basé sur Phar et sans compression. Les formats basés sur ZIP et TAR ont besoin de l'extension Phar installée avec PHP, tandis que le format d'archive basé sur Phar peut être utilisé même si l'extension Phar n'est pas installée.
  3. Toute référence à des fichiers dans l'application doit être changée pour utiliser le gestionnaire de flux phar:// avec le nom de l'archive, comme nous l'avons vu dans la section précédente.

phpMyAdmin est une application particulièrement populaire qui a été empaquetée en Phar afin d'être utilisée comme exemple de la simplicité d'utilisation de Phar. Elle a été entièrement conçue pour être exécutée depuis une archive Phar, mais elle propose néanmoins la possibilité d'écrire son fichier de configuration à l'extérieur de l'archive Phar.

IV-F. Conclusion

Les archives Phar sont un ajout très utile à PHP 5.3. Elles donnent la capacité d'empaqueter du code PHP dans une archive, ce qui peut être utile pour distribuer une application ou une bibliothèque dans un fichier unique. L'archive Phar peut être chargée facilement depuis un fichier PHP au moyen d'une instruction include ou require, ou bien elle peut être exécutée directement depuis le navigateur ou la ligne de commandes en appelant l'archive par son nom.


précédentsommairesuivant

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants : Viadeo Twitter Facebook Share on Google+   

  

Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright © 2008 John Mertic et Guillaume Rossolini. Aucune reproduction, même partielle, ne peut être faite de ce site ni de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.