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: aa55a304e5c9f5c03153eb2639284d5807f7d9a9
Page Name:phar
Date: 2015-01-17 20:02:35
Original User: mario
Mimetype:text/x-markdown
Parent: 0e519e6e5561735edfe28bb0430b98ac34f2b3cb (diff)
Next bb9d16fca975032823d02c12da00737cac10336f
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
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
  • 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.

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