diff --git a/reference/phar/fileformat.xml b/reference/phar/fileformat.xml
new file mode 100644
index 0000000000..5d6e9f1c06
--- /dev/null
+++ b/reference/phar/fileformat.xml
@@ -0,0 +1,318 @@
+
+
+
+ Phar file format
+
+ All Phar files contain three to four sections:
+
+
+ a stub
+
+
+ a manifest describing the contents
+
+
+ the file contents
+
+
+ [optional] a signature for verifying Phar integrity
+
+
+
+
+
+ Phar file stub
+
+ A Phar's stub is a simple PHP file. The smallest possible stub follows:
+
+
+
+
+
+
+
+ A stub must contain as a minimum, the __HALT_COMPILER(); token
+ at its conclusion. Typically, a stub will contain loader functionality
+ like so:
+
+
+
+
+ ]]>
+
+
+
+ There are no restrictions on the contents of a Phar stub, except for the requirement
+ that it conclude with __HALT_COMPILER();. The closing PHP tag
+ ]]> may be included or omitted, but there can be
+ no more than 1 space between the ; and the close tag
+ ]]> or the phar extension will be unable
+ to process the Phar archive.
+
+
+
+ Phar Manifest Format
+
+ 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.
+
+
+ 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.
+
+
+ The basic file format of a Phar archive manifest is as follows:
+
+
+
+ Global Phar manifest format
+
+
+
+ Size in bytes
+ Description
+
+
+
+
+ 4 bytes
+ Length of manifest in bytes (1 MB limit)
+
+
+ 4 bytes
+ Number of files in the Phar
+
+
+ 2 bytes
+ API version of the Phar manifest (currently 0.9.0)
+
+
+ 4 bytes
+ Global Phar bitmapped flags
+
+
+ 4 bytes
+ Length of Phar alias
+
+
+ ??
+ Phar alias (length based on previous)
+
+
+ at least 24 * number of entries bytes
+ entries for each file
+
+
+
+
+
+
+
+ Global Phar bitmapped flags
+
+ Here are the bitmapped flags currently recognized by the Phar extension
+ for the global Phar flat bitmap:
+
+
+
+ Bitmap values recognized
+
+
+
+ Value
+ Description
+
+
+
+
+ 0x00010000
+ If set, this Phar contains a verification signature
+
+
+ 0x00001000
+
+ If set, this Phar contains at least 1 file that
+ is compressed with zlib compression
+
+
+
+ 0x00002000
+
+ If set, this Phar contains at least 1 file that
+ is compressed with bzip compression
+
+
+
+
+
+
+
+
+ Phar manifest file entry definition
+
+ Each file in the manifest contains the following information:
+
+
+
+ Bitmap values recognized
+
+
+
+ Value
+ Description
+
+
+
+
+ 0x000001FF
+
+ These bits are reserved for defining specific file permissions
+ of a file. Permissions are used for fstat
+ and can be used to recreate desired permissions upon extraction.
+
+
+
+ 0x00001000
+
+ If set, this Phar contains at least 1 file that
+ is compressed with zlib compression
+
+
+
+ 0x00002000
+
+ If set, this Phar contains at least 1 file that
+ is compressed with bzip compression
+
+
+
+
+
+
+
+
+ Phar Signature format
+
+ Phars containing a signature always have the signature
+
+
+
+ Signature format
+
+
+
+ Length in bytes
+ Description
+
+
+
+
+ 16 or 20 bytes
+
+ The actual signature, 20 bytes for an SHA1 signature,
+ 16 bytes for an MD5 signature.
+
+
+
+ 4 bytes
+
+ Signature flags. 0x0001 is used to
+ define an MD5 signature, and 0x0001 is used
+ to define an SHA1 signature.
+
+
+
+ 4 bytes
+
+ Magic "GBMB" used to define the presence of a signature.
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/reference/phar/reference.xml b/reference/phar/reference.xml
index 1233b652cd..75f46663bf 100644
--- a/reference/phar/reference.xml
+++ b/reference/phar/reference.xml
@@ -1,5 +1,5 @@
-
+
@@ -16,19 +16,31 @@
well as iterating over their contents.
- 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
+ zlib extension is present, and using bzip2 if
+ the bz2 extension is present. In addition,
+ iteration and other features are available if the SPL
+ extension is available. Phar signature verification using md5 or sha1 is natively
+ supported if the hash extension is available.
+
+
+ The original implementation for Phar archives was in the PEAR package
+ PHP_Archive, and
+ the implementation details are very similar.
&reftitle.required;
- Phar requires PHP 5.2.0 or newer, and requires that the
- SPL extension
- be built into PHP.
+ Phar requires PHP 5.2.0 or newer. Additional features require the
+ SPL extension in order to take advantage
+ of iteration and array access to a Phar's file contents. The phar
+ stream does not require any additional extensions to function.
You may optionally wish to enable the zlib
@@ -46,19 +58,23 @@
&reftitle.resources;
-
+ The Phar extension provides the phar stream, which
+ allows accessing files contained within a phar transparently. The
+ file format of a Phar is described here
- &no.resource;
- Classes
+ &reftitle.classes;
Phar
+
+ PharFileInfo
+ &reference.phar.fileformat;
&reference.phar.functions;