D 2015-01-16T02:05:10.421
L phar
N text/x-markdown
P a55bf5d314bf2d78c10c266e99785ab2be1453f6
U mario
W 5541
##### <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`
* `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 [<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. 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 <kbd>--attr</kbd> flag be used to add further fields (just strings, not arrays).
* 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 is useful for `--version` refinement.
### 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'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.
Z c7ae7556a98be240e059fb6ea991009a