README

static-php-cli 是一个强大的工具，旨在构建包含流行扩展的静态、独立的PHP运行时。

static-php-cli 构建的静态PHP支持 cli、fpm、embed 和 micro SAPI。

static-php-cli 还可以将PHP项目与PHP解释器打包成一个单独的可执行文件。

功能

static-php-cli (你可以称之为 spc) 具有很多功能

• 👜 构建单文件php可执行文件，无任何依赖
• 🍔 构建 phpmicro 自提取可执行文件（将php二进制文件和php源代码合并到一个文件中）
• 💊 自动构建环境检查器（Doctor模块）
• ⚡ 支持 Linux、macOS、FreeBSD、Windows
• 🔧 可配置的源代码补丁
• 📚 构建依赖管理
• 📦 提供 spc 独立的可执行文件（由 spc 和 box 构建）
• 🔥 支持许多流行 扩展
• 💾 UPX 集成（显著减小二进制文件大小）

单文件独立php-cli

使用 phpmicro 将 PHP 代码与 PHP 解释器结合

文档

当前的 README 包含基本用法。有关 static-php-cli 的所有功能，请参阅 https://static-php.dev 。

直接下载

如果您不想构建或想先测试，可以下载来自 Actions 或自托管服务器的示例预编译工件。

以下是几个预编译的静态 php 二进制文件，具有不同的扩展组合，您可以根据需要直接下载。

Linux 和 Windows 支持UPX压缩二进制文件，可以减少二进制文件大小的30%到50%。macOS 不支持UPX压缩，因此mac预构建的二进制文件大小更大。

构建

编译要求

可以说我编写了一个用PHP编写的PHP构建器，很有趣。但 static-php-cli 运行时仅需要PHP 8.1以上环境以及以下提到的扩展。

• PHP >= 8.1（这是 spc 本身所需的版本，而不是构建版本）
• 扩展：mbstring,tokenizer,phar
• 支持安装了 curl 和 git 的操作系统

以下是支持的操作系统和架构，其中 代表支持GitHub Action构建，💻 代表支持本地手动构建，空白代表目前不支持。

当前支持的编译PHP版本

⚠️ 由 static-php-cli 作者支持但不维护

✔️ 支持

❌ 不支持

支持的扩展

请根据以下扩展列表首先选择您想要编译的扩展。

• 支持扩展列表
• 命令生成器

如果您需要的扩展缺失，可以提交一个问题。

以下是当前计划的支持扩展路线图：#152。

在线构建（使用GitHub Actions）

使用GitHub Action轻松构建静态编译的PHP，同时自行定义要编译的扩展。

1. 分支我。
2. 进入项目的“操作”，选择CI。
3. 选择运行工作流程，填写要编译的PHP版本、目标类型和扩展列表。（扩展用逗号分隔，例如bcmath,curl,mbstring）
4. 等待一段时间后，进入相应的任务，获取工件。

如果您启用了debug，所有日志将在构建时输出，包括编译日志，以便进行故障排除。

本地构建（使用SPC二进制文件，推荐）

该项目提供了static-php-cli的二进制文件：spc。您可以使用spc二进制文件而不是安装任何像golang app这样的运行时。目前，spc二进制文件支持的平台是Linux和macOS。

使用以下命令从自托管的夜间构建下载

# Download from self-hosted nightly builds (sync with main branch)
# 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)
curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe

# Add execute perm (Linux and macOS only)
chmod +x ./spc

# Run (Linux and macOS)
./spc --version
# Run (Windows powershell)
.\spc.exe --version

自托管的spc由GitHub Actions构建，您也可以从操作工件这里下载。

本地构建（使用git源代码）

如果您需要修改static-php-cli的源代码，或者在spc二进制文件构建时遇到问题，您可以使用git源代码下载static-php-cli。

# just clone me!
git clone https://github.com/crazywhalecc/static-php-cli.git

如果您尚未在系统上安装php，我们建议您使用内置的setup-runtime自动安装PHP和Composer。

cd static-php-cli
chmod +x bin/setup-runtime
# it will download static php (from self-hosted server) and composer (from getcomposer)
bin/setup-runtime
# initialize composer deps
bin/composer install
# chmod
chmod +x bin/spc
bin/spc --version

开始构建PHP

构建具有某些扩展的php的基本用法

如果您正在使用打包的独立spc二进制文件，您需要在以下命令中将bin/spc替换为./spc或.\spc.exe。

# Check system tool dependencies, auto-fix them if possible
./bin/spc doctor --auto-fix

# fetch all libraries
./bin/spc download --all
# only fetch necessary sources by needed extensions (recommended)
./bin/spc download --for-extensions="openssl,pcntl,mbstring,pdo_sqlite"
# download pre-built libraries first (save time for compiling dependencies)
./bin/spc download --for-extensions="openssl,curl,mbstring,mbregex" --prefer-pre-built
# download different PHP version (--with-php=x.y or --with-php=x.y.z, recommend 8.1 ~ 8.3)
./bin/spc download --for-extensions="openssl,curl,mbstring" --with-php=8.1

# with bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl extension, build both CLI and phpmicro SAPI
./bin/spc build "bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl" --build-cli --build-micro
# build thread-safe (ZTS) version (--enable-zts)
./bin/spc build "curl,phar" --enable-zts --build-cli
# build, pack executable with UPX (linux and windows only) (reduce binary size for 30~50%)
./bin/spc build "curl,phar" --enable-zts --build-cli --with-upx-pack

现在我们支持cli、micro、fpm和embed SAPI。您可以使用以下参数之一或多个来指定编译的SAPI

• --build-cli：构建静态cli可执行文件
• --build-micro：构建静态phpmicro自提取可执行文件
• --build-fpm：构建静态fpm二进制文件
• --build-embed：构建嵌入（libphp）
• --build-all：构建所有

如果出现问题，使用--debug选项显示完整的终端输出

./bin/spc build "openssl,pcntl,mbstring" --debug --build-all
./bin/spc download --all --debug

不同SAPI的用法

使用cli

php-cli是一个单静态二进制文件，您可以使用它像系统上安装的正常php一样使用。

当使用参数--build-cli或--build-all时，最终的编译结果将输出一个名为./php的二进制文件，可以直接分发和使用。此文件将位于目录buildroot/bin/中，将其复制出来即可使用。

cd buildroot/bin/
./php -v                # check version
./php -m                # check extensions
./php your_code.php     # run your php code
./php your_project.phar # run your phar (project archive)

使用micro

phpmicro是一个SelF-extracted eXecutable SAPI模块，由phpmicro项目提供。但此项目使用的是phpmicro的分支，因为我们需要向其中添加一些功能。它可以将与PHP运行时和您的源代码一起放置。

当使用参数--build-all或--build-micro时，最终的编译结果将输出一个名为./micro.sfx的文件，需要与您的PHP源代码（如code.php）一起使用。此文件将位于路径buildroot/bin/micro.sfx中，只需将其复制出来即可使用。

准备好您的项目源代码，可以是单个PHP文件或Phar文件，以便使用。

echo "<?php echo 'Hello world' . PHP_EOL;" > code.php
cat micro.sfx code.php > single-app && chmod +x single-app
./single-app

如果您打包了一个PHAR文件，只需将code.php替换为PHAR文件的路径。您可以使用box-project/box将您的CLI项目打包为Phar，然后与phpmicro结合以生成独立的可执行二进制文件。

# Use the micro.sfx generated by static-php-cli to combine,
bin/spc micro:combine my-app.phar
# or you can directly use the cat command to combine them.
cat buildroot/bin/micro.sfx my-app.phar > my-app && chmod +x my-app

# Use micro:combine combination to inject INI options into the binary.
bin/spc micro:combine my-app.phar -I "memory_limit=4G" -I "disable_functions=system" --output my-app-2

在某些情况下，PHAR文件可能在微型环境中无法运行。总体来说，微型环境尚未准备好用于生产。

使用fpm

当使用参数--build-all或--build-fpm时，最终的编译结果将输出一个名为./php-fpm的文件，该文件将位于路径buildroot/bin/下，只需将其复制出来即可使用。

在常见的Linux发行版和macOS系统上，安装php-fpm后，包管理器将自动生成一个默认的fpm配置文件。因为php-fpm必须在运行前指定配置文件，所以本项目编译的php-fpm不会包含任何配置文件，因此您需要自己编写php-fpm.conf和pool.conf配置文件。

指定php-fpm.conf可以使用命令参数-y，例如：./php-fpm -y php-fpm.conf。

使用内嵌

当使用项目参数--build-embed或--build-all时，最终的编译结果将输出一个libphp.a、php-config和一系列头文件，存储在buildroot/下。您可以将它们引入到其他项目中。

如果您熟悉内嵌SAPI，您应该知道如何使用它。在编译过程中，您可能需要引入其他库，您可以使用buildroot/bin/php-config来获取编译时的配置。

有关如何使用此功能的进阶示例，请参阅如何使用它构建FrankenPHP的静态版本。

贡献

如果您需要的扩展不存在，可以创建一个问题。如果您熟悉此项目，也欢迎发起一个pull request。

如果您想贡献文档，请直接编辑docs/。

现在有一个static-php组织，用于存储与项目相关的仓库。

赞助此项目

您可以在此页面上赞助我的项目。您捐赠的一部分将用于维护static-php.dev服务器。

开源许可

本项目本身基于MIT许可，一些新添加的扩展和依赖可能来自其他项目，这些代码文件的头部还将给出额外的LICENSE和AUTHOR说明。

这些是类似的项目

• dixyes/lwmbs
• swoole/swoole-cli

本项目使用了一些来自dixyes/lwmbs的代码，例如Windows静态构建目标和libiconv支持。lwmbs遵循Mulan PSL 2许可。

由于本项目的特殊性质，在项目编译过程中将使用许多其他开源项目，如curl和protobuf，它们各自都有自己的开源许可。

请使用bin/spc dump-license命令在编译后导出项目中使用的开源许可，并遵守相应项目的LICENSE。