crazywhalecc/static-php-cli
1
0
Fork 0
mirror of https://github.com/crazywhalecc/static-php-cli.git synced 2026-07-04 23:35:40 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
28126e73d892e64753e91d9be79acce17e011992
static-php-cli/assets/en_guide_sapi-reference.md.Dx3FnmW6.js
crazywhalecc 4f626e75e8 deploy: 9b64ad8299
2026-05-11 05:18:54 +00:00

55 lines
32 KiB
JavaScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import{_ as s,c as a,o as e,aj as n}from"./chunks/framework.C2AwuPrQ.js";const k=JSON.parse('{"title":"PHP SAPI Reference","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"en/guide/sapi-reference.md","filePath":"en/guide/sapi-reference.md"}'),t={name:"en/guide/sapi-reference.md"};function l(h,i,p,d,o,r){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="php-sapi-reference" tabindex="-1">PHP SAPI Reference <a class="header-anchor" href="#php-sapi-reference" aria-label="Permalink to “PHP SAPI Reference”">​</a></h1><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>If you installed spc as a pre-built binary, replace every <code>spc</code> in this page with <code>./spc</code> (or <code>.\\spc.exe</code> on Windows).</p><p>If you installed from source, use <code>bin/spc</code> instead.</p></div><p>This page describes the build options and usage for each PHP SAPI supported by StaticPHP.</p><h2 id="overview" tabindex="-1">Overview <a class="header-anchor" href="#overview" aria-label="Permalink to “Overview”">​</a></h2><table tabindex="0"><thead><tr><th>SAPI</th><th>Build flag</th><th>Output path (Linux/macOS)</th><th>Output path (Windows)</th><th>Platform support</th></tr></thead><tbody><tr><td>cli</td><td><code>--build-cli</code></td><td><code>buildroot/bin/php</code></td><td><code>buildroot/bin/php.exe</code></td><td>Linux, macOS, Windows</td></tr><tr><td>fpm</td><td><code>--build-fpm</code></td><td><code>buildroot/bin/php-fpm</code></td><td>—</td><td>Linux, macOS</td></tr><tr><td>micro</td><td><code>--build-micro</code></td><td><code>buildroot/bin/micro.sfx</code></td><td><code>buildroot/bin/micro.sfx</code></td><td>Linux, macOS, Windows</td></tr><tr><td>embed</td><td><code>--build-embed</code></td><td><code>buildroot/lib/libphp.a</code></td><td><code>buildroot/lib/php8embed.lib</code></td><td>Linux, macOS, Windows</td></tr><tr><td>frankenphp</td><td><code>--build-frankenphp</code></td><td><code>buildroot/bin/frankenphp</code></td><td><code>buildroot/bin/frankenphp.exe</code></td><td>Linux, macOS, Windows</td></tr></tbody></table><h2 id="cli" tabindex="-1">cli <a class="header-anchor" href="#cli" aria-label="Permalink to “cli”">​</a></h2><p>The <code>cli</code> SAPI is the standard PHP command-line binary for running scripts, interactive shells, and CLI applications.</p><h3 id="build" tabindex="-1">Build <a class="header-anchor" href="#build" aria-label="Permalink to “Build”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span></code></pre></div><p>The output is <code>buildroot/bin/php</code> on Linux and macOS, and <code>buildroot/bin/php.exe</code> on Windows.</p><p>See <a href="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a> and <a href="./cli-reference.html#common-build-options">build:php — Common Build Options</a> for the full option reference.</p><h3 id="usage" tabindex="-1">Usage <a class="header-anchor" href="#usage" aria-label="Permalink to “Usage”">​</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;"># Check version and loaded extensions</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -v</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run a script</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-script.php</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Interactive mode</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -a</span></span></code></pre></div><h3 id="php-ini-search-path" tabindex="-1">php.ini search path <a class="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><h3 id="hard-coded-ini" tabindex="-1">Hard-coded INI <a class="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><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</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,pcntl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;memory_limit=4G&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;disable_functions=system,exec&quot;</span></span></code></pre></div><p>Hard-coded INI applies to the <code>cli</code>, <code>micro</code>, and <code>embed</code> SAPIs.</p><h2 id="fpm" tabindex="-1">fpm <a class="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><div class="warning custom-block"><p class="custom-block-title custom-block-title-default">WARNING</p><p><code>fpm</code> is not supported on Windows.</p></div><h3 id="build-1" tabindex="-1">Build <a class="header-anchor" href="#build-1" aria-label="Permalink to “Build”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl,pdo_mysql&quot;</span><span style="--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 <a href="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a> and <a href="./cli-reference.html#common-build-options">build:php — Common Build Options</a> for the full option reference.</p><h3 id="usage-1" tabindex="-1">Usage <a class="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><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;"># Check version</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -v</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Start with a specific config file</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -c</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/php.ini</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -y</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/php-fpm.conf</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Test config file</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -t</span></span></code></pre></div><h3 id="example-nginx-php-fpm" tabindex="-1">Example: Nginx + php-fpm <a class="header-anchor" href="#example-nginx-php-fpm" aria-label="Permalink to “Example: Nginx + php-fpm”">​</a></h3><div class="language-nginx"><button title="Copy Code" class="copy"></button><span class="lang">nginx</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:#D73A49;--shiki-dark:#F97583;">server</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> listen </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">80</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> root </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">/var/www/html;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> index </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">index.php;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> location</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ~</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;"> \\.php$ </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> fastcgi_pass </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">127.0.0.1:9000;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> fastcgi_param </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">SCRIPT_FILENAME $document_root$fastcgi_script_name;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> include </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">fastcgi_params;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Example <code>php-fpm.conf</code>:</p><div class="language-ini"><button title="Copy Code" class="copy"></button><span class="lang">ini</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;">[global]</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pid</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = /var/run/php-fpm.pid</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error_log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = /var/log/php-fpm.log</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">[www]</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">listen</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 127.0.0.1:9000</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = dynamic</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.max_children</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 5</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.start_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 2</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.min_spare_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 1</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.max_spare_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 3</span></span></code></pre></div><h2 id="micro" tabindex="-1">micro <a class="header-anchor" href="#micro" aria-label="Permalink to “micro”">​</a></h2><p>The <code>micro</code> SAPI is built on <a href="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><h3 id="build-2" tabindex="-1">Build <a class="header-anchor" href="#build-2" aria-label="Permalink to “Build”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,phar,openssl,curl&quot;</span><span style="--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 <a href="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a>, <a href="./cli-reference.html#common-build-options">build:php — Common Build Options</a>, and <a href="./cli-reference.html#micro-options">build:php — micro Options</a> for the full option reference.</p><h3 id="packaging-an-application" tabindex="-1">Packaging an application <a class="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><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;"># Bundle a PHP script</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">echo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;?php echo &#39;Hello, World!&#39; . PHP_EOL;&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> hello.php</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> hello.php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=hello</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./hello</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Bundle a phar</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./your-app</span></span></code></pre></div><h3 id="injecting-ini-settings" tabindex="-1">Injecting INI settings <a class="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><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;"># Inject via command-line options (-I is shorthand for --with-ini-set)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;memory_limit=512M&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;curl.cainfo=/etc/ssl/certs/ca-certificates.crt&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inject from an ini file (-N is shorthand for --with-ini-file)</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/custom.ini</span></span></code></pre></div><div class="tip custom-block"><p class="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><h3 id="pretending-to-be-the-cli-sapi" tabindex="-1">Pretending to be the cli SAPI <a class="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>&#39;s <code>PHP_SAPI</code> is <code>micro</code> by default, you can make it report <code>cli</code> instead:</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</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,phar&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-micro</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro-fake-cli</span></span></code></pre></div><h3 id="specifying-a-custom-micro-sfx-path" tabindex="-1">Specifying a custom micro.sfx path <a class="header-anchor" href="#specifying-a-custom-micro-sfx-path" aria-label="Permalink to “Specifying a custom micro.sfx path”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro=/path/to/your/micro.sfx</span></span></code></pre></div><h3 id="phar-path-considerations" tabindex="-1">phar path considerations <a class="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 <a href="./../develop/structure.html">Developer Guide — Phar directory issue</a> for details.</p><h2 id="embed" tabindex="-1">embed <a class="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><h3 id="build-3" tabindex="-1">Build <a class="header-anchor" href="#build-3" aria-label="Permalink to “Build”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-embed</span></span></code></pre></div><p>Output:</p><ul><li>Linux/macOS: <code>buildroot/lib/libphp.a</code>, headers in <code>buildroot/include/</code></li><li>Windows: <code>buildroot/lib/php8embed.lib</code>, headers in <code>buildroot/include/</code></li></ul><p>See <a href="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a>, <a href="./cli-reference.html#common-build-options">build:php — Common Build Options</a>, and <a href="./cli-reference.html#embed-options">build:php — embed Options</a> for the full option reference.</p><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>Detailed instructions for linking and using <code>libphp.a</code> / <code>php8embed.lib</code> in your own projects — including compiler selection, <code>dev:shell</code> usage, and a complete C example — will be covered in the Developer Guide.</p></div><h2 id="frankenphp" tabindex="-1">frankenphp <a class="header-anchor" href="#frankenphp" aria-label="Permalink to “frankenphp”">​</a></h2><p>The <code>frankenphp</code> SAPI builds a <a href="https://github.com/php/frankenphp" target="_blank" rel="noreferrer">FrankenPHP</a> binary — a modern PHP application server with Caddy built in, supporting HTTP/2, HTTP/3, automatic HTTPS, and more.</p><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>The <code>frankenphp</code> binary produced by StaticPHP is a fully self-contained single-file executable. This is different from the official FrankenPHP release, which ships as a dynamically linked binary and requires a separate PHP installation.</p></div><div class="warning custom-block"><p class="custom-block-title custom-block-title-default">WARNING</p><p>FrankenPHP requires thread-safe mode. Always pass <code>--enable-zts</code> when building.</p></div><h3 id="build-4" tabindex="-1">Build <a class="header-anchor" href="#build-4" aria-label="Permalink to “Build”">​</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:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl,pdo_mysql&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-frankenphp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --enable-zts</span></span></code></pre></div><p>The output is <code>buildroot/bin/frankenphp</code> on Linux/macOS, and <code>buildroot/bin/frankenphp.exe</code> on Windows.</p><p>See <a href="./cli-reference.html#sapi-selection">build:php — SAPI Selection</a>, <a href="./cli-reference.html#common-build-options">build:php — Common Build Options</a>, and <a href="./cli-reference.html#frankenphp-options">build:php — frankenphp Options</a> for the full option reference.</p><h3 id="usage-2" tabindex="-1">Usage <a class="header-anchor" href="#usage-2" aria-label="Permalink to “Usage”">​</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;"># Check version</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> version</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run in PHP development server mode</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> php-server</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Run with a Caddyfile</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/Caddyfile</span></span></code></pre></div><p>For full usage, refer to the <a href="https://frankenphp.dev/docs/" target="_blank" rel="noreferrer">FrankenPHP documentation</a>.</p><h2 id="dynamic-extension-loading" tabindex="-1">Dynamic Extension Loading <a class="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&#39;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><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:#24292E;--shiki-dark:#E1E4E8;">SPC_TARGET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">native-native-gnu.2.17</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl&quot;</span><span style="--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>`,83)])])}const b=s(t,[["render",l]]);export{k as __pageData,b as default};
Reference in New Issue View Git Blame Copy Permalink