php-makephar/README.md

MakePhar mk2
============

This is a rewrite of my old MakePhar utility, with cleaner code and added
portability. Besides being able to pack executables, this version can also
create libraries, such as portable plugins.


## Executables

If your project is using composer, and your main stub is located in the
source directory as specified in the composer.json, you can create a
manifest easily:

    $ makephar -n > makephar.sdl

Now, just update `makephar.sdl` to make sure the **stub** points to the
executable stub. Here is an example:

    phar "my-project.phar" {
      include {
        dir "src";
        dir "vendor";
      }
      stub "src/boot.php";
    }

To build this into a .phar archive, just call `makephar`:

    $ makephar

The output file `my-project.phar` should be created and be executable out of
the box.


## Libraries

Libraries work like executables, with the difference that they **require** a
composer project, or rather it requires a file named `vendor/autoload.php` in
the package.

To load your own bootstrap using composer, add them as file autoloaders:

    ...
    "autoload": {
      "psr-4": ...
      "files": [ "src/my-library-stub.php" ]
    }

Next, make sure you have a line in your `makephar.sdl` that reads:

    library true;

You should now be able to create a library phar by invoking `makephar`.

It is recommended that you add a check in your main stub to make sure that
the plugin or library has what is needed, such as checking a define or making
sure that a method or class already exists.


## Sources and Stubs

Source files are added in the `include` block as either a `file` or a `dir`.

    include {
      dir "directory-to-add";
      file "file-to-add.php";
    }

The stub is what is invoked when the executable is called, and it is defined in
the `phar` block, outside of the `include` block that is. The stub must however
be added through one of the rules in the `include` block.

    stub "src/stub.php";

You can follow the same approach when excluding files with the `exclude` block:

    exclude {
      dir ".git";
      file "DONT-INCLUDE-ME-IN-PHAR";
    }

The `dir` rules match against `*/<dirname>/*` while the `file` rule will match
against `*/<filename>`.

## Metadata

As PHAR archives support metadata, you can insert your own custom data using
the `metadata` block:

    library; // build a library (plugin)
    metadata {
      plugin_type "myapp.plugin";
      plugin_name "myapp.plugin.awesomeplugin";
      plugin_version "1.0.0";
    }

You can also map props to metadata. The advantage to this is that you can scan
the metadata before including the .phar letting you pick the most recent versions
etc.

    metadata {
      plugin_version prop="MYPLUGIN_VERSION";
    }

The order is important! Make sure you have defined the props you want to reference
before referencing them!

## Props

The project properties are a set of key=value items that are defined in the stub,
and thus made available to the code in the phar. it can be read from a file, or
generated by a script or executable. Comments should be prefixed with a hash sign
(`#`):

    # Comment line
    MYAPP_VERSION=1.0
    MYAPP_VARIANT=lite
    MYAPP_BUILDDATE=2017-03-14

To add props from a file:

    props "app.props";

To evaluate props when building the archive:

    props exec="generate-props.php";

The props are defined, and the keys are cast to upper case. Be careful if you
attempt to redefine any of these values from within your project as this will
fail. What you should do is something like:

    if (!defined('MYAPP_VERSION')) define('MYAPP_VERSION','dev');
    echo "This is MyApp ".MYAPP_VERSION."\n";

This makes sure that you don't try to set an existing define, and also that the
defines generated from props by MakePhar is also available when running the app
from source.


## Options and Tweaks

Boolean options (such as `verbatim` and `library`) will have their value default
to *true* if omitted. So these two lines will have the same effect:

    verbatim;
    verbatim true;

The following options are currently available. Read the notes before using them
tho!


### library (bool)

If set, the created phar will be a pure library, intended to be *included* into
other PHP projects. The library mode currently depends on composer, and it will
use `vendor/autoload.php` as the main stub. As such, you need to add any code
you want executed on load to `autoload/files` in your composer.json.


### verbatim (bool)

If set, no minification will take place. Generally, the minification should not
cause any problems but lead to a file that can be up to half a megabyte smaller
as whitespace and comments are removed.

It is also possible to mark specific directories or files as verbatim on the
`dir` and `file` tags in an `include` block.

### compress (bool)

Compress is a legacy option from MakePhar *mk1*, and is not yet implemented. It
will work in a similar fashion to how it did before: The resulting .phar will
be compressed, and the output will have a stub prepended to extract the .phar
into a temporary directory before running. But right now **it does nothing**.


## Pro Tips

* You can have multiple `phar` blocks in your `makephar.conf`. This lets
  you build a main executable, libraries etc in one go. You currently can't
  pick the rule to build tho, but rather all defined phars will be built.
* MakePhar will minify your files using `php_strip_whitespace()` before adding
  them to the archive. This shouldn't be an issue, but if your code depends on
  a specific character index in a specific php file, you might want to specify
  the `verbatim` option.
* You can specify multiple `props` blocks, f.ex. one containing static values
  and another one generate f.ex. build date or git revision.