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.