doc-fr/reference/phar/book.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 562a216c8108885a492cbfb66e2d5734847fa19d Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<book xml:id="book.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <?phpdoc extension-membership="bundled" ?>
 <title>Phar</title>
 
 <!-- {{{ preface -->
 <preface xml:id="intro.phar">
  &reftitle.intro;
  <para>
   L'extension phar fournit un moyen de mettre une application PHP complète dans un fichier unique 
   appelé un "phar" (PHP Archive) pour une installation et une configuration aisées.
   En plus de ce service, l'extension fournit aussi une classe d'abstraction de format de fichier
   pour créer et manipuler des fichiers tar et zip à travers la classe
   <classname>PharData</classname>, tout comme
   PDO fournit une interface unifiée pour accéder à des bases de données différentes. Mais à l'inverse de PDO,
   qui ne peut pas transposer les données d'une base à l'autre, Phar a la possibilité de convertir des fichiers tar,
   zip et phar avec une simple ligne de code. Regardez
   <function>Phar::convertToExecutable</function> pour avoir un exemple.
  </para>
  <para>
   Qu'est-ce que phar? Les archives phar sont en fait un moyen pratique de grouper 
   plusieurs fichiers en un seul. Ainsi, une archive phar permet de distribuer une
   application PHP complète dans un fichier unique et de l'exécuter à partir de ce fichier
   sans pour autant l'extraire sur le disque. De plus, des archives phar peuvent être exécutées
   par PHP aussi facilement que n'importe quel autre fichier, aussi bien en ligne de commande que via
   un serveur web. Phar est une sorte de clé USB pour les applications PHP.
  </para>
  <para>
   Phar implémente cette fonctionnalité via <link linkend="book.stream">un 
   flux</link>.  Normalement, pour utiliser un fichier externe à partir d'un script PHP, vous
   devez utiliser la fonction <function>include</function>:
  </para>
  <para>
   <example>
    <title>Utiliser un fichier externe</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 include '/chemin/vers/le/fichier/externe.php';
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   On peut considérer que PHP traduit en fait
   <literal>/chemin/vers/le/fichier/externe.php</literal> en un
   flux <literal>file:///chemin/vers/le/fichier/externe.php</literal>, et qu'il
   utilise de façon cachée les fonctions de flux de fichiers plats pour accéder
   à des fichiers locaux.
  </para>
  <para>
   Pour utiliser un fichier nommé <literal>fichier.php</literal> contenu dans une archive phar
   <literal>/chemin/vers/monphar.phar</literal>,
   la syntaxe est quasi similaire à la syntaxe <literal>file://</literal> ci-dessus.
  </para>
  <para>
   <example>
    <title>Utilier un fichier contenu dans une archive phar</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 include 'phar:///chemin/vers/monphar.phar/fichier.php';
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   En fait, on peut traiter une archive phar comme s'il s'agissait d'un disque externe, en utilisant
   n'importe laquelle des fonctions relatives à <function>fopen</function>, <function>opendir</function> et
   <function>mkdir</function> pour lire, changer ou créer des nouveaux fichiers ou répertoires au sein de
   l'archive phar. Celà permet à des applications PHP complètes d'être distribuées dans un seul fichier
   et d'être exécutées à partir de celui-ci
  </para>
  <para>
   L'utilisation la plus courant d'une archive phar est de distribuer une application complète
   en un seul fichier. Par exemple, l'installeur PEAR qui est inclus avec les versions de PHP
   est distribué grâce à une archive phar. pour utiliser l'archive phar ainsi distribuée, celle-ci
   peut-être exécutée via la ligne de commande ou via un navigateur web.
  </para>
  <para>
   Les archives phar peuvent être distribuées sous forme de fichiers <literal>tar</literal>,
   de fichiers <literal>zip</literal> ou de fichiers <literal>phar</literal> spécialement conçus
   pour l'extensions phar. Chaque format de fichier a ses avantages et ses inconvénients. Les fichiers
   zip et tar peuvent être extraits par n'importe quel outil tiers qui peut lire le format, mais 
   requièrent l'extension phar pour être exécutés par PHP. Le format de fichier phar est unique et dédié
   à l'extension phar et peut être créé uniquement par celle-ci ou par le paquet PEAR
   <link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, mais a l'avantage de ne pas 
   nécessiter l'installation de l'extension phar pour que l'application empaquetée puisse être exécutée.
  </para>
  <para>
   En d'autres mots, même avec l'extension phar désactivée, il est possible d'exécuter ou d'inclure
   une archive basée sur phar. Accéder à des fichiers individuels au sein d'une archive phar n'est 
   possible qu'avec l'extension phar à moins que l'archive phar n'ait été créée par PHP_Archive.
  </para>
  <para>
   L'extension phar est aussi capable de convertir une archive phar à partir d'un tar vers un fichier zip 
   ou phar en une seule commande :
  </para>
  <para>
   <example>
    <title>Convertir une archive phar au format tar</title>
    <programlisting role="php">
     <![CDATA[
 <?php
 $phar = new Phar('monphar.phar');
 $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // produit monphar.phar.tar.gz
 ?>
     ]]>
    </programlisting>
   </example>
  </para>
  <para>
   Phar peut compresser des fichiers individuels ou une archive entière en
   utilisant la compression <link linkend="book.zlib">gzip</link> ou
   <link linkend="book.bzip2">bzip2</link>, et peut vérifier l'intégrité de l'archive
   automatiquement en utilisant des fonctions de signature MD5, SHA-1, SHA-256 ou SHA-512.
  </para>
  <para>
   Enfin, l'extension phar est orientée sécurité, elle désactive par défaut les accès 
   en écriture sur les archives phar exécutables et requiert la désactivation au niveau système
   du paramètre <literal>phar.readonly</literal> du php.ini pour créer ou modifier des archives phar.
   Des archives tar et zip sans le marqueur exécutable peuvent toujours être créées ou modifiées
   en utilisant la classe <classname>PharData</classname>.
  </para>
  <para>
   Si vous créez des applications dans le but de les distribuer, vous devriez lire
   <link linkend="phar.creating">Comment créer des archives Phar</link>. Si vous voulez
   davantage d'informations sur les différences entre les formats de fichier que phar supporte,
   vous devriez lire <link linkend="phar.fileformat">Phar, Tar et Zip</link>.
  </para>
  <para>
   Si vous utilisez des applications phar, il y a des astuces très utiles dans
   <link linkend="phar.using">Comment utiliser des archives Phar</link>.
  </para>
  <para>
   Le mot <literal>phar</literal> est la contraction de <literal>PHP</literal> et de
   <literal>Archive</literal>  et est grandement inspiré
   du mot <literal>jar</literal> (Java Archive) familier aux développeurs Java.
  </para>
  <para>
   L'implémentation des archives Phar est basée sur le paquet PEAR
   <link xlink:href="&url.pear.package;PHP_Archive">PHP_Archive</link>, et
   les détails d'implémentations sont les mêmes, bien que l'extension Phar
   soit plus puissante. En plus, celle-ci permet à la plupart des applications
   PHP d'être exécutées sans modification alors que les archives basées sur PHP_Archive
   requièrent souvent beaucoup de modifications pour fonctionner.
  </para>
 </preface>
 <!-- }}} -->
 
 &reference.phar.setup;
 &reference.phar.constants;
 &reference.phar.using;
 &reference.phar.creating;
 &reference.phar.fileformat;
 &reference.phar.Phar;
 &reference.phar.PharData;
 &reference.phar.PharFileInfo;
 &reference.phar.PharException;

</book>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->