crazywhalecc/static-php-cli
1
0
Fork 0
mirror of https://github.com/crazywhalecc/static-php-cli.git synced 2026-07-08 09:25:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge docs into static-php-cli repo (#492)

Browse Source 
* Move docs to here

* Move docs to here

* Modify old docs links
This commit is contained in:
Jerry Ma
2024-07-01 10:29:31 +08:00
committed by GitHub
parent eb00e0012f
commit b31539f0f4
51 changed files with 5172 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
docs/zh/guide/action-build.md Normal file
View File

@@ -0,0 +1,25 @@
# Action 构建
Action 构建指的是直接使用 GitHub Action 进行编译。
如果你不想自行编译，可以从本项目现有的 Action 下载 Artifact，也可以从自托管的服务器下载：[进入](https://dl.static-php.dev/static-php-cli/common/)
> 自托管的二进制也是由 Action 构建而来，[项目仓库地址](https://github.com/static-php/static-php-cli-hosted)。
## 构建方法
使用 GitHub Action 可以方便地构建一个静态编译的 PHP 和 phpmicro，同时可以自行定义要编译的扩展。
1. Fork 本项目。
2. 进入项目的 Actions，选择 CI 开头的 Workflow（根据你需要的操作系统选择）。
3. 选择 `Run workflow`，填入你要编译的 PHP 版本、目标类型、扩展列表。（扩展列表使用英文逗号分割，例如 `bcmath,curl,mbstring`）
4. 等待大约一段时间后，进入对应的任务中，获取 `Artifacts`。
如果你选择了 `debug`，则会在构建时输出所有日志，包括编译的日志，以供排查错误。
> 如果你需要在其他环境构建，可以使用 [手动构建](./manual-build)。
## 扩展选择
你可以到 [扩展列表](./extensions) 中查看目前你需要的扩展是否均支持，
然后到 [在线命令生成](./cli-generator) 中选择你需要编译的扩展，复制扩展字符串到 Action 的 `extensions` 中，编译即可。

203
docs/zh/guide/build-on-windows.md Normal file
View File

@@ -0,0 +1,203 @@
# 在 Windows 上构建
因为 Windows 系统是 NT 内核，与类 Unix 的操作系统使用的编译工具及操作系统接口几乎完全不同，所以在 Windows 上的构建流程会与 Unix 系统有些许不同。
## GitHub Actions 构建
现在已支持从 Actions 构建 Windows 版本的 static-php 了。
和 Linux、macOS 一样，你需要先 Fork static-php-cli 仓库到你的 GitHub 账户中，然后你可以进入 [扩展列表](./extensions) 选择要编译的扩展，然后进入自己仓库的 `CI on Windows` 选择 PHP 版本、填入扩展列表（逗号分割），点击 Run 即可。
如果你要在本地开发或构建，请继续向下阅读。
## 环境准备
在 Windows 上构建静态 PHP 所需要的工具与 PHP 官方的 Windows 构建工具是相同的。你可以阅读 [官方文档](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2)。
总结下来，你需要以下环境及工具：
- Windows 10（需要 build 17063 或以后的更新）
- Visual Studio 2019/2022（推荐 2022）
- Visual Studio 的 C++ 桌面开发
- Git for Windows
- static-php-cli 仓库
- PHP 和 Composer（static-php-cli 需要它们，可使用 `bin/setup-runtime` 自动安装）
- [php-sdk-binary-tools](https://github.com/php/php-sdk-binary-tools)（可使用 doctor 自动安装）
- strawberry-perl（可使用 doctor 自动安装）
- nasm（可使用 doctor 自动安装）
::: tip
static-php-cli 在 Windows 上的构建指的是使用 MSVC 构建 PHP，不基于 MinGW、Cygwin、WSL 等环境。
如果你更倾向使用 WSL，请参考在 Linux 上构建的章节。
:::
在安装 Visual Studio 后，选择 C++ 桌面开发的工作负荷后，可能会下载 8GB 左右的编译工具，下载速度取决于你的网络状况。
### 安装 Git
Git for Windows 可以从 [这里](https://git-scm.com/download/win) 下载并安装 `Standalone Installer 64-bit` 版本，安装在默认位置（`C:\Program Files\Git\`）。
如果不想手动下载和安装，你也可以使用 Visual Studio Installer，在**单个组件**的选择列表中，勾选 Git。
### 准备 static-php-cli
static-php-cli 项目的下载方式很简单，只需要使用 git clone 即可。推荐将项目放在 `C:\spc-build\` 或类似目录，路径最好不要有空格。
```shell
mkdir "C:\spc-build"
cd C:\spc-build
git clone https://github.com/crazywhalecc/static-php-cli.git
cd static-php-cli
```
static-php-cli 自身需要 PHP 环境，是有点奇怪，但现在可以通过脚本快速安装 PHP 环境。
一般你的电脑不会安装 Windows 版本的 PHP，所以我们建议你在下载 static-php-cli 后，直接使用 `bin/setup-runtime`，在当前目录安装 PHP 和 Composer。
```shell
# 安装 PHP 和 Composer 到 ./runtime/ 目录
bin/setup-runtime
# 安装后，如需在全局命令中使用 PHP 和 Composer，使用下面的命令将 runtime/ 目录添加到 PATH
bin/setup-runtime -action add-path
# 删除 PATH 中的 runtime/ 目录
bin/setup-runtime -action remove-path
```
在准备好 PHP 和 Composer 环境后，使用 `composer` 安装 static-php-cli 的依赖：
```shell
cd C:\spc-build\static-php-cli
runtime/composer install --no-dev
```
### 自动安装其他依赖
对于 `php-sdk-binary-tools`、`strawberry-perl`、`nasm`，我们更建议你直接使用命令 `bin/spc doctor --auto-fix` 检查并安装。
如果 doctor 成功自动安装，请**跳过**下方手动安装上述工具的步骤。
如果自动安装无法成功的话，再参考下方手动安装的方式。
### 手动安装 php-sdk-binary-tools
```bat
cd C:\spc-build\static-php-cli
git clone https://github.com/php/php-sdk-binary-tools.git
```
> 你也可以在 Windows 设置中设置全局变量 `PHP_SDK_PATH`，并将该项目克隆至变量对应的路径。一般情况下，默认即可。
### 手动安装 strawberry-perl
> 如果你不需要编译 openssl 扩展，可不安装 perl。
1. 从 [GitHub](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/) 下载 strawberry-perl 最新版。
2. 安装到 `C:\spc-build\static-php-cli\pkgroot\perl\` 目录。
> 你可以下载 `-portable` 版本，并直接解压到上述目录。
> 最后的 `perl.exe` 应该位于 `C:\spc-build\static-php-cli\pkgroot\perl\perl\bin\perl.exe`。
### 手动安装 nasm
> 如果你不需要编译 openssl 扩展，可不安装 nasm。
1. 从 [官网](https://www.nasm.us/pub/nasm/releasebuilds/) 下载 nasm 工具（x64）。
2. 将 `nasm.exe`、`ndisasm.exe` 放在 `C:\spc-build\static-php-cli\php-sdk-binary-tools\bin\` 目录。
## 下载源码
见 [本地构建 - download](./manual-build.html#命令-download-下载依赖包)
## 编译 PHP
使用 build 命令可以开始构建静态 php 二进制，在执行 `bin/spc build` 命令前，务必先使用 `download` 命令下载资源，建议使用 `doctor` 检查环境。
### 基本用法
你需要先到 [扩展列表](./extensions) 或 [命令生成器](./cli-generator) 选择你要加入的扩展，然后使用命令 `bin/spc build` 进行编译。你需要指定编译目标，从如下参数中选择：
- `--build-cli`: 构建一个 cli sapi（命令行界面，可在命令行执行 PHP 代码）
- `--build-micro`: 构建一个 micro sapi（用于构建一个包含 PHP 代码的独立可执行二进制）
```shell
# 编译 PHP，附带 bcmath,openssl,zlib 扩展，编译目标为 cli
bin/spc build "bcmath,openssl,zlib" --build-cli
# 编译 PHP，附带 bcmath,openssl,zlib 扩展，编译目标为 micro 和 cli
bin/spc build "bcmath,openssl,zlib" --build-micro --build-cli
```
::: warning
在Windows中，最好使用双引号包裹包含逗号的参数，例如 `"bcmath,openssl,mbstring"`
:::
### 调试
如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
```shell
bin/spc build "openssl" --build-cli --debug
```
### 编译运行选项
在编译过程中，有些特殊情况需要对编译器、编译目录的内容进行干预，可以尝试使用以下命令：
- `--with-clean`: 编译 PHP 前先清理旧的 make 产生的文件
- `--enable-zts`: 让编译的 PHP 为线程安全版本（默认为 NTS 版本）
- `--with-libs=XXX,YYY`: 编译 PHP 前先编译指定的依赖库，激活部分扩展的可选功能
- `-I xxx=yyy`: 编译前将 INI 选项硬编译到 PHP 内（支持多个选项，别名是 `--with-hardcoded-ini`）
- `--with-micro-fake-cli`: 在编译 micro 时，让 micro 的 SAPI 伪装为 `cli`（用于兼容一些检查 `PHP_SAPI` 的程序）
- `--disable-opcache-jit`: 禁用 opcache jit（默认启用）
- `--without-micro-ext-test`: 在构建 micro.sfx 后，禁用测试不同扩展在 micro.sfx 的运行结果
- `--with-suggested-exts`: 编译时将 `ext-suggests` 也作为编译依赖加入
- `--with-suggested-libs`: 编译时将 `lib-suggests` 也作为编译依赖加入
- `--with-upx-pack`: 编译后使用 UPX 减小二进制文件体积（需先使用 `bin/spc install-pkg upx` 安装 upx）
- `--with-micro-logo=XXX.ico`: 自定义 micro 构建组合后的 `exe` 可执行文件的图标（格式为 `.ico`）
有关硬编码 INI 选项，下面是一个简单的例子，我们预设一个更大的 `memory_limit`，并且禁用 `system` 函数：
```shell
bin/spc build "bcmath,openssl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
```
另一个例子：自定义 micro 构建后的 `exe` 程序图标：
```shell
bin/spc build "ffi,bcmath" --build-micro --with-micro-logo=mylogo.ico --debug
bin/spc micro:combine hello.php
# Then we got `my-app.exe` with custom logo!
my-app.exe
```
## 使用 php.exe
php.exe 编译后位于 `buildroot\bin\` 目录，你可以将其拷贝到任意位置使用。
```shell
.\php -v
```
## 使用 micro
> phpmicro 是一个提供自执行二进制 PHP 的项目，本项目依赖 phpmicro 进行编译自执行二进制。详见 [dixyes/phpmicro](https://github.com/dixyes/phpmicro)。
最后编译结果会输出一个 `./micro.sfx` 的文件，此文件需要配合你的 PHP 源码使用。
该文件编译后会存放在 `buildroot/bin/` 目录中。
使用时应准备好你的项目源码文件，可以是单个 PHP 文件，也可以是 Phar 文件。
> 如果要结合 phar 文件，编译时必须包含 phar 扩展！
```shell
# code.php "<?php echo 'Hello world' . PHP_EOL;"
bin/spc micro:combine code.php -O my-app.exe
# Run it!!! Copy it to another computer!!!
./my-app.exe
```
如果打包 PHAR 文件，仅需把 code.php 更换为 phar 文件路径即可。
你可以使用 [box-project/box](https://github.com/box-project/box) 将你的 CLI 项目打包为 Phar，
然后将它与 phpmicro 结合，生成独立可执行的二进制文件。
有关 `micro:combine` 命令的更多细节，请参考 Unix 系统上的 [命令](./manual-build)。

11
docs/zh/guide/cli-generator.md Normal file
View File

@@ -0,0 +1,11 @@
<script setup lang="ts">
import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
</script>
# CLI 编译命令生成器
::: tip
下面选择扩展可能包含所选操作系统不支持的扩展，这可能导致编译失败。请先查阅 [支持的扩展](./extensions)。
:::
<cli-generator lang="zh" />

165
docs/zh/guide/env-vars.md Normal file
View File

@@ -0,0 +1,165 @@
---
aside: false
---
# 环境变量列表
本页面的环境变量列表中所提到的所有环境变量都具有默认值，除非另有说明。你可以通过设置这些环境变量来覆盖默认值。
一般情况下，你不需要修改任何以下环境变量，因为它们已经被设置为最佳值。
但是，如果你有特殊需求，你可以通过设置这些环境变量来满足你的需求（比如你需要调试不同编译参数下的 PHP 性能表现）。
如需使用自定义环境变量，你可以在终端中使用 `export` 命令或者在命令前直接设置环境变量，例如：
```shell
# export 方式
export SPC_CONCURRENCY=4
bin/spc build mbstring,pcntl --build-cli
# 直接设置方式
SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli
```
## 通用环境变量
通用环境变量是所有构建目标都可以使用的环境变量。
| var name | default value | comment |
|------------------------------|---------------------------|-----------------------------|
| `BUILD_ROOT_PATH` | `{pwd}/buildroot` | 编译目标的根目录 |
| `BUILD_LIB_PATH` | `{pwd}/buildroot/lib` | 编译依赖库的根目录 |
| `BUILD_INCLUDE_PATH` | `{pwd}/buildroot/include` | 编译依赖库的头文件目录 |
| `BUILD_BIN_PATH` | `{pwd}/buildroot/bin` | 编译依赖库的二进制文件目录 |
| `PKG_ROOT_PATH` | `{pwd}/pkgroot` | 闭源或预编译工具下载后安装的目录 |
| `SOURCE_PATH` | `{pwd}/source` | 编译项目的源码解压缩目录 |
| `DOWNLOAD_PATH` | `{pwd}/downloads` | 下载的文件存放目录 |
| `SPC_CONCURRENCY` | 取决于当前 CPU 核心数量 | 并行编译的数量 |
| `SPC_SKIP_PHP_VERSION_CHECK` | 空 | 设置为 `yes` 时，跳过扩展对 PHP 版本的检查 |
## 系统特定变量
这些环境变量是特定于系统的，它们只在特定的系统上才会生效。
### Windows
| var name | default value | comment |
|----------------|------------------------------|-----------------|
| `PHP_SDK_PATH` | `{pwd}\php-sdk-binary-tools` | PHP SDK 工具的安装目录 |
| `UPX_EXEC` | `$PKG_ROOT_PATH\bin\upx.exe` | UPX 压缩工具的路径 |
### macOS
| var name | default value | comment |
|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| `CC` | `clang` | C 编译器 |
| `CXX` | `clang++` | C++ 编译器 |
| `SPC_DEFAULT_C_FLAGS` | `--target=arm64-apple-darwin` 或 `--target=x86_64-apple-darwin` | 默认 C 编译标志（与 `CFLAGS` 不同） |
| `SPC_DEFAULT_CXX_FLAGS` | `--target=arm64-apple-darwin` 或 `--target=x86_64-apple-darwin` | 默认 C++ 编译标志（与 `CXXFLAGS` 不同） |
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | 编译 PHP `buildconf` 命令前缀 |
| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | 编译 PHP `configure` 命令前缀 |
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | 编译 PHP `make` 命令前缀 |
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS -Werror=unknown-warning-option` | PHP `configure` 命令的 `CFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | PHP `configure` 命令的 `CPPFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | PHP `configure` 命令的 `LDFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os` 或 `-g -O0`（当使用 `--no-strip` 时为后者） | PHP `make` 命令的 `EXTRA_CFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | `-lresolv` | PHP `make` 命令的额外 `EXTRA_LIBS` 变量 |
### Linux
| var name | default value | comment |
|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
| `UPX_EXEC` | `$PKG_ROOT_PATH/bin/upx` | UPX 压缩工具的路径 |
| `GNU_ARCH` | `x86_64` 或 `aarch64` | 当前环境的 CPU 架构 |
| `CC` | Alpine: `gcc`, Other: `$GNU_ARCH-linux-musl-gcc` | C 编译器 |
| `CXX` | Alpine: `g++`, Other: `$GNU_ARCH-linux-musl-g++` | C++ 编译器 |
| `AR` | Alpine: `ar`, Other: `$GNU_ARCH-linux-musl-ar` | 静态库工具 |
| `LD` | `ld.gold` | 链接器 |
| `PATH` | `/usr/local/musl/bin:/usr/local/musl/$GNU_ARCH-linux-musl/bin:$PATH` | 系统 PATH |
| `SPC_DEFAULT_C_FLAGS` | empty | 默认 C 编译标志 |
| `SPC_DEFAULT_CXX_FLAGS` | empty | 默认 C++ 编译标志 |
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | 编译 PHP `buildconf` 命令前缀 |
| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `LD_LIBRARY_PATH={ld_lib_path} ./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | 编译 PHP `configure` 命令前缀 |
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | 编译 PHP `make` 命令前缀 |
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS` | PHP `configure` 命令的 `CFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | PHP `configure` 命令的 `CPPFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | PHP `configure` 命令的 `LDFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_CONFIGURE_LIBS` | `-ldl -lpthread` | PHP `configure` 命令的 `LIBS` 变量 |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os -fno-ident -fPIE` 或 `-g -O0 -fno-ident -fPIE`（当使用 `--no-strip` 时为后者） | PHP `make` 命令的 `EXTRA_CFLAGS` 变量 |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | empty | PHP `make` 命令的额外 `EXTRA_LIBS` 变量 |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM` | `-all-static`（当使用 `clang` 时：`-Xcompiler -fuse-ld=lld -all-static`） | `make` 命令的额外 `LDFLAGS` 变量（用于编译程序） |
| `SPC_NO_MUSL_PATH` | empty | 是否不插入 musl 工具链的 PATH（值为 `yes` 时不插入） |
> `{ld_lib_path}` 值为 `/usr/local/musl/$GNU_ARCH-linux-musl/lib`。
### FreeBSD
因 FreeBSD 系统的用户较少，我们暂时不提供 FreeBSD 系统的环境变量。
### Unix
对于 macOS、Linux、FreeBSD 等 Unix 系统，以下环境变量是通用的。
| var name | default value | comment |
|-------------------|------------------------------|------------------|
| `PATH` | `$BUILD_BIN_PATH:$PATH` | 系统 PATH |
| `PKG_CONFIG_PATH` | `$BUILD_LIB_PATH/pkgconfig` | pkg-config 的搜索路径 |
| `PKG_CONFIG` | `$BUILD_BIN_PATH/pkg-config` | pkg-config 命令路径 |
## 编译依赖库的环境变量（仅限 Unix 系统）
从 2.2.0 开始，static-php-cli 对所有 macOS、Linux、FreeBSD 等 Unix 系统的编译依赖库的命令均支持自定义环境变量。
这样你就可以随时通过环境变量来调整编译依赖库的行为。例如你可以通过 `xxx_CFLAGS=-O0` 来设置编译 xxx 库的优化参数。
当然，不是每个依赖库都支持注入环境变量，我们目前提供了三个通配的环境变量，后缀分别为：
- `_CFLAGS`: C 编译器的参数
- `_LDFLAGS`: 链接器的参数
- `_LIBS`: 额外的链接库
前缀为依赖库的名称，具体依赖库的名称以 `lib.json` 为准。其中，带有 `-` 的依赖库名称需要将 `-` 替换为 `_`。
下面是一个替换 openssl 库编译的优化选项示例：
```shell
openssl_CFLAGS="-O0"
```
库名称使用同 `lib.json` 中列举的名称，区分大小写。
::: tip
当未指定相关环境变量时，除以下变量外，其余值均默认为空：
| var name | var default value |
|-----------------------|-------------------------------------------------------------------------------------------------|
| `pkg_config_CFLAGS` | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
| `pkg_config_LDFLAGS` | Linux: `--static`, Other: empty |
| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty |
| `imagemagick_LIBS` | macOS: `-liconv`, Other: empty |
| `ldap_LDFLAGS` | `-L$BUILD_LIB_PATH` |
| `openssl_CFLAGS` | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty |
| others... | empty |
:::
下表是支持自定义以上三种变量的依赖库名称列表：
| lib name |
|-------------|
| brotli |
| bzip |
| curl |
| freetype |
| gettext |
| gmp |
| imagemagick |
| ldap |
| libargon2 |
| libavif |
| libcares |
| libevent |
| openssl |
::: tip
因为给每个库适配自定义环境变量是一项特别繁琐的工作，且大部分情况下你都不需要这些库的自定义环境变量，所以我们目前只支持了部分库的自定义环境变量。
如果你需要自定义环境变量的库不在上方列表，可以通过 [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues) 来提出需求。
:::

133
docs/zh/guide/extension-notes.md Normal file
View File

@@ -0,0 +1,133 @@
# 扩展注意事项
因为是静态编译，扩展不会 100% 完美编译，而且不同扩展对 PHP、环境都有不同的要求，这里将一一列举。
## curl
使用 curl 请求 HTTPS 时，可能存在 `error:80000002:system library::No such file or directory` 错误，
解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
## phpmicro
1. phpmicro SAPI 仅支持 PHP >= 8.0 版本。
## swoole
1. swoole >= 5.0 版本仅支持 PHP >= 8.0 版本。
2. swoole 目前不支持 PHP 8.0 版本 curl 的 hook（后续有可能会修复）。
3. 编译时只包含 `swoole` 扩展时不会完整开启支持的 Swoole 数据库协程 hook，如需使用请加入对应的 `swoole-hook-xxx` 扩展。
4. swoole 在部分扩展组合下可能出现 `zend_mm_heap corrupted` 问题，暂未找到是什么原因导致的。
## swoole-hook-pgsql
swoole-hook-pgsql 不是一个扩展，而是 Swoole 的 Hook 特性。
如果你在编译时添加了 `swoole,swoole-hook-pgsql`，你将启用 Swoole 的 PostgreSQL 客户端和 `pdo_pgsql` 扩展的协程模式。
swoole-hook-pgsql 与 `pdo_pgsql` 扩展冲突。如需使用 Swoole 和 `pdo_pgsql`，请删除 pdo_pgsql 扩展，启用 `swoole` 和 `swoole-hook-pgsql` 即可。
该扩展包含了 `pdo_pgsql` 的协程环境的实现。
在 macOS 系统，`pdo_pgsql` 可能无法正常连接到 postgresql 服务器，请谨慎使用。
## swoole-hook-mysql
swoole-hook-mysql 不是一个扩展，而是 Swoole 的 Hook 特性。
如果你在编译时添加了 `swoole,swoole-hook-mysql`，你将启用 Swoole 的 `mysqlnd` 和 `pdo_mysql` 的协程模式。
## swoole-hook-sqlite
swoole-hook-sqlite 不是一个扩展，而是 Swoole 的 Hook 特性。
如果你在编译时添加了 `swoole,swoole-hook-sqlite`，你将启用 Swoole 的 `pdo_sqlite` 的协程模式（Swoole 必须为 5.1 以上）。
swoole-hook-sqlite 与 `pdo_sqlite` 扩展冲突。如需使用 Swoole 和 `pdo_sqlite`，请删除 pdo_sqlite 扩展，启用 `swoole` 和 `swoole-hook-sqlite` 即可。
该扩展包含了 `pdo_sqlite` 的协程环境的实现。
## swow
1. swow 仅支持 PHP >= 8.0 版本。
## imap
1. 该扩展目前不支持 Kerberos。
2. 由于底层的 c-client、ext-imap 不是线程安全的。 无法在 `--enable-zts` 构建中使用它。
3. 由于该扩展可能会从未来的 PHP 中删除，因此我们建议您寻找替代实现，例如 [Webklex/php-imap](https://github.com/Webklex/php-imap)。
## gd
1. gd 扩展依赖了较多的额外图形库，默认情况下，直接使用 `bin/spc build gd` 不会引入和支持部分图形库，例如 `libjpeg`、`libavif` 等，
需要使用 `--with-libs` 参数补全。目前支持 `freetype,libjpeg,libavif,libwebp` 四个库的支持，所以这里可以使用以下命令来让 gd 库引入它们：
```bash
bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
```
## mcrypt
1. 目前未支持，未来也不计划支持此扩展。[#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
## oci8
1. oci8 是 Oracle 数据库的扩展，因为 Oracle 提供的扩展所依赖的库未提供静态编译版本（`.a`）或源代码，无法使用静态链接的方式将此扩展编译到 php 内，故无法支持。
## xdebug
1. Xdebug 是一个 Zend 扩展，Xdebug 的功能依赖于 PHP 的 Zend 引擎和底层代码，如果要将其静态编译到 PHP 中，可能需要巨量的 patch 代码，这是不可行的。
2. macOS 平台可以通过在相同平台编译的 PHP 下编译一个 xdebug 扩展，并提取其中的 `xdebug.so` 文件，再在 static-php-cli 中使用 `--no-strip` 参数保留调试符号表，同时加入 `ffi` 扩展。
编译的 `./php` 二进制可以通过指定 INI 配置并运行，例如`./php -d 'zend_extension=xdebug.so' your-code.php`。
## xml
1. xml包括 xmlreader、xmlwriter、dom、simplexml 等，添加 xml 扩展时最好同时启用这些扩展。
2. libxml 包含在 xml 扩展中。 启用 xml 相当于启用 libxml。
## glfw
1. glfw 扩展依赖 OpenGL，在 Linux 平台还依赖 X11 等环境，这些库都无法被轻易地动态链接。
2. 在 macOS 系统下，我们可以动态链接系统的 OpenGL 和一些相关的库。
## rar
1. rar 扩展目前在 macOS x86_64 环境下与 `common` 扩展集合编译 phpmicro 存在问题。
## pgsql
~~pgsql ssl 连接与 openssl 3.2.0 不兼容。相关链接：~~
- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
pgsql 16.2 修复了这个 Bug，现在正常工作了。
在 pgsql 使用 SSL 连接时，可能存在 `error:80000002:system library::No such file or directory` 错误，
解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
## openssl
使用基于 openssl 的扩展（如 curl、pgsql 等网络库）时，可能存在 `error:80000002:system library::No such file or directory` 错误，
解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
## password-argon2
1. password-argon2不是一个标准的扩展，它是 `password_hash` 函数的额外算法。
2. 在Linux系统，password-argon2 的依赖库 `libargon2` 与 `libsodium` 库冲突。
## ffi
1. 因为 Linux 系统的限制，虽然可以成功编译 ffi 扩展，但无法使用它加载其他 `so` 扩展。Linux 支持加载 so 扩展的前提是非静态编译，但动态编译和本项目的目的冲突。
2. macOS 支持 ffi 扩展，但是部分内核下不包含调试符号时会出现错误。
3. Windows 支持 ffi 扩展。
## xhprof
xhprof 扩展包含三部分：`xhprof_extension`、`xhprof_html`、`xhprof_libs`。编译的二进制中只包含 `xhprof_extension`。
如果需要使用 xhprof，请到 [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) 下载源码，指定 `xhprof_libs` 和 `xhprof_html` 路径来使用。
## event
event 扩展在 macOS 系统下编译后暂无法使用 `openpty` 特性。相关 Issue：
- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
## parallel
parallel 扩展只支持 PHP 8.0 及以上版本，并只支持 ZTS 构建（`--enable-zts`）。

24
docs/zh/guide/extensions.md Normal file
View File

@@ -0,0 +1,24 @@
# 扩展列表
> - `yes`: 已支持
> - 空白: 目前还不支持，或正在支持中
> - `no` with issue link: 确定不支持或无法支持
> - `partial` with issue link: 已支持，但是无法完美工作
<!--@include: ../../extensions.md-->
::: tip
如果缺少您需要的扩展，您可以创建 [功能请求](https://github.com/crazywhalecc/static-php-cli/issues)。
有些扩展或扩展依赖的库会有一些可选的特性，例如 gd 库可选支持 libwebp、freetype 等。
如果你只使用 `bin/spc build gd --build-cli` 是不会包含它们（static-php-cli 默认为最小依赖原则）。
你可以在编译时使用 `--with-libs=` 加入这些库，当本次编译的依赖库中包含它们，gd 会自动依赖它们启用这些特性。
（如：`bin/spc build gd --with-libs=libwebp,freetype --build-cli`）
或者你也可以使用 `--with-suggested-exts` 和 `--with-suggested-libs` 启用这些扩展和库所有可选的依赖。
（如：`bin/spc build gd --with-suggested-libs --build-cli`）
如果你不知道某个扩展是否有可选特性，可以通过查看 [spc 配置文件](https://github.com/crazywhalecc/static-php-cli/tree/main/config)
或使用命令 `bin/spc dev:extensions` 查看（库依赖为 `lib-suggests`，扩展依赖为 `ext-suggests`）。
:::

34
docs/zh/guide/index.md Normal file
View File

@@ -0,0 +1,34 @@
# 指南
static-php-cli 是一个用于构建静态编译的 PHP 二进制的工具，目前支持 Linux 和 macOS 系统。
在指南章节中，你将了解到如何使用 static-php-cli 构建独立的 php 程序。
- [Action 构建](./action-build)
- [本地构建](./manual-build)
- [扩展列表](./extensions)
## 编译环境
下面是架构支持情况，:gear: 代表支持 GitHub Action 构建，:computer: 代表支持本地构建，空 代表暂不支持。
| | x86_64 | aarch64 |
|---------|-------------------|-------------------|
| macOS | :gear: :computer: | :gear: :computer: |
| Linux | :gear: :computer: | :gear: :computer: |
| Windows | :gear: :computer: | |
| FreeBSD | :computer: | :computer: |
其中，Linux 目前仅在 Ubuntu、Debian、Alpine 发行版测试通过，其他发行版未进行测试，不能保证编译成功。
对于未经过测试的发行版，可以使用 Docker 等方式本地编译，避免环境导致的问题。
macOS 下支持 x86_64 和 Arm 两种架构，但在其中一个架构上编译的二进制无法直接在另一个架构上使用。
Rosetta 2 不能保证 Arm 架构编译的程序可以完全运行在 x86_64 环境下。
Windows 目前只支持 x86_64 架构，不支持 32 位 x86、不支持 arm64 架构。
## PHP 支持版本
目前，static-php-cli 对 PHP 7.4 ~ 8.3 版本是支持的，对于 PHP 7.4 及更早版本理论上支持，只需下载时选择早期版本即可。
但由于部分扩展和特殊组件已对早期版本的 PHP 停止了支持，所以 static-php-cli 不会明确支持早期版本。
我们推荐你编译尽可能新的 PHP 版本，以获得更好的体验。

468
docs/zh/guide/manual-build.md Normal file
View File

@@ -0,0 +1,468 @@
# 本地构建（Linux、macOS、FreeBSD）
本章节为 Linux、macOS、FreeBSD 的构建过程，如果你要在 Windows 上构建，请到 [在 Windows 上构建](./build-on-windows)。
## 手动构建（使用 SPC 二进制）（推荐）
本项目提供了一个 static-php-cli 的二进制文件，你可以直接下载对应平台的二进制文件，然后使用它来构建静态的 PHP。目前 `spc` 二进制支持的平台有 Linux 和 macOS。
使用以下命令从自托管服务器下载：
```bash
# Download from self-hosted nightly builds (sync with main branch)
# For Linux x86_64
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
# For Linux aarch64
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
# macOS x86_64 (Intel)
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
# macOS aarch64 (Apple)
curl -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 -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` 二进制，你需要将下面所有命令中 `bin/spc` 开头替换为 `./spc`。
## 手动构建（使用源码）
如果使用 spc 二进制出现问题，或你有修改 static-php-cli 源码需求，请从源码下载 static-php-cli。
目前支持在 macOS、Linux 上构建，macOS 支持最新版操作系统和两种架构，Linux 支持 Debian、RHEL 及衍生发行版、Alpine Linux 等。
因为本项目本身采用 PHP 开发，所以在编译时也需要系统安装 PHP。本项目本身也提供了适用于本项目的静态二进制 php，可以根据实际情况自行选择使用。
### 下载本项目
```bash
git clone https://github.com/crazywhalecc/static-php-cli.git --depth=1
cd static-php-cli
# 你需要先安装 PHP 环境后再运行 Composer 和本项目，安装方式可参考下面。
composer update
```
### 使用系统 PHP 环境
下面是系统安装 PHP、Composer 的一些示例命令。具体安装方式建议自行搜索或询问 AI 搜索引擎获取答案，这里不多赘述。
```bash
# [macOS], 需要先安装 Homebrew. See https://brew.sh/
# Remember change your composer executable path. For M1/M2 Chip mac, "/opt/homebrew/bin/", for Intel mac, "/usr/local/bin/". Or add it to your own path.
brew install php wget
wget https://getcomposer.org/download/latest-stable/composer.phar -O /path/to/your/bin/composer && chmod +x /path/to/your/bin/composer
# [Debian], you need to make sure your php version >= 8.1 and composer >= 2.0
sudo apt install php-cli composer php-tokenizer
# [Alpine]
apk add bash file wget xz php81 php81-common php81-pcntl php81-tokenizer php81-phar php81-posix php81-xml composer
```
::: tip
目前 Ubuntu 部分版本的 apt 安装的 php 版本较旧，故不提供安装命令。如有需要，建议先添加 ppa 等软件源后，安装最新版的 PHP 以及 tokenizer、xml、phar 扩展。
较老版本的 Debian 默认安装的可能为旧版本（<= 7.4）版本的 PHP，建议先升级 Debian。
:::
### 使用 Docker 环境
如果你不愿意在系统安装 PHP 和 Composer 运行环境，可以使用内置的 Docker 环境构建脚本。
```bash
# 直接使用，将所有使用的命令中 `bin/spc` 替换为 `bin/spc-alpine-docker` 即可
bin/spc-alpine-docker
```
首次执行命令会使用 `docker build` 构建一个 Docker 镜像，默认构建的 Docker 镜像为 `x86_64` 架构，镜像名称为 `cwcc-spc-x86_64`。
如果你想在 `x86_64` 环境下构建 `aarch64` 的 static-php-cli，可以使用 qemu 模拟 arm 镜像运行 Docker，但速度会非常慢。使用参数：`SPC_USE_ARCH=aarch64 bin/spc-alpine-docker`。
如果运行后提示需要 sudo 才能运行，执行一次以下命令可授予 static-php-cli 执行 sudo 的权限：
```bash
export SPC_USE_SUDO=yes
```
### 使用预编译静态 PHP 二进制
如果你不想使用 Docker、在系统内安装 PHP，可以直接下载本项目自身编译好的 php 二进制 cli 程序。使用流程如下：
使用命令部署环境，此脚本会从 [自托管的服务器](https://dl.static-php.dev/static-php-cli/) 下载一个当前操作系统的 php-cli 包，
并从 [getcomposer](https://getcomposer.org/download/latest-stable/composer.phar) 或 [Aliyun（镜像）](https://mirrors.aliyun.com/composer/composer.phar) 下载 Composer。
::: tip
使用预编译静态 PHP 二进制目前仅支持 Linux 和 macOS。FreeBSD 环境因为缺少自动化构建环境，所以暂不支持。
:::
```bash
bin/setup-runtime
# 对于中国大陆地区等网络环境特殊的用户，可使用镜像站加快下载速度
bin/setup-runtime --mirror china
```
此脚本总共会下载两个文件：`bin/php` 和 `bin/composer`，下载完成后，有两种使用方式：
1. 将 `bin/` 目录添加到 PATH 路径中：`export PATH="/path/to/your/static-php-cli/bin:$PATH"`，添加路径后，相当于系统安装了 PHP，可直接使用 `composer`、`php -v` 等命令，也可以直接使用 `bin/spc`。
2. 直接调用，比如执行 static-php-cli 命令：`bin/php bin/spc --help`，执行 Composer：`bin/php bin/composer update`。
## 命令 download - 下载依赖包
使用命令 `bin/spc download` 可以下载编译需要的源代码，包括 php-src 以及依赖的各种库的源码。
```bash
# 仅下载要编译的扩展及依赖库（使用扩展名，包含可选库）
bin/spc download --for-extensions=openssl,swoole,zip,pcntl,zstd
# 仅下载要编译的扩展及依赖库（使用扩展名，不包含可选库）
bin/spc download --for-extensions=openssl,swoole,zip,pcntl --without-suggestions
# 仅下载要编译的库（包括其依赖，使用库名，包含可选库，可以和 --for-extensions 组合使用）
bin/spc download --for-libs=liblz4,libevent --for-extensions=pcntl,rar,xml
# 仅下载要编译的库（包括其依赖，使用库名，不包含可选库）
bin/spc download --for-libs=liblz4,libevent --without-suggestions
# 下载资源时，忽略部分资源的缓存，强制下载（如切换 PHP 版本）
bin/spc download --for-extensions=curl,pcntl,xml --ignore-cache-sources=php-src --with-php=8.3
# 下载所有依赖包
bin/spc download --all
# 下载所有依赖包，并指定下载的 PHP 主版本，可选：7.3，7.4，8.0，8.1，8.2，8.3。
bin/spc download --all --with-php=8.2
# 下载时显示下载进度条（curl）
bin/spc download --all --debug
# 删除旧的下载数据
bin/spc download --clean
# 仅下载指定的资源（使用资源名）
bin/spc download php-src,micro,zstd,ext-zstd
# 设置重试次数
bin/spc download --all --retry=2
```
如果你所在地区的网络不好，或者下载依赖包速度过于缓慢，可以从 GitHub Action 下载每周定时打包的 `download.zip`，并使用命令直接使用 zip 压缩包作为依赖。
依赖包可以从 [Action](https://github.com/static-php/static-php-cli-hosted/actions/workflows/download-cache.yml) 下载到本地。
进入 Action 并选择一个最新成功运行的 Workflow，下载 `download-files-x.y` 即可。
```bash
bin/spc download --from-zip=/path/to/your/download.zip
```
如果某个 source 始终无法下载，或者你需要下载一些特定版本的包，例如下载测试版 PHP、旧版本库等，可以使用参数 `-U` 或 `--custom-url` 重写下载链接，
让下载器强制使用你指定的链接下载此 source 的包。使用方法为 `{source-name}:{url}` 即可，可同时重写多个库的下载地址。在使用 `--for-extensions` 选项下载时同样可用。
```bash
# 例如：指定下载测试版的 PHP8.3
bin/spc download --all -U "php-src:https://downloads.php.net/~eric/php-8.3.0beta1.tar.gz"
# 指定下载旧版本的 curl 库
bin/spc download --all -U "curl:https://curl.se/download/curl-7.88.1.tar.gz"
```
## 命令 doctor - 环境检查
如果你可以正常运行 `bin/spc` 但无法正常编译静态的 PHP 或依赖库，可以先运行 `bin/spc doctor` 检查系统自身是否缺少依赖。
```bash
# 快速检查
bin/spc doctor
# 快速检查，并在可以自动修复的时候修复（使用包管理安装依赖包，仅支持上述提到的操作系统及发行版）
bin/spc doctor --auto-fix
```
## 命令 build - 编译 PHP
使用 build 命令可以开始构建静态 php 二进制，在执行 `bin/spc build` 命令前，务必先使用 `download` 命令下载资源，建议使用 `doctor` 检查环境。
### 基本用法
你需要先到 [扩展列表](./extensions) 或 [命令生成器](./cli-generator) 选择你要加入的扩展，然后使用命令 `bin/spc build` 进行编译。你需要指定一个编译目标，从如下参数中选择：
- `--build-cli`: 构建一个 cli sapi（命令行界面，可在命令行执行 PHP 代码）
- `--build-fpm`: 构建一个 fpm sapi（php-fpm，用于和其他传统的 fpm 架构的软件如 nginx 配合使用）
- `--build-micro`: 构建一个 micro sapi（用于构建一个包含 PHP 代码的独立可执行二进制）
- `--build-embed`: 构建一个 embed sapi（用于嵌入到其他 C 语言程序中）
- `--build-all`: 构建以上所有 sapi
```bash
# 编译 PHP，附带 bcmath,curl,openssl,ftp,posix,pcntl 扩展，编译目标为 cli
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# 编译 PHP，附带 phar,curl,posix,pcntl,tokenizer 扩展，编译目标为 micro
bin/spc build phar,curl,posix,pcntl,tokenizer --build-micro
```
::: tip
如果你需要重复构建、调试，你可以删除 `buildroot/` 和 `source/` 两个目录，这样你可以从已下载的源码压缩包重新解压并构建：
```shell
# remove
rm -rf buildroot source
# build again
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
::: tip
如果你想构建多个版本的 PHP，且不想每次都重复构建其他依赖库，可以使用 `switch-php-version` 在编译好一个版本后快速切换至另一个版本并编译：
```shell
# switch to 8.3
bin/spc switch-php-version 8.3
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# switch to 8.0
bin/spc switch-php-version 8.0
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
### 调试
如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
### 编译运行选项
在编译过程中，有些特殊情况需要对编译器、编译目录的内容进行干预，可以尝试使用以下命令：
- `--cc=XXX`: 指定 C 语言编译器的执行命令（Linux 默认 `musl-gcc` 或 `gcc`，macOS 默认 `clang`）
- `--cxx=XXX`: 指定 C++ 语言编译器的执行命令（Linux 默认 `g++`，macOS 默认 `clang++`）
- `--with-clean`: 编译 PHP 前先清理旧的 make 产生的文件
- `--enable-zts`: 让编译的 PHP 为线程安全版本（默认为 NTS 版本）
- `--no-strip`: 编译 PHP 库后不运行 `strip` 裁剪二进制文件缩小体积（不裁剪的 macOS 二进制文件可使用动态链接的第三方扩展）
- `--with-libs=XXX,YYY`: 编译 PHP 前先编译指定的依赖库，激活部分扩展的可选功能（例如 gd 库的 libavif 等）
- `-I xxx=yyy`: 编译前将 INI 选项硬编译到 PHP 内（支持多个选项，别名是 `--with-hardcoded-ini`）
- `--with-micro-fake-cli`: 在编译 micro 时，让 micro 的 SAPI 伪装为 `cli`（用于兼容一些检查 `PHP_SAPI` 的程序）
- `--disable-opcache-jit`: 禁用 opcache jit（默认启用）
- `-P xxx.php`: 在 static-php-cli 编译过程中注入外部脚本（详见下方 **注入外部脚本**）
- `--without-micro-ext-test`: 在构建 micro.sfx 后，禁用测试不同扩展在 micro.sfx 的运行结果
- `--with-suggested-exts`: 编译时将 `ext-suggests` 也作为编译依赖加入
- `--with-suggested-libs`: 编译时将 `lib-suggests` 也作为编译依赖加入
- `--with-upx-pack`: 编译后使用 UPX 减小二进制文件体积（需先使用 `bin/spc install-pkg upx` 安装 upx）
硬编码 INI 选项适用于 cli、micro、embed。有关硬编码 INI 选项，下面是一个简单的例子，我们预设一个更大的 `memory_limit`，并且禁用 `system` 函数：
```bash
bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
```
## 命令 micro:combine - 打包 micro 二进制
使用 `micro:combine` 命令可以将上面编译好的 `micro.sfx` 和你的代码（`.php` 或 `.phar` 文件）构建为一个可执行二进制。
你也可以使用该命令直接构建一个注入了 ini 配置的 micro 自执行二进制文件。
::: tip
注入 ini 配置指的是，在将 micro.sfx 和 PHP 源码结合前，在 micro.sfx 后追加一段特殊的结构用于保存 ini 配置项。
micro.sfx 可通过特殊的字节来标识 INI 文件头，通过 INI 文件头可以实现 micro 带 INI 启动。
此特性的原说明地址在 [phpmicro - Wiki](https://github.com/easysoft/phpmicro/wiki/INI-settings)，这个特性也有可能在未来发生变化。
:::
下面是常规用法，直接打包 php 源码到一个文件中：
```bash
# 在做打包流程前，你应该先使用 `build --build-micro` 编译好 micro.sfx
echo "<?php echo 'hello';" > a.php
bin/spc micro:combine a.php
# 使用
./my-app
```
你可以使用以下参数指定要输出的文件名，你也可以指定其他路径的 micro.sfx 进行打包。
```bash
# 指定输出文件名
bin/spc micro:combine a.php --output=custom-bin
# 使用绝对路径，也可以使用简化参数名
bin/spc micro:combine a.php -O /tmp/my-custom-app
# 指定其他位置的 micro.sfx 进行打包
bin/spc micro:combine a.app --with-micro=/path/to/your/micro.sfx
```
如果想注入 ini 配置项，可以使用下面的参数，从文件或命令行选项添加 ini 到可执行文件中。
```bash
# 使用命令行选项指定（-I 是 --with-ini-set 的简写）
bin/spc micro:combine a.php -I "a=b" -I "foo=bar"
# 使用 ini 文件指定（-N 是 --with-ini-file 的简写）
bin/spc micro:combine a.php -N /path/to/your/custom.ini
```
::: warning
注意，请不要直接使用 PHP 源码或系统安装的 PHP 中的 `php.ini` 文件，最好手动编写一个自己需要的参数配置文件，例如：
```ini
; custom.ini
curl.cainfo=/path/to/your/cafile.pem
memory_limit=1G
```
该命令的注入 ini 是通过在 micro.sfx 后追加一段特殊的结构来实现的，和编译时插入硬编码 INI 的功能不同。
:::
如果要打包 phar，只需要将 `a.php` 替换为打包好的 phar 文件即可。但要注意，phar 下的 micro.sfx 需要额外注意路径问题，见 [Developing - Phar 路径问题](../develop/structure#phar-应用目录问题)
## 命令 extract - 手动解压某个库
使用命令 `bin/spc extract` 可以解包和拷贝编译需要的源代码，包括 php-src 以及依赖的各种库的源码（需要自己指定要解包的库名）。
例如，我们在下载好资源后，想分布执行构建流程，手动解包和拷贝包到指定位置，可以使用命令。
```bash
# 解压 php-src 和 libxml2 的下载压缩包，解压的源码存放在 source 目录
bin/spc extract php-src,libxml2
```
## 调试命令 dev - 调试命令集合
调试命令指的是你在使用 static-php-cli 构建 PHP 或改造、增强 static-php-cli 项目本身的时候，可以辅助输出一些信息的命令集合。
- `dev:extensions`: 输出目前所有支持的扩展信息，或者输出指定的扩展信息
- `dev:php-version`: 输出当前编译的 PHP 版本（通过读取 `php_version.h` 实现）
- `dev:sort-config`: 对 `config/` 目录下的配置文件的列表按照字母表排序
- `dev:lib-ver <lib-name>`: 从依赖库的源码中读取版本（仅特定依赖库可用）
- `dev:ext-ver <ext-name>`: 从扩展的源码中读取对应版本（仅特定扩展可用）
```bash
# 输出所有扩展
bin/spc dev:extensions
# 输出指定扩展的信息
bin/spc dev:extensions mongodb,curl,openssl
# 输出指定列，可选：lib-depends, lib-suggests, ext-depends, ext-suggests, unix-only, type
bin/spc dev:extensions --columns=lib-depends,type,ext-depends
# 输出当前编译的 PHP 版本（需要先将下载好的 PHP 源码解压到 source 目录，你可以使用 `bin/spc extract php-src` 单独解压缩源码）
bin/spc dev:php-version
# 排序配置文件 ext.json（也可以排序 lib、source）
bin/spc dev:sort-config ext
```
## 命令 install-pkg - 下载二进制包
使用命令 `bin/spc install-pkg` 可以下载一些预编译或闭源的工具，并将其安装到 `pkgroot` 目录中。
在 `bin/spc doctor` 自动修复 Windows 环境时会下载 nasm、perl 等工具，使用的也是 `install-pkg` 的安装过程。
下面是安装工具的示例：
- 下载安装 UPX（仅限 Linux 和 Windows）: `bin/spc install-pkg upx`
## 命令 del-download - 删除已下载的资源
一些情况下，你需要删除单个或多个指定的下载源文件，并重新下载他们，例如切换 PHP 版本，`2.1.0-beta.4` 版本后提供了 `bin/spc del-download` 命令，可以删除指定源文件。
删除已下载的源文件包含预编译的包以及源代码，名称是 `source.json` 或 `pkg.json` 中的键名。下面是一些例子：
- 删除 PHP 8.2 源码并切换下载为 8.3 版本: `bin/spc del-download php-src && bin/spc download php-src --with-php=8.3`
- 删除 redis 扩展的下载文件: `bin/spc del-download redis`
- 删除下载好的 musl-toolchain x86_64: `bin/spc del-download musl-toolchain-x86_64-linux`
## 注入外部脚本
注入外部脚本指的是在 static-php-cli 编译过程中插入一个或多个脚本，用于更灵活地支持不同环境下的参数修改、源代码补丁。
一般情况下，该功能主要解决使用 `spc` 二进制进行编译时无法通过修改 static-php-cli 代码来实现修改补丁的功能。
还有一种情况：你的项目直接依赖了 `crazywhalecc/static-php-cli` 仓库并同步，但因为项目特性需要做出一些专有的修改，而这些特性并不适合合并到主分支。
鉴于以上情况，在 2.0.1 正式版本中，static-php-cli 加入了多个事件的触发点，你可以通过编写外部的 `xx.php` 脚本，并通过命令行参数 `-P` 传入并执行。
在编写注入外部脚本时，你一定会用到的方法是 `builder()` 和 `patch_point()`。其中，`patch_point()` 获取的是当前正在执行的事件名称，`builder()` 获取的是 BuilderBase 对象。
因为传入的注入点不区分事件，所以你必须将你要执行的代码写在 `if(patch_point() === 'your_event_name')` 中，否则会重复在其他事件中执行。
下面是支持的 patch_point 事件名称及对应位置：
| 事件名称 | 事件描述 |
|------------------------------|-----------------------------------------------------------|
| before-libs-extract | 在编译的依赖库解压前触发 |
| after-libs-extract | 在编译的依赖库解压后触发 |
| before-php-extract | 在 PHP 源码解压前触发 |
| after-php-extract | 在 PHP 源码解压后触发 |
| before-micro-extract | 在 phpmicro 解压前触发 |
| after-micro-extract | 在 phpmicro 解压后触发 |
| before-exts-extract | 在要编译的扩展解压到 PHP 源码目录前触发 |
| after-exts-extract | 在要编译的扩展解压到 PHP 源码目录后触发 |
| before-library[*name*]-build | 在名称为 `name` 的库编译前触发（如 `before-library[postgresql]-build`） |
| after-library[*name*]-build | 在名称为 `name` 的库编译后触发 |
| before-php-buildconf | 在编译 PHP 命令 `./buildconf` 前触发 |
| before-php-configure | 在编译 PHP 命令 `./configure` 前触发 |
| before-php-make | 在编译 PHP 命令 `make` 前触发 |
| before-sanity-check | 在编译 PHP 后，运行扩展检查前触发 |
下面是一个简单的临时修改 PHP 源码的例子，开启 CLI 下在当前工作目录查找 `php.ini` 配置的功能：
```php
// a.php
<?php
if (patch_point() === 'before-php-buildconf') {
// replace php source code
\SPC\store\FileSystem::replaceFileStr(
SOURCE_PATH . '/php-src/sapi/cli/php_cli.c',
'sapi_module->php_ini_ignore_cwd = 1;',
'sapi_module->php_ini_ignore_cwd = 0;'
);
}
```
```bash
bin/spc build mbstring --build-cli -P a.php
echo 'memory_limit=8G' > ./php.ini
```
```
$ buildroot/bin/php -i | grep Loaded
Loaded Configuration File => /Users/jerry/project/git-project/static-php-cli/php.ini
$ buildroot/bin/php -i | grep memory
memory_limit => 8G => 8G
```
对于 static-php-cli 支持的对象、方法及接口，可以阅读源码，大部分的方法和对象都有相应的注释。
一般使用 `-P` 功能常用的对象及函数有：
- `SPC\store\FileSystem`: 文件管理类
- `::replaceFileStr(string $filename, string $search, $replace)`: 替换文件字符串内容
- `::replaceFileStr(string $filename, string $pattern, $replace)`: 正则替换文件内容
- `::replaceFileUser(string $filename, $callback)`: 用户自定义函数替换文件内容
- `::copyDir(string $from, string $to)`: 递归拷贝某个目录到另一个位置
- `::convertPath(string $path)`: 转换路径的分隔符为当前系统分隔符
- `::scanDirFiles(string $dir, bool $recursive = true, bool|string $relative = false, bool $include_dir = false)`: 遍历目录文件
- `SPC\builder\BuilderBase`: 构建对象
- `->getPatchPoint()`: 获取当前的注入点名称
- `->getOption(string $key, $default = null)`: 获取命令行和编译时的选项
- `->getPHPVersionID()`: 获取当前编译的 PHP 版本 ID
- `->getPHPVersion()`: 获取当前编译的 PHP 版本号
- `->setOption(string $key, $value)`: 设定选项
- `->setOptionIfNotExists(string $key, $value)`: 如果选项不存在则设定选项
::: tip
static-php-cli 开放的方法非常多，文档中无法一一列举，但只要是 `public function` 并且不被标注为 `@internal`，均可调用。
:::

20
docs/zh/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,20 @@
# 故障排除
使用 static-php-cli 过程中可能会碰到各种各样的故障，这里将讲述如何自行查看错误并反馈 Issue。
## 下载失败问题
下载资源问题是 spc 最常见的问题之一。主要是由于 spc 下载资源使用的地址一般均为对应项目的官方网站或 GitHub 等，而这些网站可能偶尔会宕机、屏蔽 IP 地址。
目前 2.0.0 版本还没有加入自动重试机制，所以在遇到下载失败后，可以多次尝试调用下载命令。如果确认地址确实无法正常访问，可以提交 Issue 或 PR 更新地址。
## doctor 无法修复
在绝大部分情况下，doctor 模块都可以对缺失的系统环境进行自动修复和安装，但也存在特殊的环境无法正常使用自动修复功能。
部分项目由于系统局限（如 Windows 下无法自动安装 Visual Studio 等软件），无法使用自动修复功能。
在遇到无法自动修复功能时，如果遇到 `Some check items can not be fixed` 字样，则表明无法自动修复，请根据终端显示的方法提交 Issue 或自行修复环境。
## 编译错误
遇到编译错误时，如果没有开启 `--debug` 日志，请先开启调试日志，然后确定报错的命令。
报错的终端输出对于修复编译错误非常重要，请在提交 Issue 时一并将终端日志的最后报错片段（或整个终端日志输出）上传，并且包含使用的 `spc` 命令和参数。