D 2015-01-21T13:13:00.939
L phar
N text/x-markdown
P bb9d16fca975032823d02c12da00737cac10336f
U mario
W 5928
### <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.
* Builds a class map.
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> phaz.bz2 </td><td> Phar </td><td> gzip </td><td> bzip2 </td><td> (avoid!) </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>
* 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 [<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:
* `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 [<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.
### 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 0c2db60b9139136222d4b07aab0b28c3