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

⌈⌋ ⎇ branch:  cross package maker


Update of "phar"

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: 400abac88529fc14d1dc8bde1ab6d110737fdca0
Page Name:phar
Date: 2015-01-16 02:05:10
Original User: mario
Mimetype:text/x-markdown
Parent: a55bf5d314bf2d78c10c266e99785ab2be1453f6 (diff)
Next 1282b700e50eeee36955ce679414faf3c685f57c
Content
-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.