D 2015-01-17T19:57:58.915
L phar
N text/x-markdown
P 1282b700e50eeee36955ce679414faf3c685f57c
U mario
W 5731
##### <kbd>-t `phar`</kbd> 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 <kbd>-s src</kbd>, <kbd>-s composer</kbd> source plugins, and <kbd>-u lcase</kbd>, <kbd>-u composer</kbd> update filters.
### Recognized file extensions or `--phar-format` specifiers
<table>
<tr>
<th> Extension / Specifier </th><th> Archive Format </th><th> Compression Per File </th><th> Envelope Compression </th><th> Use Cases </th>
</tr>
<tr>
<td> phar </td><td> Phar </td><td> - </td><td> - </td><td> </td>
</tr>
<tr>
<td> phar.gz </td><td> Phar </td><td> gzip </td><td> - </td><td> general </td>
</tr>
<tr>
<td> phar·bz2 </td><td> Phar </td><td> bzip2 </td><td> - </td><td> </td>
</tr>
<tr>
<td> PHAZ </td><td> Phar </td><td> - </td><td> gzip </td><td> </td>
</tr>
<tr>
<td> - </td><td> Phar </td><td> gzip </td><td> gzip </td><td> (eschew) </td>
</tr>
<tr>
<td> zip </td><td> Zip </td><td> - </td><td> - </td><td> </td>
</tr>
<tr>
<td> zip.gz </td><td> Zip </td><td> gzip </td><td> - </td><td> distribution </td>
</tr>
<tr>
<td> zip…bz2 </td><td> Zip </td><td> bzip2 </td><td> - </td><td> </td>
</tr>
<tr>
<td> tar </td><td> Pax </td><td> - </td><td> - </td><td> </td>
</tr>
<tr>
<td> tgz </td><td> Pax </td><td> - </td><td> gzip </td><td> </td>
</tr>
<tr>
<td> tar+bz2 </td><td> Pax </td><td> - </td><td> bzip2 </td><td> data bundles </td>
</tr>
</table>
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](http://php.net/phar.getmetadata) 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`<br>
* The [<kbd>-s src</kbd>](wiki/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`
* `doc`
* `pack` (file list / glob specifier)
* `config` (unparsed section)
Further fields can be present. Each `api:` can define specific attributes. And they can just be used for documentative purposes. While field names in the source comment are case-insensitive, they're always lowercased in the Phar meta array.
* When using the [<kbd>-s composer</kbd>](wiki/source_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 <kbd>--attr</kbd> flag. (Just strings though, not array structures currently.)
* The [<kbd>-u composer</kbd>](wiki/update+filters#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 [<kbd>-u lcase=php</kbd>](wiki/update+filters#lcase) all included filenames can be converted to lowercase beforehand.
* A <kbd>-u classmap</kbd> plugin is *planned* to craft a class→script map for inclusion as Phar meta data.
### Prior notes
* fpm issue: [#812](https://github.com/jordansissel/fpm/issues/812)
* orig gist: [fpm…package…**phar.rb**](https://gist.github.com/prof-milki/1c1930b2e8cba5753902)
* 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.
Z 24495823ae668b3311b4b479ce9264e2