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