static-php-cli

static-php-cli is a powerful tool designed for building static, standalone PHP runtime with popular extensions.

Features

• 🐘 Support multiple PHP versions - PHP 8.1, 8.2, 8.3, 8.4, 8.5
• 👜 Build single-file PHP executable with zero dependencies
• 🍔Build phpmicro self-extracting executables (combines PHP binary and source code into one file)
• 💊 Automatic build environment checker with auto-fix capabilities
• ⚡ Linux, macOS, FreeBSD, Windows support
• 🔧 Configurable source code patching
• 📚 Intelligent dependency management
• 📦 Self-contained spc executable (built with box)
• 🔥 Support 75+ popular extensions
• 💾 UPX compression support (reduces binary size by 30-50%)

Single-file standalone php-cli:

Combine PHP code with PHP interpreter using phpmicro:

Quickstart

1. Download spc binary

# For Linux x86_64
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
# For Linux aarch64
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
# macOS x86_64 (Intel)
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
# macOS aarch64 (Apple)
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
# Windows (x86_64, win10 build 17063 or later, please install VS2022 first)
curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe

For macOS and Linux, add execute permission first:

chmod +x ./spc

2. Build Static PHP

First, create a craft.yml file and specify which extensions you want to include from extension list or command generator:

# PHP version support: 8.1, 8.2, 8.3, 8.4, 8.5
php-version: 8.4
# Put your extension list here
extensions: "apcu,bcmath,calendar,ctype,curl,dba,dom,exif,fileinfo,filter,gd,iconv,mbregex,mbstring,mysqli,mysqlnd,opcache,openssl,pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,readline,redis,session,simplexml,sockets,sodium,sqlite3,tokenizer,xml,xmlreader,xmlwriter,xsl,zip,zlib"
sapi:
  - cli
  - micro
  - fpm
download-options:
  prefer-pre-built: true

Run command:

./spc craft

# Output full console log
./spc craft --debug

3. Static PHP usage

Now you can copy binaries built by static-php-cli to another machine and run with no dependencies:

# php-cli
buildroot/bin/php -v

# phpmicro
echo '<?php echo "Hello world!\n";' > a.php
./spc micro:combine a.php -O my-app
./my-app

# php-fpm
buildroot/bin/php-fpm -v

Documentation

The current README contains basic usage. For all the features of static-php-cli, see https://static-php.dev .

Direct Download

If you don't want to build or want to test first, you can download example pre-compiled artifact from Actions, or from self-hosted server.

Below are several precompiled static-php binaries with different extension combinations, which can be downloaded directly according to your needs.

Combination	Extension Count	OS	Comment
common	30+	Linux, macOS	The binary size is about 7.5MB
bulk	50+	Linux, macOS	The binary size is about 25MB
gnu-bulk	50+	Linux, macOS	Using shared glibc
minimal	5	Linux, macOS	The binary size is about 3MB
spc-min	5	Windows	The binary size is about 3MB
spc-max	40+	Windows	The binary size is about 8.5MB

Linux and Windows supports UPX compression for binaries, which can reduce the size of the binary by 30% to 50%. macOS does not support UPX compression, so the size of the pre-built binaries for mac is larger.

Build Online (using GitHub Actions)

When the above direct download binaries cannot meet your needs, you can use GitHub Action to easily build a statically compiled PHP, and at the same time define the extensions to be compiled by yourself.

1. Fork me.
2. Go to the Actions of the project and select CI.
3. Select Run workflow, fill in the PHP version you want to compile, the target type, and the list of extensions. (extensions comma separated, e.g. bcmath,curl,mbstring)
4. After waiting for about a period of time, enter the corresponding task and get Artifacts.

If you enable debug, all logs will be output at build time, including compiled logs, for troubleshooting.

Contribution

If the extension you need is missing, you can create an issue. If you are familiar with this project, you are also welcome to initiate a pull request.

If you want to contribute documentation, please just edit in docs/.

Now there is a static-php organization, which is used to store the repo related to the project.

Sponsor this project

You can sponsor me or my project from GitHub Sponsor. A portion of your donation will be used to maintain the static-php.dev server.

Special thanks to sponsors below:

Open-Source License

This project itself is based on MIT License, some newly added extensions and dependencies may originate from the the other projects, and the headers of these code files will also be given additional instructions LICENSE and AUTHOR.

These are similar projects:

• dixyes/lwmbs
• swoole/swoole-cli

The project uses some code from dixyes/lwmbs, such as windows static build target and libiconv support. lwmbs is licensed under the Mulan PSL 2.

Due to the special nature of this project, many other open source projects such as curl and protobuf will be used during the project compilation process, and they all have their own open source licenses.

Please use the bin/spc dump-license command to export the open source licenses used in the project after compilation, and comply with the corresponding project's LICENSE.