Skip to content

Compiling your application into a static binary

Packing your Castor application as a phar can be a good way to easily share and use it in various environments.

However, you need to ensure that PHP is installed and configured correctly in all the environments where you want to use your Castor app. This can be a hassle, especially if you don't have control over the environments.

To make things simpler, Castor's compile command can help by creating a customizable PHP binary with a phar, making one executable file that can be used in any setting.

Just pass your repacked Castor app phar as an argument of this command.

Pre-requisites

Compiling your Castor application into a static binary requires you to have a phar version of it. Follow the repack documentation to produce a phar containing your Castor application.

Running the Compile Command

To compile your Castor application, navigate to your project directory and run:

vendor/bin/castor compile my-custom-castor-app.phar

Warning

Compiling is not supported yet on Windows.

Usage

castor:compile [--spc-version SPC-VERSION] [--binary-path BINARY-PATH] [--os OS] [--arch ARCH] [--php-version PHP-VERSION] [--php-extensions PHP-EXTENSIONS] [-N|--php-ini-file PHP-INI-FILE] [--php-rebuild] [--] <phar-path>

Arguments

phar-path

Path to phar to compile along PHP

  • Is required: yes
  • Is array: no
  • Default: NULL

Options

--spc-version

Version of the static-php-cli (spc) tool to use

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: '2.7.5'

--binary-path

Path to compiled static binary. It can be the parent dirname too

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: '/home/runner/work/castor/castor'

--os

Target OS for PHP compilation

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: 'linux'

--arch

Target architecture for PHP compilation

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: 'x86_64'

--php-version

PHP version in major.minor format

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: '8.4'

--php-extensions

PHP extensions required, in a comma-separated format. Defaults are the minimum required to run a basic "Hello World" task in Castor.

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: 'mbstring,phar,posix,tokenizer,curl,filter,openssl'

--php-ini-file|-N

ini file to inject into micro.sfx when combining

  • Accept value: yes
  • Is value required: yes
  • Is multiple: no
  • Is negatable: no
  • Default: NULL

--php-rebuild

Ignore cache and force PHP build compilation.

  • Accept value: no
  • Is value required: no
  • Is multiple: no
  • Is negatable: no
  • Default: false

Behavior

The compile command performs several steps:

  1. Downloads or uses an existing Static PHP CLI tool to compile PHP and the phar into a binary.
  2. If required, it automatically installs dependencies and compiles PHP with the specified extensions.
  3. Combines the compiled PHP and your phar file into a single executable.

Post-Compilation

Once the compilation is finished, your Castor application is transformed into a static binary named castor by default (you can use the --binary-path option to change it).

This binary is now ready to be distributed and run in environments that do not have PHP installed.

You can simply run it like any other executable:

./castor