sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/reference/phar/fileformat.xml
Sergey Panteleev f9c4a68ef4
Removed references to PHP 5, PHP 7.0 (#548)
2021-04-26 11:46:55 +03:00

515 lines
16 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="phar.fileformat" xmlns="http://docbook.org/ns/docbook">
<title>What makes a phar a phar and not a tar or a zip?</title>
<section xml:id="phar.fileformat.ingredients" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Ingredients of all Phar archives, independent of file format</title>
<para>
All Phar archives 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 (phar file format only)</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>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's manifest.
</para>
<para>
In a tar or zip-based phar archive, the stub is stored in the
<literal>.phar/stub.php</literal> file. The default stub for phar-based
Phar archives contains approximately 7k of code to extract the contents
of the phar and execute them. See <function>Phar::createDefaultStub</function>
for more detail.
</para>
<para>
The phar alias is stored in a tar or zip-based phar archive in the
<literal>.phar/alias.txt</literal> file as plain text.
</para>
</section>
<section xml:id="phar.fileformat.comparison" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Head-to-head comparison of Phar, Tar and Zip</title>
<para>
What are the good and the bad things about the three supported file formats in
the phar extension? This table attempts to address that question.
<table>
<title>Feature matrix: Phar vs. Tar vs. Zip</title>
<tgroup cols="4">
<thead>
<row>
<entry>Feature</entry>
<entry>Phar</entry>
<entry>Tar</entry>
<entry>Zip</entry>
</row>
</thead>
<tbody>
<row>
<entry>Standard File Format</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Can be executed without the Phar Extension
<link linkend="phar.fileformat.phartip">[1]</link>
</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>Per-file compression</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Whole-archive compression</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Whole-archive signature validation</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Web-specific application support</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Per-file Meta-data</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Whole-Archive Meta-data</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Archive creation/modification
<link linkend="phar.fileformat.phartip2">[2]</link>
</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Full support for all stream wrapper functions</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Can be created/modified even if phar.readonly=1
<link linkend="phar.fileformat.phartip3">[3]</link>
</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para xml:id="phar.fileformat.phartip">
<tip>
<para>
[1] PHP can only directly access the contents of a Phar archive
without the Phar extension if it is using a <literal>stub</literal>
that extracts the contents of the phar archive. The stub
created by <function>Phar::createDefaultStub</function> extracts
the phar archive and runs its contents from a temporary directory
if no phar extension is found.
</para>
</tip>
</para>
<para xml:id="phar.fileformat.phartip2">
<tip>
<para>
[2] All write access requires <literal>phar.readonly</literal> to
be disabled in php.ini or on the command-line directly.
</para>
</tip>
</para>
<para xml:id="phar.fileformat.phartip3">
<tip>
<para>
[3] Only tar and zip archives without <literal>.phar</literal> in their
filename and without an executable stub <literal>.phar/stub.php</literal>
can be created if 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>Tar-based phars</title>
<para>
Archives based on the tar file format follow the more modern USTAR
file format. The design of the tar file header makes them more efficient
to access than the zip file format, and almost as efficient as the phar
file format. File names are limited to 255 bytes, including
full path within the phar archive. There is no limit on the number of files
within a tar-based phar archive. These archives can fully compressed in
gzip or bzip2 format and still be executed by the Phar extension.
</para>
<para>
There is limited support for reading tarballs in pax interchange format,
but all recognized pax headers (currently, typeflag <literal>x</literal> and
<literal>g</literal>) are silently ignored.
There is also limited support for GNU Tar Archives;
currently, <literal>././@LongLink</literal> headers are resolved.
</para>
<para>
To compress an entire archive, use <function>Phar::compress</function>.
To decompress an entire archive, use <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>Zip-based phars</title>
<para>
Archives based on the zip file format support several features built into
the zip file format. Per-file and whole-archive metadata is stored in
the zip file comment and zip archive comment as a serialized string. Pre-existing
zip comments will be successfully read as a string. Per-file compression
read/write is supported with zlib DEFLATE compression, and read access is supported
with bzip2 compression. There is no limit on the number of files
within a zip-based phar archive. Empty directories are stored in the zip archive
as files with a trailing slash like <literal>my/directory/</literal>
</para>
</section>
<section xml:id="phar.fileformat.phar" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Phar File Format</title>
<para>
The phar file format is literally laid out as stub/manifest/contents/signature, and
stores the crucial information of what is included in the phar archive in its
<literal>manifest</literal>.
</para>
<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 file 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 1.0.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>4 bytes</entry>
<entry>Length of Phar metadata (<literal>0</literal> for none)</entry>
</row>
<row>
<entry>??</entry>
<entry>Serialized Phar Meta-data, stored in <function>serialize</function> format</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 xml:id="phar.fileformat.flags" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<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 DEFLATE compression
</entry>
</row>
<row>
<entry><literal>0x00002000</literal></entry>
<entry>
If set, this Phar contains at least 1 file that
is compressed with bzip2 compression
</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>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 File Meta-data length (<literal>0</literal> for none)</entry>
</row>
<row>
<entry>??</entry>
<entry>Serialized File Meta-data, stored in <function>serialize</function> format</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Note that as of API version 1.1.1, empty directories are stored as filenames
with a trailing slash like <literal>my/directory/</literal>
</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 file is compressed with zlib DEFLATE compression
</entry>
</row>
<row>
<entry><literal>0x00002000</literal></entry>
<entry>
If set, this file is compressed with bzip2 compression
</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>
Phars containing a signature always have the signature appended to the
end of the Phar archive after the loader, manifest, and file contents.
The signature formats supported at this time are MD5, SHA1, SHA256, SHA512,
and OPENSSL.
</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>varying</entry>
<entry>
The actual signature, 20 bytes for an SHA1 signature,
16 bytes for an MD5 signature, 32 bytes for an SHA256 signature,
and 64 bytes for an SHA512 signature. The length of an OPENSSL
signature depends on the size of the private key.
</entry>
</row>
<row>
<entry>4 bytes</entry>
<entry>
Signature flags. <literal>0x0001</literal> is used to
define an MD5 signature, <literal>0x0002</literal> is used
to define an SHA1 signature, <literal>0x0003</literal> is used
to define an SHA256 signature, and <literal>0x0004</literal> is
used to define an SHA512 signature. The SHA256 and SHA512 signature
support is available as of API version 1.1.0.
<literal>0x0010</literal> is used to define an OPENSSL signature, what
is available as of API version 1.1.1, if OpenSSL is available.
</entry>
</row>
<row>
<entry>4 bytes</entry>
<entry>
Magic <literal>GBMB</literal> used to define the presence of a 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
-->
Reference in a new issue View git blame Copy permalink