-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.

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
-	Phar	gzip	gzip	(eschew)
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
    

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

  • api
  • type
  • comment (includes the remainder of the first comment block, basic documentation / long description text)
  • state
  • pack (file list / glob specifier)
  • config (unparsed section)

  Further field names can be present, depending on application api: of course, or just for plain documentative purposes.

• 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. And because phars aren't preferred in the packagist/composer ecosystem anyway, and due to their constrained set of allowed fields, composer:{} is only a substructure in the meta array. (Thus it indirectly has to return the extra: stashing favour here.)

• Likewise can the fpm --attr flag be used to add further fields (just strings, not arrays).

• 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 is useful for --version refinement.

Update filters

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

• A -u classmap plugin is planned to craft a class→script map for inclusion as Phar meta data.

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's not infeasible to reimplement the phar binary format, or its zip/tar variant specifica. Generating them per fpm is a convenienence over using the command-line phar tool.