add documentation on the Phar file format

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228018 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Greg Beaver 2007-01-24 04:37:45 +00:00
parent a1baf6142a
commit 4257d89464
2 changed files with 344 additions and 10 deletions

View file

@ -0,0 +1,318 @@
<?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 &quot;GBMB&quot; 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
-->

View file

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