PHP phar archive (without stub): format specification

A phar (PHP archive) file. The phar format is a custom archive format from the PHP ecosystem that is used to package a complete PHP library or application into a single self-contained archive. All phar archives start with an executable PHP stub, which can be used to allow executing or including phar files as if they were regular PHP scripts. PHP 5.3 and later include the phar extension, which adds native support for reading and manipulating phar files.

The phar format was originally developed as part of the PEAR library PHP_Archive, first released in 2005. Later, a native PHP extension named "phar" was developed, which was first released on PECL in 2007, and is included with PHP 5.3 and later. The phar extension has effectively superseded the PHP_Archive library, which has not been updated since 2010. The phar extension is also no longer released independently on PECL; it is now developed and released as part of PHP itself.

Because of current limitations in Kaitai Struct (seekaitai-io/kaitai_struct#158 and kaitai-io/kaitai_struct#538), the executable PHP stub that precedes the rest of the archive is not handled by this spec. Before parsing a phar using this spec, the stub must be removed manually.

A phar's stub is terminated by the special token __HALT_COMPILER(); (which may be followed by at most one space, the PHP tag end ?>, and an optional line terminator). The stub termination sequence is immediately followed by the remaining parts of the phar format, as described in this spec.

The phar stub usually contains code that loads the phar and runs a contained PHP file, but this is not required. A minimal valid phar stub is <?php __HALT_COMPILER(); - such a stub makes it impossible to execute the phar directly, but still allows loading or manipulating it using the phar extension.

Note: The phar format does not specify any encoding for text fields (stub, alias name, and all file names), so these fields may contain arbitrary binary data. The actual text encoding used in a specific phar file usually depends on the application that created the phar, and on the standard encoding of the system on which the phar was created.

Application

PHP

File extension

phar

KS implementation details

License: CC0-1.0
Minimal Kaitai Struct required: 0.9

References

This page hosts a formal specification of PHP phar archive (without stub) using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Block diagram

Format specification in Kaitai Struct YAML

meta:
  id: phar_without_stub
  title: PHP phar archive (without stub)
  application: PHP
  file-extension: phar
  xref:
    wikidata: Q1269709
  license: CC0-1.0
  ks-version: 0.9
  imports:
    - /serialization/php_serialized_value
  endian: le
doc: |
  A phar (PHP archive) file. The phar format is a custom archive format
  from the PHP ecosystem that is used to package a complete PHP library
  or application into a single self-contained archive.
  All phar archives start with an executable PHP stub, which can be used to
  allow executing or including phar files as if they were regular PHP scripts.
  PHP 5.3 and later include the phar extension, which adds native support for
  reading and manipulating phar files.
  
  The phar format was originally developed as part of the PEAR library
  PHP_Archive, first released in 2005. Later, a native PHP extension
  named "phar" was developed, which was first released on PECL in 2007,
  and is included with PHP 5.3 and later. The phar extension has effectively
  superseded the PHP_Archive library, which has not been updated since 2010.
  The phar extension is also no longer released independently on PECL;
  it is now developed and released as part of PHP itself.
  
  Because of current limitations in Kaitai Struct
  (seekaitai-io/kaitai_struct#158 and kaitai-io/kaitai_struct#538),
  the executable PHP stub that precedes the rest of the archive is not handled
  by this spec. Before parsing a phar using this spec, the stub must be
  removed manually.
  
  A phar's stub is terminated by the special token `__HALT_COMPILER();`
  (which may be followed by at most one space, the PHP tag end `?>`,
  and an optional line terminator). The stub termination sequence is
  immediately followed by the remaining parts of the phar format,
  as described in this spec.
  
  The phar stub usually contains code that loads the phar and runs
  a contained PHP file, but this is not required. A minimal valid phar stub
  is `