import{_ as t,c as d,o as a,aj as i}from"./chunks/framework.C2AwuPrQ.js";const k=JSON.parse('{"title":"Migrating from v2","description":"","frontmatter":{},"headers":[],"relativePath":"en/guide/migrate-from-v2.md","filePath":"en/guide/migrate-from-v2.md"}'),s={name:"en/guide/migrate-from-v2.md"};function o(n,e,l,c,r,h){return a(),d("div",null,[...e[0]||(e[0]=[i(`

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.

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 — the main site now hosts v3 documentation.
v2 docs (archived): 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 for details.

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 for details.

`,59)])])}const g=t(s,[["render",o]]);export{k as __pageData,g as default};

Migrating from v2 ​

Documentation URL Change ​

spc Binary Download URL Change ​

Removed Commands ​

Removed Options ​

--with-added-patch / -P (build command) ​

Windows-only: --with-sdk-binary-dir and --vs-ver ​

Renamed / Deprecated Options ​

Example ​

Changed build Command Behaviour ​

Automatic Download in Build Commands ​

Changed download Command Options ​

Removed Dev Commands ​

Renamed Dev Commands ​

New Commands in v3 ​

craft.yml Changes ​

Removed: build-options.with-added-patch ​

libs → packages (both work) ​

env.ini Variable Renames ​

Migrating from v2

Documentation URL Change

`spc` Binary Download URL Change

Removed Commands

Removed Options

`--with-added-patch` / `-P` (build command)

Windows-only: `--with-sdk-binary-dir` and `--vs-ver`

Renamed / Deprecated Options

Example

Changed `build` Command Behaviour

Automatic Download in Build Commands

Changed `download` Command Options

Removed Dev Commands

Renamed Dev Commands

New Commands in v3

`craft.yml` Changes

Removed: `build-options.with-added-patch`

`libs` → `packages` (both work)

`env.ini` Variable Renames