-t phar packaging

Phars are PHPs file bundles. They are available in a few format and compression flavours (binary, zip, tar). And this target plugin basically works like the zip module.

• Packs the staging dir with relative directory structures.
• 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. Each is a simple identifer→filename association, with keys being lowercased (for PHP compliance).

• 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.json 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 frowned on 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.