PHP packaging

Packaging PHP scripts into PHAR files is a practice that enables the bundling of entire PHP applications into single, standalone files. The acronym PHAR stands for PHP Archive, and it aims to do for PHP what JAR (Java Archive) does for Java. These single files can encapsulate all the resources a PHP project might need, including libraries, images, and even data files, making it exceedingly straightforward to distribute and deploy them.

The PHAR format is particularly useful for PHP scripts and applications that are intended for distribution or deployment outside of a typical web server environment. For example, command-line tools, cron jobs, or daemonized PHP applications can benefit from being packaged as PHAR files. The practice is common in projects that offer CLI utilities or frameworks, as it simplifies the installation process. Instead of having to deal with a number of scripts, dependencies, and other files, the end-user can simply download a single PHAR file and execute it.

Additionally, PHAR files can be executed directly by the PHP interpreter, which makes them platform-independent to a large extent. You can also apply various kinds of compression to reduce file size, making them easier to distribute.

One important point to note is that in order to run a PHAR file, you must have PHP installed on your system. The PHAR file is essentially a packaged PHP application, and it requires the PHP runtime for execution. This is similar to how you'd need the Java runtime to execute a JAR file. So while the PHAR file bundles all the application's PHP code and resources, the PHP interpreter is still required to actually run the application. This is an important consideration when distributing PHAR files, as your users will need to have PHP installed to use them.

Workflow

For building the PHAR file, a custom script build, specified in composer.json, is executed. This script leverages Box to compile the PHP code into a PHAR file.

The composer build command installs Box, validates its configuration, and compiles the PHAR file. The configuration for Box is provided in the configuration file, specifying what to include in the archive, where to output it, and what compression to use.

The release-php job of Release GitHub action is triggered on pushes to the main branch and runs composer build command. It then passes the built PHAR file to the softprops/action-gh-release action, which attaches the PHAR file to the most recent release as a release asset.

An example of the release asset generated by this action can be found on the Releases page of this repository under Assets.

Box

The Box project is a tool for building and managing PHAR (PHP Archive) files. PHAR files bundle together PHP code, making it easier to distribute and execute. It's especially useful for command-line PHP scripts and applications that need to be easily installed without dealing with Composer packages or PEAR installations. Box offers a host of configurations to customize the building of your PHAR files, allowing you to specify directories, files, compression settings, and more.

{
    "output": ".build/php-command.phar",
    "compression": "GZ",
    "finder": [
        {
            "in": "./",
            "exclude": [
                "php-script",
                "tests"
            ]
        }
    ]
}

In the provided Box configuration, several settings are specified:

• Output: Defines where the compiled PHAR file will be stored. In this case, it's set to .build/php-command.phar. Whenever Box compiles the PHAR, this is where the file will be output.

• Compression: Specifies the compression algorithm to be used for the PHAR. The value GZ indicates Gzip compression. This reduces the PHAR file size, making it faster to download and distribute.

• Finder: A powerful feature that allows you to include or exclude specific files and directories in the PHAR. In your setup, the finder is set to include all files in the current directory ("./"), excluding the tests directories.

These settings can be tailored to fit the needs of your project. By understanding and properly configuring these parameters, you can control exactly how your PHP code is packaged, making it convenient to distribute and execute.

Read more about packaging using Box on the Box page.