<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -a</span></span></code></pre></div><h3id="php-ini-search-path"tabindex="-1">php.ini search path <aclass="header-anchor"href="#php-ini-search-path"aria-label="Permalink to “php.ini search path”"></a></h3><p>The static PHP cli binary searches for <code>php.ini</code> in this order:</p><ol><li>The path specified with the <code>-c /path/to/php.ini</code> command-line flag</li><li>The path set in the <code>PHP_INI_PATH</code> environment variable</li><li>The directory specified at compile time via <code>--with-config-file-path</code> (default: <code>/usr/local/etc/php</code>)</li></ol><p>Run <code>./buildroot/bin/php --ini</code> to see which ini file is actually loaded.</p><h3id="hard-coded-ini"tabindex="-1">Hard-coded INI <aclass="header-anchor"href="#hard-coded-ini"aria-label="Permalink to “Hard-coded INI”"></a></h3><p>Use <code>-I</code> at build time to bake INI settings directly into the binary, so no external <code>php.ini</code> is required:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"bcmath,pcntl"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"memory_limit=4G"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"disable_functions=system,exec"</span></span></code></pre></div><p>Hard-coded INI applies to the <code>cli</code>, <code>micro</code>, and <code>embed</code> SAPIs.</p><h2id="fpm"tabindex="-1">fpm <aclass="header-anchor"href="#fpm"aria-label="Permalink to “fpm”"></a></h2><p>The <code>fpm</code> SAPI (FastCGI Process Manager) is used with web servers such as Nginx or Apache for traditional web application deployments.</p><divclass="warning custom-block"><pclass="custom-block-title custom-block-title-default">WARNING</p><p><code>fpm</code> is not supported on Windows.</p></div><h3id="build-1"tabindex="-1">Build <aclass="header-anchor"href="#build-1"aria-label="Permalink to “Build”"></a></h3><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"bcmath,openssl,curl,pdo_mysql"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-fpm</span></span></code></pre></div><p>The output is <code>buildroot/bin/php-fpm</code>.</p><p>See <ahref="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a> and <ahref="./cli-reference.html#common-build-options">build:php — Common Build Options</a> for the full option reference.</p><h3id="usage-1"tabindex="-1">Usage <aclass="header-anchor"href="#usage-1"aria-label="Permalink to “Usage”"></a></h3><p>Copy <code>buildroot/bin/php-fpm</code> to your server and use it like a regular <code>php-fpm</code> binary:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="shikishiki-th
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> index </span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">index.php;</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;"> include </span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">fastcgi_params;</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.max_spare_servers</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 3</span></span></code></pre></div><h2id="micro"tabindex="-1">micro <aclass="header-anchor"href="#micro"aria-label="Permalink to “micro”"></a></h2><p>The <code>micro</code> SAPI is built on <ahref="https://github.com/easysoft/phpmicro"target="_blank"rel="noreferrer">phpmicro</a> and produces a self-contained executable stub. With <code>spc micro:combine</code>, you can merge <code>micro.sfx</code> with your PHP code into a single portable binary that requires no PHP installation on the target machine.</p><h3id="build-2"tabindex="-1">Build <aclass="header-anchor"href="#build-2"aria-label="Permalink to “Build”"></a></h3><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"bcmath,phar,openssl,curl"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-micro</span></span></code></pre></div><p>The output is <code>buildroot/bin/micro.sfx</code>.</p><p>See <ahref="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a>, <ahref="./cli-reference.html#common-build-options">build:php — Common Build Options</a>, and <ahref="./cli-reference.html#micro-options">build:php — micro Options</a> for the full option reference.</p><h3id="packaging-an-application"tabindex="-1">Packaging an application <aclass="header-anchor"href="#packaging-an-application"aria-label="Permalink to “Packaging an application”"></a></h3><p>Use <code>micro:combine</code> to bundle a PHP script or phar into a standalone executable:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Bundle a PHP script</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./your-app</span></span></code></pre></div><h3id="injecting-ini-settings"tabindex="-1">Injecting INI settings <aclass="header-anchor"href="#injecting-ini-settings"aria-label="Permalink to “Injecting INI settings”"></a></h3><p>INI configuration can be injected at packaging time via command-line options or an ini file:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inject via command-line options (-I is shorthand for --with-ini-set)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inject from an ini file (-N is shorthand for --with-ini-file)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/custom.ini</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title custom-block-title-default">TIP</p><p>The INI injected with <code>-I</code> here is runtime configuration appended to the <code>micro.sfx</code> file as a special structure. This is distinct from INI hard-coded at compile time using <code>-I</code> during <code>build:php</code>. Both can coexist.</p></div><h3id="pretending-to-be-the-cli-sapi"tabindex="-1">Pretending to be the cli SAPI <aclass="header-anchor"href="#pretending-to-be-the-cli-sapi"aria-label="Permalink to “Pretending to be the cli SAPI”"></a></h3><p>Some frameworks check the <code>PHP_SAPI</code> value and refuse to run outside <code>cli</code>. Since <code>micro</code>'s <code>PHP_SAPI</code> is <code>micro</code> by default, you can make it report <code>cli</code> instead:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"bcmath,phar"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-micro</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro-fake-cli</span></span></code></pre></div><h3id="specifying-a-custom-micro-sfx-path"tabindex="-1">Specifying a custom micro.sfx path <aclass="header-anchor"href="#specifying-a-custom-micro-sfx-path"aria-label="Permalink to “Specifying a custom micro.sfx path”"></a></h3><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro=/path/to/your/micro.sfx</span></span></code></pre></div><h3id="phar-path-considerations"tabindex="-1">phar path considerations <aclass="header-anchor"href="#phar-path-considerations"aria-label="Permalink to “phar path considerations”"></a></h3><p>When packaging a phar, internal relative paths may behave differently than expected. See the <ahref="./../develop/structure.html">Developer Guide — Phar directory issue</a> for details.</p><h2id="embed"tabindex="-1">embed <aclass="header-anchor"href="#embed"aria-label="Permalink to “embed”"></a></h2><p>The <code>embed</code> SAPI compiles PHP into a static library (<code>libphp.a</code> on Linux/macOS, <code>php8embed.lib</code> on Windows) that can be linked into C/C++ programs to run PHP code directly.</p><h3id="build-3"tabindex="-1">Build <aclass="header-anchor"href="#build-3"aria-label="Permalink to “Build”"></a></h3><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="shiki shiki-themes github-light github-dark"style="--shiki-light:#24
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run with a Caddyfile</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --config</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/Caddyfile</span></span></code></pre></div><p>For full usage, refer to the <ahref="https://frankenphp.dev/docs/"target="_blank"rel="noreferrer">FrankenPHP documentation</a>.</p><h2id="dynamic-extension-loading"tabindex="-1">Dynamic Extension Loading <aclass="header-anchor"href="#dynamic-extension-loading"aria-label="Permalink to “Dynamic Extension Loading”"></a></h2><p>Whether a static PHP binary can load extensions at runtime via <code>dl()</code> depends on how the binary was linked.</p><p><strong>macOS</strong> — The build always links dynamically against system libraries. Extensions built as <code>.so</code> files can be loaded at runtime via <code>dl()</code> or <code>php.ini</code> as usual.</p><p><strong>Linux</strong> — StaticPHP's default build target is <code>native-native-musl</code>: a fully static binary linked against musl libc. Because there is no dynamic linker available at runtime, <code>dl()</code> is disabled, the FFI extension cannot be used, and no external <code>.so</code> extensions can be loaded.</p><p>To support dynamic extension loading on Linux, set the <code>SPC_TARGET</code> environment variable before building:</p><divclass="language-bash"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">bash</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">SPC_TARGET</span><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">native-native-gnu.2.17</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> spc</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"bcmath,openssl"</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span></code></pre></div><p>If you installed from source, you can also set <code>SPC_TARGET=native-native-gnu.2.17</code> in <code>config/env.ini</code> to make it the default for all builds.</p><p>This uses the Zig toolchain to produce a partially static binary dynamically linked against glibc 2.17, compatible with most modern GNU/Linux distributions. No Docker and no extra cross-compilation toolchain are required. The resulting binary supports <code>dl()</code>, FFI, and loading <code>.so</code> extensions at runtime, but cannot run on musl-based systems such as Alpine Linux.</p><p><strong>Windows</strong> — PHP extensions on Windows are distributed as <code>.dll</code> files that depend on the DLLs bundled with the official dynamically-built PHP. StaticPHP produces a standalone static executable that does not include those DLLs, so dynamic extension loading is not possible on Windows. All extensions must be compiled in statically at build time.</p></div></div></main><footerclass="VPDocFooter"data-v-7011f0d8data-v-e257564d><!--[--><!--]--><!----><navclass="prev-next"aria-labelledby="doc-footer-aria-label"data-v-e257564d><spanclass="visually-hidden"id="doc-footer-aria-label"data-v-e257564d>Pager</span><divclass="pager"data-v-e257564d><aclass="VPLink link pager-link prev"href="/en/guide/first-build.html"data-v-e257564d><!--[--><spanclass="desc"data-v-e257564d>Previous page</span><spanclass="title"data-v-e257564d>First Build</span><!--]--></a></div><divclass="pager"data-v-e257564d><aclass="VPLink link pager-link next"href="/en/guide/cli-reference.html"data-v-e257564d><!--[--><spanclass="desc"data-v-e257564d>Next page</span><spanclass="title"data-v-e257564d>CLI Reference</span><!--]--
