README.md

IMPHP - Make .phar

---

This is a build script that compiles a PHP project into a single phar archive.

Usage

./make-phar.php [options]

Options

Option	Default	Description
--incl-file		Include an additional file from outside the --in directory
--incl-key		Include an additional key from the composer.json file into the metadata
--stub	stub.php	Include a stub file
--metadata		Include additional metadata from a json string
--metafile		Include additional metadata from a file
--vendor		Include a vendor directory with project dependencies
--in	src/	Define the src directory to use
--out	releases/	Define the dest directory to use
--version		Define the project version
--name		Define the project name
--composer	composer.json	Use a composer file containing version and name
--debug		Enable debug e.g. don't strip PHP files

Always run this script from inside the project root directory. This script uses CWD and not the script location as base directory for the build process.

Example 1

$ ls -p
src/  vendor/  stub.php

$ make-phar --name imphp/test --verson 0.0.1 --vendor vendor/

This will create the archive releases/imphp-test.phar.

Note that src/ is automatically included as it's the default source directory in the build script.

Example 2

$ ls -p
src/  vendor/  stub.php  composer.json

$ cat composer.json
{
    "name": "imphp/test",
    "version": "0.0.1",
}

$ make-phar --vendor vendor/

Metadata

By default the build script creates 3 metadata variables. These are added as metadata to the archive itself but they are also added as json to a file named metadata within the archive, making them accessable to the code within.

You can add additional data to the metadata file, though not to the archive metadata. One way is to simply include a complete json metadata file to the build. This will include everything from that file. The other way is to add a json string to the build line and the 3'rd way is to extract additional information from the composer.json file and have that be included.

Example: Include metadata file

$ ls -p
src/  vendor/  stub.php  metadata.json

$ cat metadata.json
{
    "key": "val"
}

$ make-phar --name imphp/test --verson 0.0.1 --vendor vendor/ --metafile metadata.json

Example: Include metadata string

$ ls -p
src/  vendor/  stub.php

$ make-phar --name imphp/test --verson 0.0.1 --vendor vendor/ --metadata '{"key": "val"}'

Example: Include metadata from composer.json

$ ls -p
src/  vendor/  stub.php  composer.json

$ cat composer.json
{
    "name": "imphp/test",
    "version": "0.0.1",

    "authors": [
        {
            "email": "[email protected]"
        }
    ]
}

$ make-phar --vendor vendor/ --incl-key authors.0.email:auth_email

This part needs a bit of explaining. We do not want to include the entire authors array in this example. All we want is the first email there is, so we instruct the script to get email from authors.0. Also in this example we want to rename the key from email to auth_email, so we write email:auth_email instead of just email.

Example: Using the metadata from inside the archive

$ ls -p
src/  vendor/  stub.php  composer.json

$ cat stub.php
<?php
json = json_decode(file_get_contents("metadata"));
print_r(json);

When we run the archive with this stub.php, we get the following output, based on the previous example.

Array
(
    [type] => release
    [name] => imphp/test
    [version] => 0.0.1
    [auth_email] => [email protected]
)

Debug

You can specify the --debug option to create a debug version. The difference is that in normal builds, the build script will strip all whitespace and comments from any PHP file. This however is not great for debugging as things like line information becomes useless.

ls-phar.php

There is a small script included called ls-phar.php. It's purpose is simply to dump different information about an archive. It can list all the files in the archive, any metadata and dump content from files inside the archive.