144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
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.
|