Distribute as a Single Executable Binary

Introduction#

A PHAR archive still requires PHP to be installed on the machine that runs it. When you are distributing your application to people who may not have PHP — or may have the wrong version — you may instead bundle your application into a standalone executable binary with the PHP runtime embedded in it.

Laravel Zero uses PHPacker to create these self-contained binaries from your PHAR archives.

Installation#

First, add PHPacker to your project as a development dependency:

composer require phpacker/phpacker --dev

Building the Binary#

PHPacker works from a PHAR archive, so you should build one first. The build name must have the .phar extension:

php application app:build movie-cli.phar

Once the archive is ready in your builds directory, create binaries for every supported platform:

./vendor/bin/phpacker build --src=./builds/movie-cli.phar --php=8.4 all

This command builds binaries with PHP 8.4 embedded for:

• macOS — arm64 and x64
• Linux — arm64 and x64
• Windows — x64

The resulting binaries are placed in the ./builds/build directory, organized by platform. For platform-specific builds and additional configuration options, consult the PHPacker documentation.

Running the Binary#

The binary may be executed directly, with no other dependencies:

./builds/build/mac/mac-arm

Or, on Linux:

./builds/build/linux/linux-x64

Or, on Windows:

C:\application\path> builds\build\windows\windows-x64.exe

Considerations#

• Binaries are considerably larger than PHAR archives, since they embed the PHP runtime.
• Building requires network access, as the PHP binaries are downloaded during the build.
• Some PHP extensions may not be available in the embedded runtime. If your application depends on one, verify it is present before distributing.
• Everything that is true of a PHAR build is also true here: the environment is production, and the bundled filesystem is read-only. See what changes in a build.