Cross package maker. DEB/RPM generation or conversion. Derived from jordansissel/fpm.

⌈⌋ branch:  cross package maker


-t phar packaging

Phars are PHPs file bundles. They are available in a few format and compression flavours (binary, zip, tar).

  • Packs the staging dir with relative directory structures (like the zip module).
  • Somewhat consolidates the --phar-format selection.
  • Allows for stub inclusion.
  • And provides a --phar-sign option.
  • Populates the Phar meta data bag.
  • Builds a class map.

Interacts with the -s src, -s composer source plugins, and -u lcase, -u composer update filters.

Recognized file extensions or --phar-format specifiers

Extension / Specifier Archive Format Compression Per File Envelope Compression Use Cases
phar Phar - -
phar.gz Phar gzip - general
phar.bz2 Phar bzip2 -
phaz Phar - gzip
phaz.bz2 Phar gzip bzip2 (avoid!)
zip Zip - -
zip.gz Zip gzip - distribution
zip.bz2 Zip bzip2 -
tar Pax - -
tgz Pax - gzip
tar.bz2 Pax - bzip2 data bundles

The tar archives are POSIX tars, therefore mentioned as Pax here.

Format/file extension combos can be specified with dots, without, or arbitrary delimiters, and in any order. So these are all equivalent:

  • --phar-format .tar.gz
  • --phar-format tar+gz
  • --phar-format tar/gz
  • --phar-format targz

Per default uncompressed Phars are generated.

Meta data

Phars have a built-in meta data section, internally stored as PHP serialize() array.

  • Packaging options are used as defaults.
    The basic fields are:

    • id (package basename)
    • title
    • description
    • category
    • version
    • epoch (optional)
    • iteration (optional)
    • architecture (usually "all")
    • author
    • url
    • license

  • An identifier map is automatically included. It contains not just class but also function and const declarations.

    • map
      • class
        • vnd\dir\classname => src/dir/Classname.php
        • myiterator => src/MyIterator.php
      • function
      • const

    Each is a simple identifer→filename association, with keys being lowercased (for PHP compliance). For libraries usually only the class list is populated.

  • The -s src module can update or add extra fields. It reads out the comment meta block from the primary script.
    For instance:

    • main (lists the primary PHP script within the phar)
    • api
    • type
    • comment (includes the remainder of the first comment block, basic documentation / long description text)
    • state
    • doc
    • pack (unparsed file list / glob specifier)
    • config (unparsed section)

    Further fields can be present. Each api: may define custom attributes. Or can just be used for documentative purposes. Field names are always lowercased in the Phar meta array (they're case-insensitive in source comment headers).

  • When using the -s composer source plugin, the composer.lock bundle information will be stashed in a composer subarray.

    • composer{}
      • keywords[]
      • license[]
      • authors{}
      • support{}
      • require{}

    This is somewhat redundant, since phar://.../composer.json is available still. Because full phar support is disregarded in the packagist/composer ecosystem, and due to their constrained set of allowed fields, composer: is only a substructure in the meta array. (Thus indirectly returning the extra: stashing favour.)

  • Custom phar meta array fields can likewise be added using the fpm --attr flag. (Just strings though, not array structures currently.)

  • The -u composer update filter works the other way round. It generates a stub composer.json when there wasn't one in the input dir. It maps accumulated fpm package infos to populate or update fields in composer.json. Which for example is useful for refining the --version field.

Update filters

  • With -u lcase=php all included filenames can be converted to lowercase beforehand.

Prior notes

  • fpm issue: #812
  • orig gist: fpm…package…phar.rb
  • The implementation is basically just 70% php code. The Ruby section mostly just copies data over.
    It wouldn't be very practical to reimplement the phar binary format, or the zip/tar specifica.
    Generating Phars per fpm is a convenienence over using the command-line phar tool.