static-php-cli/assets/en_guide_migrate-from-v2.md.CfVymFnT.js

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(`<h1 id="migrating-from-v2" tabindex="-1">Migrating from v2 <a class="header-anchor" href="#migrating-from-v2" aria-label="Permalink to “Migrating from v2”">​</a></h1><p>StaticPHP v3 is a ground-up rewrite. The core build workflow (<code>download → build → combine</code>) remains familiar, but several commands, options, and configuration fields have changed. This page covers everything you need to update before switching.</p><div class="info custom-block"><p class="custom-block-title">Scope</p><p>This guide only covers user-facing CLI commands, options, <code>craft.yml</code> fields, and <code>env.ini</code> variable names. Internal PHP APIs are not covered.</p></div><h2 id="documentation-url-change" tabindex="-1">Documentation URL Change <a class="header-anchor" href="#documentation-url-change" aria-label="Permalink to “Documentation URL Change”">​</a></h2><p>The official documentation site has moved:</p><ul><li><strong>v3 docs (current)</strong>: <a href="https://static-php.dev" target="_blank" rel="noreferrer">https://static-php.dev</a> — the main site now hosts v3 documentation.</li><li><strong>v2 docs (archived)</strong>: <a href="https://static-php.github.io/v2-docs/" target="_blank" rel="noreferrer">https://static-php.github.io/v2-docs/</a> — v2 documentation is preserved here for reference.</li></ul><p>Update any bookmarks or internal links accordingly.</p><h2 id="spc-binary-download-url-change" tabindex="-1"><code>spc</code> Binary Download URL Change <a class="header-anchor" href="#spc-binary-download-url-change" aria-label="Permalink to “spc Binary Download URL Change”">​</a></h2><p>The nightly <code>spc</code> self-contained binary has moved to a new path:</p><table tabindex="0"><thead><tr><th></th><th>URL</th></tr></thead><tbody><tr><td><strong>v2</strong></td><td><code>https://dl.static-php.dev/static-php-cli/spc-bin/nightly/</code></td></tr><tr><td><strong>v3</strong></td><td><code>https://dl.static-php.dev/v3/spc-bin/nightly/</code></td></tr></tbody></table><p>Update any CI scripts or bootstrap commands that download the <code>spc</code> binary directly. For example:</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -o</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -o</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64</span></span></code></pre></div><h2 id="removed-commands" tabindex="-1">Removed Commands <a class="header-anchor" href="#removed-commands" aria-label="Permalink to “Removed Commands”">​</a></h2><table tabindex="0"><thead><tr><th>v2 Command</th><th>v3 Replacement</th><th>Notes</th></tr></thead><tbody><tr><td><code>del-download</code></td><td><code>spc reset</code></td><td><code>reset</code> also accepts <code>--with-pkgroot</code> and <code>--with-download</code> for finer control</td></tr><tr><td><code>del-download --all</code></td><td><code>spc reset --with-download</code></td><td>Removes the downloads cache directory</td></tr></tbody></table><h2 id="removed-options" tabindex="-1">Removed Options <a class="header-anchor" href="#removed-options" aria-label="Permalink to “Removed Options”">​</a></h2><h3 id="with-added-patch-p-build-command" tabindex="-1"><code>--with-added-patch</code> / <code>-P</code> (build command) <a class="header-anchor" href="#with-added-patch-p-build-command" aria-label="Permalink to “--with-added-patch / -P (build command)”">​</a></h3><p>This option allowed injecting external PHP patch scripts at specific build stages. <strong>It has been removed in v3.</strong></p><p>There is no direct drop-in replacement. If you relied on this feature:</p><ul><li>Consider contributing your patches upstream to the StaticPHP repository.</li><li>For project-specific patches, use a custom registry with a package class. See <a href="/en/develop/extending/package-classes.html">Writing Package Classes</a> for details.</li></ul><div class="tip custom-block"><p class="custom-block-title">Future Plans</p><p>A single-file hook API for lightweight patches may be provided in a future release.</p></div><h3 id="windows-only-with-sdk-binary-dir-and-vs-ver" tabindex="-1">Windows-only: <code>--with-sdk-binary-dir</code> and <code>--vs-ver</code> <a class="header-anchor" href="#windows-only-with-sdk-binary-dir-and-vs-ver" aria-label="Permalink to “Windows-only: --with-sdk-binary-dir and --vs-ver”">​</a></h3><p>These options are no longer accepted on the command line. Instead, set the <code>PHP_SDK_PATH</code> environment variable to point to your PHP SDK binary tools directory. The Visual Studio version is now managed by the toolchain configuration.</p><h2 id="renamed-deprecated-options" tabindex="-1">Renamed / Deprecated Options <a class="header-anchor" href="#renamed-deprecated-options" aria-label="Permalink to “Renamed / Deprecated Options”">​</a></h2><p>The following options have been renamed. The old names are accepted where noted, but you should update your scripts.</p><table tabindex="0"><thead><tr><th>v2 Option</th><th>v3 Option</th><th>Status</th></tr></thead><tbody><tr><td><code>--prefer-pre-built</code></td><td><code>--prefer-binary</code> / <code>-p</code></td><td>Old name kept as a deprecated alias</td></tr><tr><td><code>--with-libs=&lt;list&gt;</code></td><td><code>--with-packages=&lt;list&gt;</code></td><td>—</td></tr><tr><td><code>--with-suggested-libs</code> / <code>-L</code></td><td><code>--with-suggests</code></td><td>Old <code>-L</code> / <code>-E</code> flags removed</td></tr><tr><td><code>--with-suggested-exts</code> / <code>-E</code></td><td><code>--with-suggests</code></td><td>Merged into a single flag</td></tr></tbody></table><h3 id="example" tabindex="-1">Example <a class="header-anchor" href="#example" aria-label="Permalink to “Example”">​</a></h3><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-libs=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -L</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -E</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-packages=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-suggests</span></span></code></pre></div><h2 id="changed-build-command-behaviour" tabindex="-1">Changed <code>build</code> Command Behaviour <a class="header-anchor" href="#changed-build-command-behaviour" aria-label="Permalink to “Changed build Command Behaviour”">​</a></h2><p>The <code>build</code> command (alias: <code>build:php</code>) still works. However, v3 also provides <strong>dedicated single-target commands</strong> that do not require SAPI selection flags:</p><table tabindex="0"><thead><tr><th>v2</th><th>v3 Equivalent</th></tr></thead><tbody><tr><td><code>spc build exts --build-cli</code></td><td><code>spc build:php-cli exts</code></td></tr><tr><td><code>spc build exts --build-fpm</code></td><td><code>spc build:php-fpm exts</code></td></tr><tr><td><code>spc build exts --build-cgi</code></td><td><code>spc build:php-cgi exts</code></td></tr><tr><td><code>spc build exts --build-micro</code></td><td><code>spc build:php-micro exts</code></td></tr><tr><td><code>spc build exts --build-embed</code></td><td><code>spc build:php-embed exts</code></td></tr><tr><td><code>spc build exts --build-frankenphp</code></td><td><code>spc build:frankenphp exts</code></td></tr></tbody></table><p>Use <code>build:php</code> when you need to build multiple SAPIs in one pass (the <code>--build-*</code> flags remain valid there).</p><h3 id="automatic-download-in-build-commands" tabindex="-1">Automatic Download in Build Commands <a class="header-anchor" href="#automatic-download-in-build-commands" aria-label="Permalink to “Automatic Download in Build Commands”">​</a></h3><p>In v3, all <code>build:*</code> commands automatically download any missing dependencies before building. You no longer need to run <code>spc download</code> as a separate step:</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2 — two steps required</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> download</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --for-extensions=curl,gd</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3 — one step is enough</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php-cli</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span></span></code></pre></div><p>To opt out of the automatic download (for example in CI where sources are pre-cached), pass <code>--no-download</code>:</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php-cli</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-download</span></span></code></pre></div><h2 id="changed-download-command-options" tabindex="-1">Changed <code>download</code> Command Options <a class="header-anchor" href="#changed-download-command-options" aria-label="Permalink to “Changed download Command Options”">​</a></h2><table tabindex="0"><thead><tr><th>v2</th><th>v3</th><th>Notes</th></tr></thead><tbody><tr><td><code>--prefer-pre-built</code></td><td><code>--prefer-binary</code> / <code>-p</code></td><td>Deprecated alias kept</td></tr><tr><td><code>--with-libs</code></td><td><code>--for-libs</code></td><td>Separate from packages</td></tr><tr><td><em>(no equivalent)</em></td><td><code>--for-packages</code></td><td>Unified package filter</td></tr><tr><td><em>(no equivalent)</em></td><td><code>--parallel</code> / <code>-P</code></td><td>Parallel downloads</td></tr><tr><td><em>(no equivalent)</em></td><td><code>--retry</code> / <code>-R</code></td><td>Retry on failure</td></tr></tbody></table><h2 id="removed-dev-commands" tabindex="-1">Removed Dev Commands <a class="header-anchor" href="#removed-dev-commands" aria-label="Permalink to “Removed Dev Commands”">​</a></h2><p>These development utility commands have been removed or consolidated:</p><table tabindex="0"><thead><tr><th>v2 Command</th><th>v3 Replacement</th></tr></thead><tbody><tr><td><code>dev:extensions</code> / <code>list-ext</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:ext-version</code> / <code>dev:ext-ver</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:lib-version</code> / <code>dev:lib-ver</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:php-version</code> / <code>dev:php-ver</code></td><td><code>spc dev:info php-src</code></td></tr><tr><td><code>dev:gen-ext-dep-docs</code> + <code>dev:gen-lib-dep-docs</code></td><td><code>spc dev:gen-deps-data</code></td></tr></tbody></table><h2 id="renamed-dev-commands" tabindex="-1">Renamed Dev Commands <a class="header-anchor" href="#renamed-dev-commands" aria-label="Permalink to “Renamed Dev Commands”">​</a></h2><table tabindex="0"><thead><tr><th>v2</th><th>v3</th><th>Notes</th></tr></thead><tbody><tr><td><code>dev:sort-config</code> / <code>sort-config</code></td><td><code>dev:lint-config</code></td><td>Old alias still accepted</td></tr></tbody></table><h2 id="new-commands-in-v3" tabindex="-1">New Commands in v3 <a class="header-anchor" href="#new-commands-in-v3" aria-label="Permalink to “New Commands in v3”">​</a></h2><p>These commands are new in v3 with no v2 equivalent:</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><code>spc reset</code></td><td>Clean <code>buildroot/</code> and <code>source/</code> directories</td></tr><tr><td><code>spc check-update</code></td><td>Check for newer artifact versions</td></tr><tr><td><code>spc build:php-cli</code></td><td>Build CLI SAPI (no flags needed)</td></tr><tr><td><code>spc build:php-fpm</code></td><td>Build PHP-FPM (no flags needed)</td></tr><tr><td><code>spc build:php-cgi</code></td><td>Build PHP CGI (no flags needed)</td></tr><tr><td><code>spc build:php-micro</code></td><td>Build phpmicro (no flags needed)</td></tr><tr><td><code>spc build:php-embed</code></td><td>Build embed SAPI (no flags needed)</td></tr><tr><td><code>spc build:frankenphp</code></td><td>Build FrankenPHP (no flags needed)</td></tr><tr><td><code>spc dev:shell</code></td><td>Interactive shell with build environment</td></tr><tr><td><code>spc dev:is-installed</code></td><td>Check whether a package is installed</td></tr><tr><td><code>spc dev:dump-stages</code></td><td>Dump all package build stages to JSON</td></tr><tr><td><code>spc dev:dump-capabilities</code></td><td>Dump buildable/installable capabilities</td></tr><tr><td><code>spc dev:info</code></td><td>Show configuration info for a package</td></tr></tbody></table><h2 id="craft-yml-changes" tabindex="-1"><code>craft.yml</code> Changes <a class="header-anchor" href="#craft-yml-changes" aria-label="Permalink to “craft.yml Changes”">​</a></h2><h3 id="removed-build-options-with-added-patch" tabindex="-1">Removed: <code>build-options.with-added-patch</code> <a class="header-anchor" href="#removed-build-options-with-added-patch" aria-label="Permalink to “Removed: build-options.with-added-patch”">​</a></h3><p>The <code>with-added-patch</code> key inside <code>build-options</code> is no longer parsed and will be silently ignored. Remove it from your <code>craft.yml</code>:</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2 — remove this block</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">build-options</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  with-added-patch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-patch.php</span></span></code></pre></div><h3 id="libs-→-packages-both-work" tabindex="-1"><code>libs</code> → <code>packages</code> (both work) <a class="header-anchor" href="#libs-→-packages-both-work" aria-label="Permalink to “libs → packages (both work)”">​</a></h3><p>The top-level <code>libs</code> field still works. The preferred v3 field name is <code>packages</code>, which is a superset covering libraries and other tool packages:</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">libs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nghttp2,liblz4</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3 (preferred)</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">packages</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nghttp2,liblz4</span></span></code></pre></div><h2 id="env-ini-variable-renames" tabindex="-1"><code>env.ini</code> Variable Renames <a class="header-anchor" href="#env-ini-variable-renames" aria-label="Permalink to “env.ini Variable Renames”">​</a></h2><p>If you customise <code>config/env.ini</code> or export environment variables in CI, update the following names:</p><table tabindex="0"><thead><tr><th>v2 Variable</th><th>v3 Variable</th></tr></thead><tbody><tr><td><code>SPC_LINUX_DEFAULT_CC</code></td><td><code>SPC_DEFAULT_CC</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_CXX</code></td><td><code>SPC_DEFAULT_CXX</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_AR</code></td><td><code>SPC_DEFAULT_AR</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_LD</code></td><td><code>SPC_DEFAULT_LD</code></td></tr><tr><td><code>SPC_LIBC</code></td><td><code>SPC_TARGET</code></td></tr></tbody></table><p><code>SPC_TARGET</code> uses a new format that encodes both architecture and libc in a single string, for example:</p><table tabindex="0"><thead><tr><th>v2</th><th>v3</th></tr></thead><tbody><tr><td><code>SPC_LIBC=musl</code></td><td><code>SPC_TARGET=x86_64-linux-musl</code></td></tr><tr><td><code>SPC_LIBC=gnu</code></td><td><code>SPC_TARGET=x86_64-linux-gnu.2.17</code></td></tr></tbody></table><p>New logging variables were also added (<code>SPC_ENABLE_LOG_FILE</code>, <code>SPC_LOGS_DIR</code>, <code>SPC_PRESERVE_LOGS</code>). Refer to <a href="/en/guide/env-vars.html">Environment Variables</a> for details.</p>`,59)])])}const g=t(s,[["render",o]]);export{k as __pageData,g as default};