Note: This manual is provided for your convenience only - this is not the official source and may not be 100% up to date.
CXXIII. Phar archive stream and classes
The phar extension provides the phar stream wrapper and the Phar class for manipulating self-contained PHP Archive (phar) files. The Phar class can be used to create and to extract contents of phar files as well as iterating over their contents.
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 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. 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 to ensure archive integrity.
The original implementation for Phar archives was in the PEAR package PHP_Archive, and the implementation details are very similar, although the Phar extension is more full-featured. PHP_Archive has more flexibility in Phar creation, and helpful debugging tools like the PHP_Archive_Manager class, and the Phar extension supports iteration, array access, and directly manipulating Phar contents through a simple interface. PHP_Archive supports creation of Phar archives that can be processed using the Phar extension or PHP_Archive seamlessly, whereas the Phar extension is designed to create extensions that function with the Phar extension. In addition, the Phar extension will continue to work even if the allow_url_include or allow_url_fopen INI variables are disabled, while PHP_Archive-based Phar archives (without the Phar extension) will not function.
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.
Windows binaries may be found at http://snaps.php.net/. To install, download php_phar.dll to the folder specified by your php.ini file's extension_dir directive. Enable it by adding extension=php_phar.dll to your php.ini and restarting your web server.
Linux, BSD, and other *nix variants can be compiled using the following steps:
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/phar.
The behaviour of these functions is affected by settings in php.ini.
Table 1. Filesystem and Streams Configuration Options
Here's a short explanation of the configuration directives.
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
Phar archives are similar in concept to Java JAR archives, but are tailored to the needs and to the flexibility of PHP applications. A Phar archive is used to distribute a complete PHP application or library in a single file. Unlike Java's implementation of JAR archives, no external tool is required to process or run a PHP Phar archive. A Phar archive application is processed exactly like any other PHP application:
Using a Phar archive library is identical to using any other PHP library:
What makes Phar archives incredibly useful is the phar stream wrapper, which is explained in depth here. Using this stream wrapper, it is possible to access individual files within a phar as if the phar were its own filesystem. The phar stream wrapper supports all read/write operations on files, and opendir() on directories.
Also provided with the Phar extension is the Phar class, which allows accessing the files of the Phar archive as if it were an associative array, and other functionality. The Phar class is explained here.
The Phar stream wrapper fully supports fopen() for read, write or append, unlink(), stat(), fstat(), fseek(), rename() and directory stream operation opendir(). The Phar stream wrapper does not support creating or erasing a directory, as files are stored only as files, and the concept of an abstract directory does not exist.
Individual file compression and per-file metadata can also be manipulated in a Phar archive using stream contexts:
Although it is possible to create phar archives from scratch just using stream operations, it is best to use the functionality built into the Phar class. The stream wrapper is best used for read operations.
The Phar class supports reading and manipulation of Phar archives, as well as iteration through inherited functionality of the RecursiveDirectoryIterator class. With support for the ArrayAccess interface, files inside a Phar archive can be accessed as if they were part of an associative array.
It is important to note that when creating a Phar archive, the full path should be passed to the Phar object constructor. Relative paths will fail to initialize.
Assuming that $p is a Phar object initialized as follows:
An empty Phar archive will be created at /path/to/myphar.phar, or if /path/to/myphar.phar already exists, it will be opened again. The literal myphar.phar deomnstrates the concept of an alias that can be used to reference /path/to/myphar.phar in URLs as in:
With the newly created $p Phar object, the following is possible:
In addition, the Phar object is the only way to access Phar-specific metadata, through Phar->getMetaData(), and the only way to set or retrieve a Phar archive's PHP loader stub through Phar->getStub() and Phar->setStub(). Additionally, compression for the entire Phar archive at once can only be manipulated using the Phar class.
The full list of Phar object functionality is documented below.
The PharFileInfo class extends the SplFileInfo class, and adds several methods for manipulating Phar-specific details of a file contained within a Phar, such as manipulating compression and metadata.
All Phar files contain three to four sections:
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's manifest.
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.
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:
Table 2. Global Phar manifest format
Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap:
Each file in the manifest contains the following information:
Table 4. Phar Manifest file entry
The File-specific bitmap values recognized are:
Table 5. Bitmap values recognized
Phars containing a signature always have the signature appended to the end of the Phar archive after the loader, manifest, and file contents. The two signature formats supported at this time are MD5 and SHA1.
Table 6. Signature format