Introducing pecl extension phar

Update 2007-02-11: http:/www.php.net/phar now contains the current docs for the phar extension.

After 14 months and nearly 200 commits, Marcus Börger and I have finished the first release of the phar extension in PECL. Phar provides both a stream wrapper (phar://) and a Phar class which can be used to access the contents of a phar archive. What is a phar archive? Think of it as a virtual filesystem that is customized for use with PHP, sort of like a Java .jar archive. Incidentally, the phar extension is a C implementation of the principles behind the PHP_Archive PEAR package.

So how do you use the phar extension? Complete docs are at http://www.php.net/phar, but as of this time, the manual has not yet been rebuilt from CVS, which corrects several minor and a few major errors (most are obvious). Basically, first you need to create a Phar archive. To do this, you need to install the phar extension via "pecl install phar-beta" and then to enable it in php.ini. You also need PHP 5.2.0 or newer, and will need the zlib or bzip2 extensions for compression. SPL is also needed to take advantage of the Phar object, but is not required for basic stream access.

To create a phar object, you will need to disable "phar.readonly" in php.ini with:

phar.readonly=0

There are two basic ways to create a file within a phar archive. First, using streams:

and then using the Phar object:

As you can see, both are very intuitive. Phar archives are designed so that they can contain a "bootstrap loader stub" which is a PHP script that can be used to allow running a phar archive as if it were an executable script:

php my.phar

However, phar archives can also be accessed directly using the phar stream wrapper:

If SPL is enabled, the Phar object extends DirectoryIterator, allowing iteration over a Phar's contents, for instance in order to extract a phar's contents:

The primary motivations for implementing PHP_Archive in C were caused by the introduction of the allow_url_include and allow_url_fopen INI directives. These directives are designed to prevent users from opening up arbitrary code execution vulnerabilties by executing or opening untrusted remote data. The assumption behind these directives is that local data is much more likely to be controlled and therefore safe. C extensions are allowed to define themselves as "local" streams (like the file:// plain file wrapper, for instance).

Phar is much more powerful than PHP_Archive, but is also compatible with PHP_Archive-created .phar archives as of PHP_Archive version 0.10.0 (which was released yesterday).