cvs: phpdoc /en/reference/phar fileformat.xml reference.xml
| From: | Greg Beaver | Date: | Wed, 24 Jan 2007 04:37:45 +0000 |
| Subject: | cvs: phpdoc /en/reference/phar fileformat.xml reference.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969375008@lists.php.net to get a copy of this message | ||
cellog Wed Jan 24 04:37:45 2007 UTC
Added files:
/phpdoc/en/reference/phar fileformat.xml
Modified files:
/phpdoc/en/reference/phar reference.xml
Log:
add documentation on the Phar file format
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/reference.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/phar/reference.xml diff -u phpdoc/en/reference/phar/reference.xml:1.1 phpdoc/en/reference/phar/reference.xml:1.2 --- phpdoc/en/reference/phar/reference.xml:1.1 Thu Jan 18 00:24:34 2007 +++ phpdoc/en/reference/phar/reference.xml Wed Jan 24 04:37:45 2007 @@ -1,5 +1,5 @@ <?xml version = '1.0' encoding = 'iso-8859-1'?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Purpose: --> <!-- Membership: pecl --> <reference id="ref.phar" > @@ -16,19 +16,31 @@ well as iterating over their contents. </para> <para> - PHP Archive files are special collections of files that can be transparently + PHP Archive files (Phars) are special collections of files that can be transparently run right out of the file, similar to Java's jar archive files. Using a phar archive, - it is possible to distribute a complete PHP application in a single file. Phar + it is possible to distribute a complete PHP application in a single file that will + run out of the file without modification or extraction. Phar archives can also be used to store files for extraction similar to tar or zip - archive files. + archive files. Phars support compression using gzip if the + <link linkend="ref.zlib">zlib</link> extension is present, and using bzip2 if + the <link linkend="ref.bzip2">bz2</link> extension is present. In addition, + iteration and other features are available if the <link linkend="ref.spl">SPL</link> + extension is available. Phar signature verification using md5 or sha1 is natively + supported if the <link linkend="ref.hash">hash</link> extension is available. + </para> + <para> + The original implementation for Phar archives was in the PEAR package + <ulink url="http://pear.php.net/PHP_Archive">PHP_Archive</ulink>, and + the implementation details are very similar. </para> </section> <section id="phar.requirements" > &reftitle.required; <para> - Phar requires PHP 5.2.0 or newer, and requires that the - <link linkend="ref.spl">SPL</link> extension - be built into PHP. + Phar requires PHP 5.2.0 or newer. Additional features require the + <link linkend="ref.spl">SPL</link> extension in order to take advantage + of iteration and array access to a Phar's file contents. The <literal>phar</literal> + stream does not require any additional extensions to function. </para> <para> You may optionally wish to enable the <link linkend="ref.zlib" >zlib</link> @@ -46,19 +58,23 @@ <section id="phar.resources" > &reftitle.resources; <para> - + The Phar extension provides the <literal>phar</literal> stream, which + allows accessing files contained within a phar transparently. The + file format of a Phar is described <link linkend="phar.fileformat">here</link> </para> - &no.resource; </section> <section> - <title>Classes</title> + &reftitle.classes; <simplelist> <member> <classname>Phar</classname> + </member> + <member> <classname>PharFileInfo</classname> </member> </simplelist> </section> + &reference.phar.fileformat; </partintro> &reference.phar.functions; </reference> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/fileformat.xml?view=markup&rev=1.1 Index: phpdoc/en/reference/phar/fileformat.xml +++ phpdoc/en/reference/phar/fileformat.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <section id="phar.fileformat"> <title>Phar file format</title> <para> All Phar files contain three to four sections: <orderedlist> <listitem> <para>a stub</para> </listitem> <listitem> <para>a manifest describing the contents</para> </listitem> <listitem> <para>the file contents</para> </listitem> <listitem> <para>[optional] a signature for verifying Phar integrity</para> </listitem> </orderedlist> </para> </section> <section> <title>Phar file stub</title> <para> A Phar's stub is a simple PHP file. The smallest possible stub follows: </para> <para> <programlisting role="php"> <![CDATA[<?php __HALT_COMPILER();]]> </programlisting> </para> <para> A stub must contain as a minimum, the <literal>__HALT_COMPILER();</literal> token at its conclusion. Typically, a stub will contain loader functionality like so: </para> <para> <programlisting role="php"> <![CDATA[ <?php Phar::mapPhar(); include 'phar://myphar.phar/index.php'; __HALT_COMPILER(); ?> ]]> </programlisting> </para> <para> There are no restrictions on the contents of a Phar stub, except for the requirement that it conclude with <literal>__HALT_COMPILER();</literal>. The closing PHP tag <literal><![CDATA[?>]]></literal> may be included or omitted, but there can be no more than 1 space between the <literal>;</literal> and the close tag <literal><![CDATA[?>]]></literal> or the phar extension will be unable to process the Phar archive. </para> </section> <section> <title>Phar Manifest Format</title> <para> The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined meta-data such as user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order. </para> <para> All unused flags are reserved for future use, and must not be used to store custom information. Use the per-file meta-data facility to store customized information about particular files. </para> <para> The basic file format of a Phar archive manifest is as follows: </para> <para> <table> <title>Global Phar manifest format</title> <tgroup cols="2"> <thead> <row> <entry>Size in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>4 bytes</entry> <entry>Length of manifest in bytes (1 MB limit)</entry> </row> <row> <entry>4 bytes</entry> <entry>Number of files in the Phar</entry> </row> <row> <entry>2 bytes</entry> <entry>API version of the Phar manifest (currently 0.9.0)</entry> </row> <row> <entry>4 bytes</entry> <entry>Global Phar bitmapped flags</entry> </row> <row> <entry>4 bytes</entry> <entry>Length of Phar alias</entry> </row> <row> <entry>??</entry> <entry>Phar alias (length based on previous)</entry> </row> <row> <entry>at least 24 * number of entries bytes</entry> <entry>entries for each file</entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Global Phar bitmapped flags</title> <para> Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap: </para> <para> <table> <title>Bitmap values recognized</title> <tgroup cols="2"> <thead> <row> <entry>Value</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>0x00010000</literal></entry> <entry>If set, this Phar contains a verification signature</entry> </row> <row> <entry><literal>0x00001000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with zlib compression </entry> </row> <row> <entry><literal>0x00002000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with bzip compression </entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Phar manifest file entry definition</title> <para> Each file in the manifest contains the following information: </para> <para> <table> <title>Phar Manifest file entry</title> <tgroup cols="2"> <thead> <row> <entry>Size in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>4 bytes</entry> <entry>Filename length in bytes</entry> </row> <row> <entry>??</entry> <entry>Filename (length specified in previous)</entry> </row> <row> <entry>4 bytes</entry> <entry>Un-compressed file size in bytes</entry> </row> <row> <entry>4 bytes</entry> <entry>Unix timestamp of file</entry> </row> <row> <entry>4 bytes</entry> <entry>Compressed file size in bytes</entry> </row> <row> <entry>4 bytes</entry> <entry>CRC32 checksum of un-compressed file contents</entry> </row> <row> <entry>4 bytes</entry> <entry>Bit-mapped File-specific flags</entry> </row> <row> <entry>4 bytes</entry> <entry>Serialized Meta-data length (0 for none)</entry> </row> <row> <entry>??</entry> <entry>Serialized Meta-data, stored in <function>serialize</function> format</entry> </row> </tbody> </tgroup> </table> </para> <para> The File-specific bitmap values recognized are: </para> <para> <table> <title>Bitmap values recognized</title> <tgroup cols="2"> <thead> <row> <entry>Value</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>0x000001FF</literal></entry> <entry> These bits are reserved for defining specific file permissions of a file. Permissions are used for <function>fstat</function> and can be used to recreate desired permissions upon extraction. </entry> </row> <row> <entry><literal>0x00001000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with zlib compression </entry> </row> <row> <entry><literal>0x00002000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with bzip compression </entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Phar Signature format</title> <para> Phars containing a signature always have the signature </para> <para> <table> <title>Signature format</title> <tgroup cols="2"> <thead> <row> <entry>Length in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>16 or 20 bytes</entry> <entry> The actual signature, 20 bytes for an SHA1 signature, 16 bytes for an MD5 signature. </entry> </row> <row> <entry>4 bytes</entry> <entry> Signature flags. <literal>0x0001</literal> is used to define an MD5 signature, and <literal>0x0001</literal> is used to define an SHA1 signature. </entry> </row> <row> <entry>4 bytes</entry> <entry> Magic "GBMB" used to define the presence of a signature. </entry> </row> </tbody> </tgroup> </table> </para> </section> <!-- 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:"../../../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 -->
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/reference.xml?r1=1.1&r2=1.2&diff_format=u Index: phpdoc/en/reference/phar/reference.xml diff -u phpdoc/en/reference/phar/reference.xml:1.1 phpdoc/en/reference/phar/reference.xml:1.2 --- phpdoc/en/reference/phar/reference.xml:1.1 Thu Jan 18 00:24:34 2007 +++ phpdoc/en/reference/phar/reference.xml Wed Jan 24 04:37:45 2007 @@ -1,5 +1,5 @@ <?xml version = '1.0' encoding = 'iso-8859-1'?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Purpose: --> <!-- Membership: pecl --> <reference id="ref.phar" > @@ -16,19 +16,31 @@ well as iterating over their contents. </para> <para> - PHP Archive files are special collections of files that can be transparently + PHP Archive files (Phars) are special collections of files that can be transparently run right out of the file, similar to Java's jar archive files. Using a phar archive, - it is possible to distribute a complete PHP application in a single file. Phar + it is possible to distribute a complete PHP application in a single file that will + run out of the file without modification or extraction. Phar archives can also be used to store files for extraction similar to tar or zip - archive files. + archive files. Phars support compression using gzip if the + <link linkend="ref.zlib">zlib</link> extension is present, and using bzip2 if + the <link linkend="ref.bzip2">bz2</link> extension is present. In addition, + iteration and other features are available if the <link linkend="ref.spl">SPL</link> + extension is available. Phar signature verification using md5 or sha1 is natively + supported if the <link linkend="ref.hash">hash</link> extension is available. + </para> + <para> + The original implementation for Phar archives was in the PEAR package + <ulink url="http://pear.php.net/PHP_Archive">PHP_Archive</ulink>, and + the implementation details are very similar. </para> </section> <section id="phar.requirements" > &reftitle.required; <para> - Phar requires PHP 5.2.0 or newer, and requires that the - <link linkend="ref.spl">SPL</link> extension - be built into PHP. + Phar requires PHP 5.2.0 or newer. Additional features require the + <link linkend="ref.spl">SPL</link> extension in order to take advantage + of iteration and array access to a Phar's file contents. The <literal>phar</literal> + stream does not require any additional extensions to function. </para> <para> You may optionally wish to enable the <link linkend="ref.zlib" >zlib</link> @@ -46,19 +58,23 @@ <section id="phar.resources" > &reftitle.resources; <para> - + The Phar extension provides the <literal>phar</literal> stream, which + allows accessing files contained within a phar transparently. The + file format of a Phar is described <link linkend="phar.fileformat">here</link> </para> - &no.resource; </section> <section> - <title>Classes</title> + &reftitle.classes; <simplelist> <member> <classname>Phar</classname> + </member> + <member> <classname>PharFileInfo</classname> </member> </simplelist> </section> + &reference.phar.fileformat; </partintro> &reference.phar.functions; </reference> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/phar/fileformat.xml?view=markup&rev=1.1 Index: phpdoc/en/reference/phar/fileformat.xml +++ phpdoc/en/reference/phar/fileformat.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <section id="phar.fileformat"> <title>Phar file format</title> <para> All Phar files contain three to four sections: <orderedlist> <listitem> <para>a stub</para> </listitem> <listitem> <para>a manifest describing the contents</para> </listitem> <listitem> <para>the file contents</para> </listitem> <listitem> <para>[optional] a signature for verifying Phar integrity</para> </listitem> </orderedlist> </para> </section> <section> <title>Phar file stub</title> <para> A Phar's stub is a simple PHP file. The smallest possible stub follows: </para> <para> <programlisting role="php"> <![CDATA[<?php __HALT_COMPILER();]]> </programlisting> </para> <para> A stub must contain as a minimum, the <literal>__HALT_COMPILER();</literal> token at its conclusion. Typically, a stub will contain loader functionality like so: </para> <para> <programlisting role="php"> <![CDATA[ <?php Phar::mapPhar(); include 'phar://myphar.phar/index.php'; __HALT_COMPILER(); ?> ]]> </programlisting> </para> <para> There are no restrictions on the contents of a Phar stub, except for the requirement that it conclude with <literal>__HALT_COMPILER();</literal>. The closing PHP tag <literal><![CDATA[?>]]></literal> may be included or omitted, but there can be no more than 1 space between the <literal>;</literal> and the close tag <literal><![CDATA[?>]]></literal> or the phar extension will be unable to process the Phar archive. </para> </section> <section> <title>Phar Manifest Format</title> <para> The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined meta-data such as user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order. </para> <para> All unused flags are reserved for future use, and must not be used to store custom information. Use the per-file meta-data facility to store customized information about particular files. </para> <para> The basic file format of a Phar archive manifest is as follows: </para> <para> <table> <title>Global Phar manifest format</title> <tgroup cols="2"> <thead> <row> <entry>Size in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>4 bytes</entry> <entry>Length of manifest in bytes (1 MB limit)</entry> </row> <row> <entry>4 bytes</entry> <entry>Number of files in the Phar</entry> </row> <row> <entry>2 bytes</entry> <entry>API version of the Phar manifest (currently 0.9.0)</entry> </row> <row> <entry>4 bytes</entry> <entry>Global Phar bitmapped flags</entry> </row> <row> <entry>4 bytes</entry> <entry>Length of Phar alias</entry> </row> <row> <entry>??</entry> <entry>Phar alias (length based on previous)</entry> </row> <row> <entry>at least 24 * number of entries bytes</entry> <entry>entries for each file</entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Global Phar bitmapped flags</title> <para> Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap: </para> <para> <table> <title>Bitmap values recognized</title> <tgroup cols="2"> <thead> <row> <entry>Value</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>0x00010000</literal></entry> <entry>If set, this Phar contains a verification signature</entry> </row> <row> <entry><literal>0x00001000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with zlib compression </entry> </row> <row> <entry><literal>0x00002000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with bzip compression </entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Phar manifest file entry definition</title> <para> Each file in the manifest contains the following information: </para> <para> <table> <title>Phar Manifest file entry</title> <tgroup cols="2"> <thead> <row> <entry>Size in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>4 bytes</entry> <entry>Filename length in bytes</entry> </row> <row> <entry>??</entry> <entry>Filename (length specified in previous)</entry> </row> <row> <entry>4 bytes</entry> <entry>Un-compressed file size in bytes</entry> </row> <row> <entry>4 bytes</entry> <entry>Unix timestamp of file</entry> </row> <row> <entry>4 bytes</entry> <entry>Compressed file size in bytes</entry> </row> <row> <entry>4 bytes</entry> <entry>CRC32 checksum of un-compressed file contents</entry> </row> <row> <entry>4 bytes</entry> <entry>Bit-mapped File-specific flags</entry> </row> <row> <entry>4 bytes</entry> <entry>Serialized Meta-data length (0 for none)</entry> </row> <row> <entry>??</entry> <entry>Serialized Meta-data, stored in <function>serialize</function> format</entry> </row> </tbody> </tgroup> </table> </para> <para> The File-specific bitmap values recognized are: </para> <para> <table> <title>Bitmap values recognized</title> <tgroup cols="2"> <thead> <row> <entry>Value</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>0x000001FF</literal></entry> <entry> These bits are reserved for defining specific file permissions of a file. Permissions are used for <function>fstat</function> and can be used to recreate desired permissions upon extraction. </entry> </row> <row> <entry><literal>0x00001000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with zlib compression </entry> </row> <row> <entry><literal>0x00002000</literal></entry> <entry> If set, this Phar contains at least 1 file that is compressed with bzip compression </entry> </row> </tbody> </tgroup> </table> </para> </section> <section> <title>Phar Signature format</title> <para> Phars containing a signature always have the signature </para> <para> <table> <title>Signature format</title> <tgroup cols="2"> <thead> <row> <entry>Length in bytes</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry>16 or 20 bytes</entry> <entry> The actual signature, 20 bytes for an SHA1 signature, 16 bytes for an MD5 signature. </entry> </row> <row> <entry>4 bytes</entry> <entry> Signature flags. <literal>0x0001</literal> is used to define an MD5 signature, and <literal>0x0001</literal> is used to define an SHA1 signature. </entry> </row> <row> <entry>4 bytes</entry> <entry> Magic "GBMB" used to define the presence of a signature. </entry> </row> </tbody> </tgroup> </table> </para> </section> <!-- 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:"../../../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 -->