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