fileformat.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f9c4a68ef4f89e51e6d9b905ad3ddb6492386dd3 Maintainer: gui Status: ready -->
<!-- Reviewed: yes -->
<chapter xml:id="phar.fileformat" xmlns="http://docbook.org/ns/docbook">
 <title>Qu'est-ce qui fait d'un phar un phar et pas un tar ou un zip ?</title>
 <section xml:id="phar.fileformat.ingredients" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Les constituants de toutes les archives Phar, indépendamment du format de fichier</title>
  <para>
   Toute les archives Phar contiennent de trois à quatre sections:
   <orderedlist>
    <listitem>
     <para>
      Un conteneur
     </para>
    </listitem>
    <listitem>
     <para>
      Un manifest décrivant le contenu
     </para>
    </listitem>
    <listitem>
     <para>
      Le contenu du fichier
     </para>
    </listitem>
    <listitem>
     <para>
      Une signature (facultative) pour vérifier l'intégrité
      (uniquement avec le format de fichier phar)
     </para>
    </listitem>
   </orderedlist>
  </para>
 </section>
 <section xml:id="phar.fileformat.stub" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Le conteneur de fichier Phar</title>
  <para>
   Un conteneur Phar est un simple fichier PHP. Le conteneur minimal contient :
  </para>
  <para>
   <programlisting role="php">
<![CDATA[<?php __HALT_COMPILER();]]>
   </programlisting>
  </para>
  <para>
   Un conteneur doit contenir au moins le jeton <literal>__HALT_COMPILER();</literal>
   en guise de conclusion. Typiquement, un conteneur comportera les fonctionnalités
   de chargement suivantes :
  </para>
  <para>
   <programlisting role="php">
<![CDATA[
<?php
Phar::mapPhar();
include 'phar://monphar.phar/index.php';
__HALT_COMPILER();
   ]]>
   </programlisting>
  </para>
  <para>
   Il n'y a aucune restriction sur le contenu d'un conteneur Phar, si ce n'est le besoin d'être conclu
   par <literal>__HALT_COMPILER();</literal>. Le tag fermant PHP <literal><![CDATA[?>]]></literal> peut être 
   inclus ou omis, mais il ne peut y avoir plus d'un espace entre le <literal>;</literal> et le tag fermant
   <literal><![CDATA[?>]]></literal> sans quoi l'extension phar ne sera pas capable de lire le
   manifeste de l'archive.
  </para>
  <para>
   Dans une archive phar basée sur tar ou zip, le conteneur est stocké dans le fichier
   <literal>.phar/stub.php</literal>.  Le conteneur par défaut des archives Phar basées sur
   phar contient approximativement 7ko de code pour extraire le contenu du phar et l'exécuter.
   Regardez la fonction <function>Phar::createDefaultStub</function> pour davantage de détails.
  </para>
  <para>
   L'alias phar est stocké, dans le cas d'une archive phar basée sur tar ou zip, dans le fichier
   <literal>.phar/alias.txt</literal> en tant que texte plein.
  </para>
 </section>
 <section xml:id="phar.fileformat.comparison" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Comparaison entre Phar, Tar et Zip</title>
  <para>
   Quels sont les avantages et les inconvénients de chacun des trois formats supportés
   par l'extension phar ? Ce tableau tente de répondre à cette question.
   <table>
    <title>Tableau comparatif : Phar, Tar et  Zip</title>
    <tgroup cols="4">
     <thead>
      <row>
       <entry>Fonctionnalité</entry>
       <entry>Phar</entry>
       <entry>Tar</entry>
       <entry>Zip</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Format de fichier standard</entry>
       <entry>Non</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Peut être exécuté sans l'extension Phar
        <link linkend="phar.fileformat.phartip">[1]</link>
       </entry>
       <entry>Oui</entry>
       <entry>Non</entry>
       <entry>Non</entry>
      </row>
      <row>
       <entry>Compression par fichier</entry>
       <entry>Oui</entry>
       <entry>Non</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Compression pour toute l'archive</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Non</entry>
      </row>
      <row>
       <entry>Validation par signature de toute l'archive</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Support d'applications spécifiquement Web</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Métadonnées par fichier</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Métadonnées pour toute l'archive</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Création/modification d'archive
        <link linkend="phar.fileformat.phartip2">[2]</link>
       </entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Support complet de toutes les fonctions de flux</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
      <row>
       <entry>Peut être créée/modifiée même si phar.readonly=1
        <link linkend="phar.fileformat.phartip3">[3]</link>
       </entry>
       <entry>Non</entry>
       <entry>Oui</entry>
       <entry>Oui</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para xml:id="phar.fileformat.phartip">
   <tip>
    <para>
     [1] PHP ne peut accéder directement au contenu d'une archive Phar sans que l'extension
     Phar soit installée si elle utilise un <literal>conteneur</literal>
     qui extrait le contenu de l'archive phar. Le conteneur
     créé par <function>Phar::createDefaultStub</function> extrait
     l'archive phar et exécute son contenu à partir d'un répertoire temporaire si
     aucune extension phar n'est trouvée.
    </para>
   </tip>
  </para>
  <para xml:id="phar.fileformat.phartip2">
   <tip>
    <para>
     [2] Tous les accès en écriture nécessitent que <literal>phar.readonly</literal> soit
     désactivé dans le php.ini ou directement via la ligne de commande.
    </para>
   </tip>
  </para>
  <para xml:id="phar.fileformat.phartip3">
   <tip>
    <para>
     [3] Seules les archives tar ou zip sans <literal>.phar</literal> dans leur
     nom et sans conteneur exécutable <literal>.phar/stub.php</literal>
     peuvent être créées si phar.readonly=1.
    </para>
   </tip>
  </para>
 </section>
 <section xml:id="phar.fileformat.tar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Les phars basés sur Tar</title>
  <para>
   Les archives basées sur le format de fichier tar sont conformes au format moderne
   USTAR. Le design des en-têtes du fichier tar le rend plus efficace que le format de fichier zip
   et aussi efficace que le format de fichier phar quand il s'agit d'accéder aux données.
   Les noms de fichiers sont limités à 255 octets, y compris le chemin complet au sein de l'archive phar
   basée sur tar. Ces archives peuvent être intégralement compressées au format gzip ou bzip2 tout
   en restant exécutables par l'extension Phar.
  </para>
  <para>
   Il y a un support limité pour lire les tarballs dans le format pax interchange,
   mais tout les en-têtes pax reconnues (actuellement, typeflag <literal>x</literal>
   et <literal>g</literal>) sont silencieusement ignorés.
   Il y a aussi un support limité pour les GNU Tar Archives;
   actuellement, les en-têtes <literal>././@LongLink</literal> sont résolus.
  </para>
  <para>
   Pour compresser une archive entière, utilisez <function>Phar::compress</function>.
   Pour décompresser une archive entière, utilisez <function>Phar::decompress</function>.
  </para>
 </section>
 <section xml:id="phar.fileformat.zip" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Les phars basés sur Zip</title>
  <para>
   Les archives basées sur le format de fichier zip supportent de nombreuses fonctionnalités
   incluses dans le format zip. Les métadonnées par fichier ou sur toute l'archive sont stockées
   dans les commentaires du fichier zip et de l'archive zip en tant que chaîne de caractères sérialisée.
   Les commentaires zip déjà existants seront lus sans problème en tant que chaîne. Les lectures/écritures
   compressées sont supportées par la compression zlib DEFLATE, et uniquement les lectures compressées par 
   la compression bzip2. Il n'y a pas de limite sur le nombre de fichiers au sein d'une archive phar
   basée sur zip. Les répertoires vides sont stockés dans l'archive zip comme des fichiers avec un slash final,
   comme <literal>mon/repertoire/</literal>
  </para>
 </section>
 <section xml:id="phar.fileformat.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Le format de fichier Phar</title>
  <para>
   Le format de fichier phar est composé de conteneur/manifeste/contenu/signature, et stocke
   les informations cruciales de ce qui est contenu dans l'archive phar dans son
   <literal>manifeste</literal>.
  </para>
  <para>
   Le manifeste Phar est un format hautement optimisé qui permet la spécification fichier par fichier
   de la compression, des permissions et même des métadonnées utilisateur tels que l'utilisateur ou le
   groupe propriétaire. Toutes les valeurs de plus d'un octet sont stockées sous forme petit-boutiste,
   A l'exception de la version de l'API qui est stockée pour des raisons historiques en 3 morceaux
   grand-boutistes.
  </para>
  <para>
   Tous les drapeaux non utilisés sont réservés pour un usage futur et ne doivent pas être utilisés
   pour stocker des informations personnalisées. Utilisez les métadonnées par fichier pour stocker
   des métadonnées personnalisées sur des fichiers particuliers.
  </para>
  <para>
   Le format de fichier basique du manifeste d'une archive Phar est le suivant :
  </para>
  <para>
   <table>
    <title>Format global du manifeste Phar</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Taille en octets</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4 octets</entry>
       <entry>Longueur du manifeste en octets (limitée à 1 Mo)</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Nombre de fichiers dans le Phar</entry>
      </row>
      <row>
       <entry>2 octets</entry>
       <entry>Version de l'API du manifest Phar (à ce jour 1.0.0)</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Drapeaux "bitmappés" globaux du Phar</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Longueur de l'alias Phar</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>L'alias Phar (longueur basée sur la valeur précédente)</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Longueur des métadonnées Phar (<literal>0</literal> si aucune)</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>métadonnées Phar sérialisées, stockées dans un format <function>serialize</function></entry>
      </row>
      <row>
       <entry>au moins 24 * nombre d'octets des entrées</entry>
       <entry>Entrées pour chaque fichier</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Drapeaux "bitmappés" globaux du Phar</title>
  <para>
   Voici les drapeaux "bitmappés" actuellement reconnus par l'extension Phar
   pour le bitmap plein global de Phar :
  </para>
  <para>
   <table>
    <title>Valeurs de bitmap reconnues</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Valeur</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>0x00010000</literal></entry>
       <entry>Si présent, le Phar contient une signature de vérification</entry>
      </row>
      <row>
       <entry><literal>0x00001000</literal></entry>
       <entry>
        Si présent, le Phar contient au moins 1 fichier qui est
        compressé grâce à zlib DEFLATE
       </entry>
      </row>
      <row>
       <entry><literal>0x00002000</literal></entry>
       <entry>
        Si présent, le Phar contient au moins 1 fichier qui est
        compressé grâce à bzip2
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.manifestfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Définition des entrées du manifeste Phar</title>
  <para>
   Chaque fichier du manifeste contient les informations suivantes :
  </para>
  <para>
   <table>
    <title>Entrée du manifeste Phar</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Taille en octets</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4 octets</entry>
       <entry>Longueur du nom de fichier en octets</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>Nom de fichier (longueur basée sur la valeur précédente)</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Taille du fichier décompressé en octets</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Timestamp Unix du fichier</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Taille du fichier compressé en octets</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Somme de contrôle CRC32 du contenu décompressé du fichier</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Drapeaux bitmappés spécifiques au fichier</entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>Longueur des métadonnées du fichier sérialisées (<literal>0</literal> si aucune)</entry>
      </row>
      <row>
       <entry>??</entry>
       <entry>métadonnées du fichier sérialisées, stockées dans un format <function>serialize</function></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   A noter qu'à partir de l'API 1.1.1, les répertoires vides sont stockés comme des noms de fichier
   avec un slash final comme <literal>mon/repertoire/</literal>
  </para>
  <para>
   Les valeurs reconnues de drapeaux bitmappés spécifiques au fichier sont :
  </para>
  <para>
   <table>
    <title>Valeurs reconnues de bitmap</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Valeur</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>0x000001FF</literal></entry>
       <entry>
        Ces bits sont réservés pour définir des permissions spécifiques au fichier.
        Celles-ci sont utilisées pour <function>fstat</function>
        et peuvent être utilisées pour recréer les permissions souhaitées en cas d'extraction.
       </entry>
      </row>
      <row>
       <entry><literal>0x00001000</literal></entry>
       <entry>
        Si présent, le fichier est compressé grâce à zlib DEFLATE
       </entry>
      </row>
      <row>
       <entry><literal>0x00002000</literal></entry>
       <entry>
        Si présent, le fichier est compressé grâce à bzip2
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
 <section xml:id="phar.fileformat.signature" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Phar Signature format</title>
  <para>
   Les Phar qui contiennent une signature ont toujours la signature ajoutée à la fin du Phar,
   après le chargeur, le manifeste et le contenu.
   Les types de signature supportés à ce jour sont MD5, SHA1, SHA256, SHA512,
   et OPENSSL.
  </para>
  <para>
   <table>
    <title>Format de signature</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Longueur en octets</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>variant</entry>
       <entry>
        La signature actuelle, 20 octets pour une SHA1,
        16 octets pour une MD5, 32 octets pour une SHA256,
        et 64 octets pour une SHA512. La longueur d'une signature
        OPENSSL dépend de la taille de la clé privée.
       </entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>
        Les drapeaux de signature.  <literal>0x0001</literal> est utilisé pour
        définir une signature MD5, <literal>0x0002</literal> pour une SHA1,
        <literal>0x0003</literal> pour une SHA256 et <literal>0x0004</literal>
        pour une SHA512. Le support des signatures SHA256 et SHA512 est disponible
        à partir de la version 1.1.0 de l'API.
        <literal>0x0010</literal> est utilisé pour définir une signature OPENSSL,
        qui est disponible à partir de la version 1.1.1 de l'API, si OpenSSL est disponible.
       </entry>
      </row>
      <row>
       <entry>4 octets</entry>
       <entry>
        <literal>GBMB</literal> magique utilisé pour définir la présence d'une signature.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>
</chapter>

<!-- 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
-->