mirror of
https://github.com/crazywhalecc/static-php-cli.git
synced 2026-07-02 22:35:43 +08:00
Add migration guide
This commit is contained in:
crazywhalecc
@@ -8,6 +8,7 @@ export default {
|
||||
{ text: 'First Build', link: '/en/guide/first-build' },
|
||||
{ text: 'PHP SAPI Reference', link: '/en/guide/sapi-reference' },
|
||||
{ text: 'CLI Reference', link: '/en/guide/cli-reference' },
|
||||
{ text: 'Migrating from v2', link: '/en/guide/migrate-from-v2' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
@@ -8,6 +8,7 @@ export default {
|
||||
{ text: '第一次构建', link: '/zh/guide/first-build' },
|
||||
{ text: 'PHP SAPI 构建参考', link: '/zh/guide/sapi-reference' },
|
||||
{ text: '命令行参考', link: '/zh/guide/cli-reference' },
|
||||
{ text: '从 v2 迁移', link: '/zh/guide/migrate-from-v2' },
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
210
docs/en/guide/migrate-from-v2.md
Normal file
210
docs/en/guide/migrate-from-v2.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Migrating from v2
|
||||
|
||||
StaticPHP v3 is a ground-up rewrite. The core build workflow (`download → build → combine`) remains familiar, but several commands, options, and configuration fields have changed. This page covers everything you need to update before switching.
|
||||
|
||||
::: info Scope
|
||||
This guide only covers user-facing CLI commands, options, `craft.yml` fields, and `env.ini` variable names. Internal PHP APIs are not covered.
|
||||
:::
|
||||
|
||||
## Documentation URL Change
|
||||
|
||||
The official documentation site has moved:
|
||||
|
||||
- **v3 docs (current)**: [https://static-php.dev](https://static-php.dev) — the main site now hosts v3 documentation.
|
||||
- **v2 docs (archived)**: [https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 documentation is preserved here for reference.
|
||||
|
||||
Update any bookmarks or internal links accordingly.
|
||||
|
||||
## `spc` Binary Download URL Change
|
||||
|
||||
The nightly `spc` self-contained binary has moved to a new path:
|
||||
|
||||
| | URL |
|
||||
|---|---|
|
||||
| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
|
||||
| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
|
||||
|
||||
Update any CI scripts or bootstrap commands that download the `spc` binary directly. For example:
|
||||
|
||||
```bash
|
||||
# v2
|
||||
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
|
||||
|
||||
# v3
|
||||
curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
|
||||
```
|
||||
|
||||
## Removed Commands
|
||||
|
||||
| v2 Command | v3 Replacement | Notes |
|
||||
|---|---|---|
|
||||
| `del-download` | `spc reset` | `reset` also accepts `--with-pkgroot` and `--with-download` for finer control |
|
||||
| `del-download --all` | `spc reset --with-download` | Removes the downloads cache directory |
|
||||
|
||||
## Removed Options
|
||||
|
||||
### `--with-added-patch` / `-P` (build command)
|
||||
|
||||
This option allowed injecting external PHP patch scripts at specific build stages. **It has been removed in v3.**
|
||||
|
||||
There is no direct drop-in replacement. If you relied on this feature:
|
||||
|
||||
- Consider contributing your patches upstream to the StaticPHP repository.
|
||||
- For project-specific patches, use a custom registry with a package class. See [Writing Package Classes](/en/develop/extending/package-classes) for details.
|
||||
|
||||
::: tip Future Plans
|
||||
A single-file hook API for lightweight patches may be provided in a future release.
|
||||
:::
|
||||
|
||||
### Windows-only: `--with-sdk-binary-dir` and `--vs-ver`
|
||||
|
||||
These options are no longer accepted on the command line. Instead, set the `PHP_SDK_PATH` environment variable to point to your PHP SDK binary tools directory. The Visual Studio version is now managed by the toolchain configuration.
|
||||
|
||||
## Renamed / Deprecated Options
|
||||
|
||||
The following options have been renamed. The old names are accepted where noted, but you should update your scripts.
|
||||
|
||||
| v2 Option | v3 Option | Status |
|
||||
|---|---|---|
|
||||
| `--prefer-pre-built` | `--prefer-binary` / `-p` | Old name kept as a deprecated alias |
|
||||
| `--with-libs=<list>` | `--with-packages=<list>` | — |
|
||||
| `--with-suggested-libs` / `-L` | `--with-suggests` | Old `-L` / `-E` flags removed |
|
||||
| `--with-suggested-exts` / `-E` | `--with-suggests` | Merged into a single flag |
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# v2
|
||||
spc build curl,gd --build-cli --with-libs="openssl" -L -E
|
||||
|
||||
# v3
|
||||
spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
|
||||
```
|
||||
|
||||
## Changed `build` Command Behaviour
|
||||
|
||||
The `build` command (alias: `build:php`) still works. However, v3 also provides **dedicated single-target commands** that do not require SAPI selection flags:
|
||||
|
||||
| v2 | v3 Equivalent |
|
||||
|---|---|
|
||||
| `spc build exts --build-cli` | `spc build:php-cli exts` |
|
||||
| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
|
||||
| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
|
||||
| `spc build exts --build-micro` | `spc build:php-micro exts` |
|
||||
| `spc build exts --build-embed` | `spc build:php-embed exts` |
|
||||
| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
|
||||
|
||||
Use `build:php` when you need to build multiple SAPIs in one pass (the `--build-*` flags remain valid there).
|
||||
|
||||
### Automatic Download in Build Commands
|
||||
|
||||
In v3, all `build:*` commands automatically download any missing dependencies before building. You no longer need to run `spc download` as a separate step:
|
||||
|
||||
```bash
|
||||
# v2 — two steps required
|
||||
spc download --for-extensions=curl,gd
|
||||
spc build curl,gd --build-cli
|
||||
|
||||
# v3 — one step is enough
|
||||
spc build:php-cli curl,gd
|
||||
```
|
||||
|
||||
To opt out of the automatic download (for example in CI where sources are pre-cached), pass `--no-download`:
|
||||
|
||||
```bash
|
||||
spc build:php-cli curl,gd --no-download
|
||||
```
|
||||
|
||||
## Changed `download` Command Options
|
||||
|
||||
| v2 | v3 | Notes |
|
||||
|---|---|---|
|
||||
| `--prefer-pre-built` | `--prefer-binary` / `-p` | Deprecated alias kept |
|
||||
| `--with-libs` | `--for-libs` | Separate from packages |
|
||||
| *(no equivalent)* | `--for-packages` | Unified package filter |
|
||||
| *(no equivalent)* | `--parallel` / `-P` | Parallel downloads |
|
||||
| *(no equivalent)* | `--retry` / `-R` | Retry on failure |
|
||||
|
||||
## Removed Dev Commands
|
||||
|
||||
These development utility commands have been removed or consolidated:
|
||||
|
||||
| v2 Command | v3 Replacement |
|
||||
|---|---|
|
||||
| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
|
||||
| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
|
||||
| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
|
||||
| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
|
||||
| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
|
||||
|
||||
## Renamed Dev Commands
|
||||
|
||||
| v2 | v3 | Notes |
|
||||
|---|---|---|
|
||||
| `dev:sort-config` / `sort-config` | `dev:lint-config` | Old alias still accepted |
|
||||
|
||||
## New Commands in v3
|
||||
|
||||
These commands are new in v3 with no v2 equivalent:
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `spc reset` | Clean `buildroot/` and `source/` directories |
|
||||
| `spc check-update` | Check for newer artifact versions |
|
||||
| `spc build:php-cli` | Build CLI SAPI (no flags needed) |
|
||||
| `spc build:php-fpm` | Build PHP-FPM (no flags needed) |
|
||||
| `spc build:php-cgi` | Build PHP CGI (no flags needed) |
|
||||
| `spc build:php-micro` | Build phpmicro (no flags needed) |
|
||||
| `spc build:php-embed` | Build embed SAPI (no flags needed) |
|
||||
| `spc build:frankenphp` | Build FrankenPHP (no flags needed) |
|
||||
| `spc dev:shell` | Interactive shell with build environment |
|
||||
| `spc dev:is-installed` | Check whether a package is installed |
|
||||
| `spc dev:dump-stages` | Dump all package build stages to JSON |
|
||||
| `spc dev:dump-capabilities` | Dump buildable/installable capabilities |
|
||||
| `spc dev:info` | Show configuration info for a package |
|
||||
|
||||
## `craft.yml` Changes
|
||||
|
||||
### Removed: `build-options.with-added-patch`
|
||||
|
||||
The `with-added-patch` key inside `build-options` is no longer parsed and will be silently ignored. Remove it from your `craft.yml`:
|
||||
|
||||
```yaml
|
||||
# v2 — remove this block
|
||||
build-options:
|
||||
with-added-patch:
|
||||
- my-patch.php
|
||||
```
|
||||
|
||||
### `libs` → `packages` (both work)
|
||||
|
||||
The top-level `libs` field still works. The preferred v3 field name is `packages`, which is a superset covering libraries and other tool packages:
|
||||
|
||||
```yaml
|
||||
# v2
|
||||
libs: nghttp2,liblz4
|
||||
|
||||
# v3 (preferred)
|
||||
packages: nghttp2,liblz4
|
||||
```
|
||||
|
||||
## `env.ini` Variable Renames
|
||||
|
||||
If you customise `config/env.ini` or export environment variables in CI, update the following names:
|
||||
|
||||
| v2 Variable | v3 Variable |
|
||||
|---|---|
|
||||
| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
|
||||
| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
|
||||
| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
|
||||
| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
|
||||
| `SPC_LIBC` | `SPC_TARGET` |
|
||||
|
||||
`SPC_TARGET` uses a new format that encodes both architecture and libc in a single string, for example:
|
||||
|
||||
| v2 | v3 |
|
||||
|---|---|
|
||||
| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
|
||||
| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
|
||||
|
||||
New logging variables were also added (`SPC_ENABLE_LOG_FILE`, `SPC_LOGS_DIR`, `SPC_PRESERVE_LOGS`). Refer to [Environment Variables](/en/guide/env-vars) for details.
|
||||
210
docs/zh/guide/migrate-from-v2.md
Normal file
210
docs/zh/guide/migrate-from-v2.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# 从 v2 迁移
|
||||
|
||||
StaticPHP v3 是一次完整的重写。核心构建流程（`download → build → combine`）保持不变，但部分命令、选项和配置字段已发生变化。本页列出了切换前所有需要更新的内容。
|
||||
|
||||
::: info 范围说明
|
||||
本指南仅涵盖面向用户的 CLI 命令、选项、`craft.yml` 字段和 `env.ini` 变量名称。不涵盖内部 PHP API。
|
||||
:::
|
||||
|
||||
## 文档地址变更
|
||||
|
||||
官方文档站点已迁移：
|
||||
|
||||
- **v3 文档（当前）**：[https://static-php.dev](https://static-php.dev) — 主站现在托管 v3 文档。
|
||||
- **v2 文档（归档）**：[https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 文档已归档保留，供参考。
|
||||
|
||||
请更新你保存的书签或内部链接。
|
||||
|
||||
## `spc` 二进制下载地址变更
|
||||
|
||||
nightly `spc` 自包含二进制文件已迁移到新路径：
|
||||
|
||||
| | 地址 |
|
||||
|---|---|
|
||||
| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
|
||||
| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
|
||||
|
||||
请更新所有直接下载 `spc` 二进制的 CI 脚本或初始化命令，例如：
|
||||
|
||||
```bash
|
||||
# v2
|
||||
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
|
||||
|
||||
# v3
|
||||
curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
|
||||
```
|
||||
|
||||
## 已移除的命令
|
||||
|
||||
| v2 命令 | v3 替代方案 | 说明 |
|
||||
|---|---|---|
|
||||
| `del-download` | `spc reset` | `reset` 支持 `--with-pkgroot` 和 `--with-download` 以进行更细粒度的控制 |
|
||||
| `del-download --all` | `spc reset --with-download` | 删除下载缓存目录 |
|
||||
|
||||
## 已移除的选项
|
||||
|
||||
### `--with-added-patch` / `-P`（build 命令）
|
||||
|
||||
该选项允许在特定构建阶段注入外部 PHP patch 脚本。**v3 已完全移除此功能。**
|
||||
|
||||
目前没有直接的替代方案。如果你依赖此功能，请考虑以下方式：
|
||||
|
||||
- 将你的 patch 贡献到 StaticPHP 的上游仓库。
|
||||
- 对于项目专用的 patch，可以使用自定义 registry 并编写 Package 类。详情参见[编写 Package 类](/zh/develop/extending/package-classes)。
|
||||
|
||||
::: tip 未来计划
|
||||
未来版本可能会提供用于轻量级 patch 的单文件 hook API。
|
||||
:::
|
||||
|
||||
### Windows 专有：`--with-sdk-binary-dir` 和 `--vs-ver`
|
||||
|
||||
这两个选项已不再被命令行接受。请改为设置 `PHP_SDK_PATH` 环境变量，指向你的 PHP SDK binary tools 目录。Visual Studio 版本现在由工具链配置统一管理。
|
||||
|
||||
## 已重命名 / 已弃用的选项
|
||||
|
||||
以下选项已重命名。部分旧名称仍作为弃用别名被接受，但建议尽快更新脚本。
|
||||
|
||||
| v2 选项 | v3 选项 | 状态 |
|
||||
|---|---|---|
|
||||
| `--prefer-pre-built` | `--prefer-binary` / `-p` | 旧名称保留为弃用别名 |
|
||||
| `--with-libs=<list>` | `--with-packages=<list>` | — |
|
||||
| `--with-suggested-libs` / `-L` | `--with-suggests` | 旧 `-L` / `-E` 已移除 |
|
||||
| `--with-suggested-exts` / `-E` | `--with-suggests` | 已合并为单一标志 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# v2
|
||||
spc build curl,gd --build-cli --with-libs="openssl" -L -E
|
||||
|
||||
# v3
|
||||
spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
|
||||
```
|
||||
|
||||
## `build` 命令行为变化
|
||||
|
||||
`build` 命令（别名：`build:php`）仍然可用。但 v3 新增了**专用的单目标构建命令**，无需再传入 SAPI 选择标志：
|
||||
|
||||
| v2 | v3 等价命令 |
|
||||
|---|---|
|
||||
| `spc build exts --build-cli` | `spc build:php-cli exts` |
|
||||
| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
|
||||
| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
|
||||
| `spc build exts --build-micro` | `spc build:php-micro exts` |
|
||||
| `spc build exts --build-embed` | `spc build:php-embed exts` |
|
||||
| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
|
||||
|
||||
如果需要在一次构建中同时编译多个 SAPI，请继续使用 `build:php`（`--build-*` 标志在该命令下仍然有效）。
|
||||
|
||||
### 构建命令自动下载依赖
|
||||
|
||||
v3 中，所有 `build:*` 命令在构建前会自动下载缺失的依赖包，不再需要单独执行 `spc download`：
|
||||
|
||||
```bash
|
||||
# v2 — 需要两步
|
||||
spc download --for-extensions=curl,gd
|
||||
spc build curl,gd --build-cli
|
||||
|
||||
# v3 — 一步即可
|
||||
spc build:php-cli curl,gd
|
||||
```
|
||||
|
||||
如需跳过自动下载（例如在 CI 中源码已预先缓存），可传入 `--no-download`：
|
||||
|
||||
```bash
|
||||
spc build:php-cli curl,gd --no-download
|
||||
```
|
||||
|
||||
## `download` 命令选项变化
|
||||
|
||||
| v2 | v3 | 说明 |
|
||||
|---|---|---|
|
||||
| `--prefer-pre-built` | `--prefer-binary` / `-p` | 弃用别名保留 |
|
||||
| `--with-libs` | `--for-libs` | 与包过滤分开 |
|
||||
| *（无等价）* | `--for-packages` | 统一包过滤器 |
|
||||
| *（无等价）* | `--parallel` / `-P` | 并行下载 |
|
||||
| *（无等价）* | `--retry` / `-R` | 失败重试 |
|
||||
|
||||
## 已移除的 dev 命令
|
||||
|
||||
以下开发辅助命令已被移除或合并：
|
||||
|
||||
| v2 命令 | v3 替代方案 |
|
||||
|---|---|
|
||||
| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
|
||||
| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
|
||||
| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
|
||||
| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
|
||||
| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
|
||||
|
||||
## 已重命名的 dev 命令
|
||||
|
||||
| v2 | v3 | 说明 |
|
||||
|---|---|---|
|
||||
| `dev:sort-config` / `sort-config` | `dev:lint-config` | 旧别名仍可用 |
|
||||
|
||||
## v3 新增命令
|
||||
|
||||
以下命令为 v3 新增，v2 中没有对应命令：
|
||||
|
||||
| 命令 | 说明 |
|
||||
|---|---|
|
||||
| `spc reset` | 清理 `buildroot/` 和 `source/` 目录 |
|
||||
| `spc check-update` | 检查 artifact 的最新版本 |
|
||||
| `spc build:php-cli` | 构建 CLI SAPI（无需标志） |
|
||||
| `spc build:php-fpm` | 构建 PHP-FPM（无需标志） |
|
||||
| `spc build:php-cgi` | 构建 PHP CGI（无需标志） |
|
||||
| `spc build:php-micro` | 构建 phpmicro（无需标志） |
|
||||
| `spc build:php-embed` | 构建 embed SAPI（无需标志） |
|
||||
| `spc build:frankenphp` | 构建 FrankenPHP（无需标志） |
|
||||
| `spc dev:shell` | 进入带构建环境的交互式 shell |
|
||||
| `spc dev:is-installed` | 检查某个包是否已正确安装 |
|
||||
| `spc dev:dump-stages` | 将所有包的构建阶段导出为 JSON |
|
||||
| `spc dev:dump-capabilities` | 导出包的可构建/可安装能力 |
|
||||
| `spc dev:info` | 显示某个包的配置信息 |
|
||||
|
||||
## `craft.yml` 变化
|
||||
|
||||
### 已移除：`build-options.with-added-patch`
|
||||
|
||||
`build-options` 下的 `with-added-patch` 键不再被解析，将被静默忽略。请从你的 `craft.yml` 中移除它：
|
||||
|
||||
```yaml
|
||||
# v2 — 请删除此块
|
||||
build-options:
|
||||
with-added-patch:
|
||||
- my-patch.php
|
||||
```
|
||||
|
||||
### `libs` → `packages`（两者均可用）
|
||||
|
||||
顶层 `libs` 字段仍然有效。v3 中推荐使用 `packages`，它是 `libs` 的超集，还涵盖其他工具类包：
|
||||
|
||||
```yaml
|
||||
# v2
|
||||
libs: nghttp2,liblz4
|
||||
|
||||
# v3（推荐）
|
||||
packages: nghttp2,liblz4
|
||||
```
|
||||
|
||||
## `env.ini` 变量重命名
|
||||
|
||||
如果你在 `config/env.ini` 中进行了自定义，或在 CI 中导出了环境变量，请更新以下变量名：
|
||||
|
||||
| v2 变量名 | v3 变量名 |
|
||||
|---|---|
|
||||
| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
|
||||
| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
|
||||
| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
|
||||
| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
|
||||
| `SPC_LIBC` | `SPC_TARGET` |
|
||||
|
||||
`SPC_TARGET` 使用新的格式，将架构与 libc 编码在一个字符串中，例如：
|
||||
|
||||
| v2 | v3 |
|
||||
|---|---|
|
||||
| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
|
||||
| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
|
||||
|
||||
v3 还新增了若干日志相关变量（`SPC_ENABLE_LOG_FILE`、`SPC_LOGS_DIR`、`SPC_PRESERVE_LOGS`）。详情参见[环境变量](/zh/guide/env-vars)。
|
||||
Reference in New Issue
Block a user