mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
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
parent
a1baf6142a
commit
4257d89464
2 changed files with 344 additions and 10 deletions
318
reference/phar/fileformat.xml
Normal file
318
reference/phar/fileformat.xml
Normal 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 "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
|
||||
-->
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue