D 2015-01-28T12:42:36.312
L phar
N text/x-markdown
P 98a8ecfd314a3daf755f6ffd4f61cc01bd438758
U mario
W 6381
### <kbd>-t `phar`</kbd> packaging
Phars are PHPs file bundles. They are available in a few format and compression flavours (binary, zip, tar).
* Packs the staging dir with relative directory structures (like the `zip` module).
* 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><a href="wiki/src">-s src</a></kbd>, <kbd><a href="wiki/source_composer">-s composer</a></kbd> source plugins, and <kbd><a href="wiki/update+filters#lcase">-u lcase</a></kbd>, <kbd><a href="wiki/update+filters#composer">-u composer</a></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><br>
* An identifier <kbd>map</kbd> is automatically included. It contains not just <kbd>class</kbd> but also <kbd>function</kbd> and <kbd>const</kbd> declarations.
* <kbd>map</kbd>
* <kbd>class</kbd>
* `vnd\dir\classname` **=>** `src/dir/Classname.php`
* `myiterator` **=>** `src/MyIterator.php`
* <kbd>function</kbd>
* <kbd>const</kbd>
Each is a simple identifer→filename association, with keys being lowercased (for PHP compliance). For libraries usually only the `class` list is populated.
* 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.lock` 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 disregarded 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 19c17f39b3f2316fdaf588eec35ae9af