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";

In the future, it will also be possible to exclude files matching specific
patterns.


## 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";

## 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.


### 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.