crazywhalecc/static-php-cli
1
0
Fork 0
mirror of https://github.com/crazywhalecc/static-php-cli.git synced 2026-07-07 16:55:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add GUIDE section for v3 docs

Browse Source
This commit is contained in:
crazywhalecc
2026-04-19 18:01:56 +08:00
parent a348e838d7
commit 2045055591
31 changed files with 2156 additions and 518 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/en/guide/cli-generator.md
View File

@@ -2,6 +2,10 @@
aside: false
---
<script setup>
import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
</script>
# Build Command Generator
<!-- TODO: Embed CliGenerator Vue component. -->
<CliGenerator lang="en" />

213
docs/en/guide/cli-reference.md
View File

@@ -1,6 +1,211 @@
---
outline: 'deep'
---
# CLI Reference
<!-- TODO: Full reference for every spc command and option.
One ## section per command: download, build, craft, doctor, check-update, dev:*.
Each option: type, default, description, example.
Covers platform-specific options (e.g., --embed-icon on Windows). -->
::: tip
If you installed spc as a pre-built binary, replace every `spc` in this page with `./spc` (or `.\spc.exe` on Windows).
If you installed from source, use `bin/spc` instead.
:::
## download
Download source archives and pre-built binaries required for building.
```bash
spc download [artifacts] [options]
```
`artifacts` (optional): Specific artifacts to download, comma-separated (e.g. `"php-src,openssl,curl"`).
### Options
| Option | Short | Description |
|---|---|---|
| `--for-extensions=<list>` | `-e` | Download artifacts needed by the given extensions |
| `--for-libs=<list>` | `-l` | Download artifacts needed by the given libraries |
| `--for-packages=<list>` | | Download artifacts needed by the given packages |
| `--without-suggests` | | Skip suggested packages when using `--for-extensions` |
| `--clean` | | Delete existing download cache before fetching |
| `--with-php=<ver>` | | PHP version in `major.minor` format (default: `8.4`) |
| `--prefer-binary` | `-p` | Prefer pre-built binaries over source archives |
| `--prefer-source` | | Prefer source archives over pre-built binaries |
| `--source-only` | | Only download source artifacts |
| `--binary-only` | | Only download binary artifacts |
| `--parallel=<n>` | `-P` | Number of parallel downloads (default: `1`) |
| `--retry=<n>` | `-R` | Number of retries on failure (default: `0`) |
| `--ignore-cache=<list>` | | Force re-download the specified artifacts |
| `--no-alt` | | Do not use alternative mirror URLs |
| `--no-shallow-clone` | | Do not clone git repositories shallowly |
| `--custom-url=<src:url>` | `-U` | Override the download URL for a source |
| `--custom-git=<src:branch:url>` | `-G` | Override with a custom git repository |
| `--custom-local=<src:path>` | `-L` | Use a local path as a source override |
### Examples
```bash
# Download only what the chosen extensions need
spc download --for-extensions="bcmath,openssl,curl" --with-php=8.4
# Download specific artifacts
spc download "php-src,openssl"
# Speed up with parallelism and retries
spc download --for-extensions="bcmath,openssl,curl" --parallel 8 --retry=3
# Prefer pre-built binaries
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary
# Force re-download the PHP source (e.g. when switching versions)
spc download --for-extensions="bcmath,curl" --ignore-cache="php-src" --with-php=8.3
# Override a download URL
spc download --for-extensions="bcmath" --custom-url "php-src:https://downloads.php.net/~user/php-8.5.0alpha1.tar.xz"
```
## build:php {#build-php}
Build PHP and extensions from source. Alias: `build`.
```bash
spc build:php <extensions> [options]
```
`extensions` (required): Comma-separated list of extensions to compile statically (e.g. `"bcmath,openssl,curl"`).
All `download` options are also available on `build:php` with the `--dl-` prefix (e.g. `--dl-with-php=8.3`, `--dl-parallel=4`). These are passed to the automatic downloader that runs before the build.
### SAPI Selection {#sapi-selection}
These flags apply only to the combined `build:php` target. To build a specific SAPI in isolation, use its dedicated command (e.g. `spc build:php-cli`).
| Option | Description |
|---|---|
| `--build-cli` | Build the `cli` SAPI (`php` / `php.exe`) |
| `--build-fpm` | Build `php-fpm` (Linux and macOS only) |
| `--build-cgi` | Build `php-cgi` |
| `--build-micro` | Build `micro.sfx` |
| `--build-embed` | Build the embed static library (`libphp.a` / `php8embed.lib`) |
| `--build-frankenphp` | Build the FrankenPHP binary |
### Common Build Options {#common-build-options}
| Option | Short | Description |
|---|---|---|
| `--no-strip` | | Keep debug symbols; do not strip the binary |
| `--with-upx-pack` | | Compress the output binary with UPX (install first with `spc install-pkg upx`; Linux and Windows only) |
| `--disable-opcache-jit` | | Disable OPcache JIT |
| `--with-config-file-path=<path>` | | Directory where PHP looks for `php.ini` (default: `/usr/local/etc/php`) |
| `--with-config-file-scan-dir=<path>` | | Directory PHP scans for additional `.ini` files (default: `/usr/local/etc/php/conf.d`) |
| `--with-hardcoded-ini=<k=v>` | `-I` | Bake an INI setting into the binary at compile time (repeatable) |
| `--enable-zts` | | Enable thread-safe (ZTS) mode |
| `--no-smoke-test` | | Skip the post-build smoke tests |
| `--with-suggests` | `-L` / `-E` | Also resolve and install suggested packages |
| `--with-packages=<list>` | | Additional packages to install alongside the build |
| `--no-download` | | Skip the download step (use existing cached files) |
| `--with-added-patch=<file>` | `-P` | Inject an external PHP patch script (repeatable) |
| `--build-shared=<list>` | `-D` | Extensions to compile as shared `.so` / `.dll` instead of static |
### micro Options {#micro-options}
| Option | Description |
|---|---|
| `--with-micro-fake-cli` | Make `micro`'s `PHP_SAPI` report `cli` instead of `micro` |
| `--without-micro-ext-test` | Disable the post-build extension test for `micro.sfx` |
| `--with-micro-logo=<path>` | Embed a custom `.ico` icon into `micro.sfx` (Windows only) |
| `--enable-micro-win32` | Build `micro.sfx` as a Win32 GUI application instead of a console app (Windows only) |
### frankenphp Options {#frankenphp-options}
| Option | Description |
|---|---|
| `--enable-zts` | Required for FrankenPHP; enables thread-safe mode |
| `--with-frankenphp-app=<path>` | Embed a directory into the FrankenPHP binary |
### embed Options {#embed-options}
| Option | Description |
|---|---|
| `--build-shared=<list>` | Compile specific extensions as shared libraries (requires embed SAPI) |
### Download Pass-through Options {#download-options}
All downloader options are available with the `--dl-` prefix:
| Option | Description |
|---|---|
| `--dl-with-php=<ver>` | PHP version to download (default: `8.4`) |
| `--dl-prefer-binary` | Prefer pre-built binaries for dependencies |
| `--dl-parallel=<n>` | Number of parallel downloads |
| `--dl-retry=<n>` | Number of retries on failure |
| `--dl-custom-url=<src:url>` | Override a source download URL |
| `--dl-custom-git=<src:branch:url>` | Override with a custom git repository |
### Examples
```bash
# Build cli SAPI
spc build:php "bcmath,openssl,curl" --build-cli
# Build cli + micro together
spc build:php "bcmath,phar,openssl,curl" --build-cli --build-micro
# Build with a specific PHP version
spc build:php "bcmath,openssl" --build-cli --dl-with-php=8.3
# Bake INI into the binary
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
# Keep debug symbols
spc build:php "bcmath,openssl" --build-cli --no-strip
# Build FrankenPHP (ZTS required)
spc build:php "bcmath,openssl,curl" --build-frankenphp --enable-zts
```
## build:php-cli, build:php-fpm, build:php-micro, build:php-embed, build:php-cgi, build:frankenphp
Dedicated single-target build commands. These accept the same options as `build:php` except the SAPI-selection flags (`--build-*`), which are implicit.
```bash
spc build:php-cli "bcmath,openssl,curl"
spc build:php-micro "bcmath,phar,openssl"
spc build:php-fpm "bcmath,openssl,curl,pdo_mysql"
spc build:php-embed "bcmath,openssl"
spc build:frankenphp "bcmath,openssl,curl" --enable-zts
```
## craft
Read a `craft.yml` and run the full build pipeline automatically.
```bash
spc craft [path/to/craft.yml]
```
If no path is given, `craft.yml` in the current working directory is used. See [craft.yml configuration](../develop/craft-yml) for the file format.
## doctor
Diagnose whether the current environment can compile PHP normally.
```bash
spc doctor [--auto-fix[=never]]
```
| Option | Description |
|---|---|
| `--auto-fix` | Automatically fix detected issues using the system package manager |
| `--auto-fix=never` | Report issues but never attempt automatic fixes |
## dev:shell
Enter an interactive shell with StaticPHP's build environment pre-loaded (compiler wrappers, `buildroot/`, `pkgroot/` paths, etc. on `PATH`).
```bash
spc dev:shell
```
Useful for compiling small programs against `libphp.a` (embed SAPI) or inspecting the build environment manually.

56
docs/en/guide/env-vars.md
View File

@@ -1,4 +1,56 @@
# Environment Variables
<!-- TODO: Full table of all env vars supported by config/env.ini and config/env.custom.ini.
Migrate and update from v2 env-vars.md. -->
All environment variables mentioned in the list on this page have default values unless otherwise noted.
You can override the default values by setting these environment variables.
## Environment variables list
StaticPHP centralizes environment variables in the `config/env.ini` file.
You can set environment variables by modifying this file.
We divide the environment variables supported by StaticPHP into three types:
- **Global internal environment variables**: declared after StaticPHP starts, you can use `getenv()` to get them internally in StaticPHP, and you can override them before starting StaticPHP.
- **Fixed environment variables**: declared after StaticPHP starts, you can only use `getenv()` to get them, but you cannot override them through shell scripts.
- **Config file environment variables**: declared before StaticPHP builds, you can set these environment variables by modifying the `config/env.ini` file or through shell scripts.
You can read the comments for each parameter in [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/v3/config/env.ini) to understand its purpose.
## Custom environment variables
Generally, you don't need to modify any of the following environment variables as they are already set to optimal values.
However, if you have special needs, you can set these environment variables to meet your needs
(for example, you need to debug PHP performance under different compilation parameters).
If you want to use custom environment variables, you can use the `export` command in the terminal or set the environment variables directly before the command, for example:
```shell
# export first
export SPC_CONCURRENCY=4
spc build:php "mbstring,pcntl" --build-cli
# or direct use
SPC_CONCURRENCY=4 spc build:php "mbstring,pcntl" --build-cli
```
Or, if you need to modify an environment variable for a long time, you can modify the `config/env.ini` file.
`config/env.ini` is divided into three sections: `[global]` is globally effective, `[windows]`, `[macos]`, `[linux]` are only effective for the corresponding operating system.
For example, if you need to modify the `./configure` command for compiling PHP, you can find the `SPC_CMD_PREFIX_PHP_CONFIGURE` environment variable in the `config/env.ini` file, and then modify its value.
If your build conditions are more complex and require multiple `env.ini` files to switch,
we recommend that you use the `config/env.custom.ini` file.
In this way, you can specify your environment variables by writing additional override items
without modifying the default `config/env.ini` file.
```ini
; This is an example of `config/env.custom.ini` file,
; we modify the `SPC_CONCURRENCY` and linux default CFLAGS passing to libs and PHP
[global]
SPC_CONCURRENCY=4
[linux]
SPC_DEFAULT_C_FLAGS="-O3"
```

168
docs/en/guide/extension-notes.md
View File

@@ -1,3 +1,169 @@
# Extension Notes
<!-- TODO: Migrate and update from v2 extension-notes.md. Per-extension special compilation notes. -->
Because it is a static compilation, extensions will not compile 100% perfectly,
and different extensions have different requirements for PHP and the environment,
which will be listed one by one here.
## curl
HTTP3 support is not enabled by default, compile with `--with-libs="nghttp2,nghttp3,ngtcp2"` to enable HTTP3 support for PHP >= 8.4.
When using curl to request HTTPS, there may be an `error:80000002:system library::No such file or directory` error.
For details on the solution, see [FAQ](../faq/).
## phpmicro
1. Only PHP >= 8.0 is supported.
## swoole
1. swoole >= 5.0 Only PHP >= 8.0 is supported.
2. swoole Currently, curl hooks are not supported for PHP 8.0.x (which may be fixed in the future).
3. When compiling, if only `swoole` extension is included, the supported Swoole database coroutine hook will not be fully enabled.
If you need to use it, please add the corresponding `swoole-hook-xxx` extension.
4. The `zend_mm_heap corrupted` problem may occur in swoole under some extension combinations. The cause has not yet been found.
## swoole-hook-pgsql
swoole-hook-pgsql is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-pgsql`, you will enable Swoole's PostgreSQL client and the coroutine mode of the `pdo_pgsql` extension.
swoole-hook-pgsql conflicts with the `pdo_pgsql` extension. If you want to use Swoole and `pdo_pgsql`, please delete the pdo_pgsql extension and enable `swoole` and `swoole-hook-pgsql`.
This extension contains an implementation of the coroutine environment for `pdo_pgsql`.
On macOS systems, `pdo_pgsql` may not be able to connect to the postgresql server normally, please use it with caution.
## swoole-hook-mysql
swoole-hook-mysql is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-mysql`, you will enable the coroutine mode of Swoole's `mysqlnd` and `pdo_mysql`.
## swoole-hook-sqlite
swoole-hook-sqlite is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-sqlite`, you will enable the coroutine mode of Swoole's `pdo_sqlite` (Swoole must be 5.1 or above).
swoole-hook-sqlite conflicts with the `pdo_sqlite` extension. If you want to use Swoole and `pdo_sqlite`, please delete the pdo_sqlite extension and enable `swoole` and `swoole-hook-sqlite`.
This extension contains an implementation of the coroutine environment for `pdo_sqlite`.
## swoole-hook-odbc
swoole-hook-odbc is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-odbc`, you will enable the coroutine mode of Swoole's `odbc` extension.
swoole-hook-odbc conflicts with the `pdo_odbc` extension. If you want to use Swoole and `pdo_odbc`, please delete the `pdo_odbc` extension and enable `swoole` and `swoole-hook-odbc`.
This extension contains an implementation of the coroutine environment for `pdo_odbc`.
## swow
1. Only PHP 8.0+ is supported.
## imagick
1. OpenMP support is disabled, this is recommended by the maintainers and also the case system packages.
## imap
1. Kerberos is not supported
2. ext-imap is not thread safe due to the underlying c-client. It's not possible to use it in `--enable-zts` builds.
3. The extension was dropped from php 8.4, we recommend you look for an alternative implementation, such as [Webklex/php-imap](https://github.com/Webklex/php-imap)
## gd
1. gd Extension relies on more additional Graphics library. By default,
using `bin/spc build gd` directly will not support some Graphics library, such as `libjpeg`, `libavif`, etc.
Currently, it supports four libraries: `freetype,libjpeg,libavif,libwebp`.
Therefore, the following command can be used to introduce them into the gd library:
```bash
bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
```
## mcrypt
1. Currently not supported, and this extension will not be supported in the future. [#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
## oci8
1. oci8 is an extension of the Oracle database, because the library on which the extension provided by Oracle does not provide a statically compiled version (`.a`) or source code,
and this extension cannot be compiled into php by static linking, so it cannot be supported.
## xdebug
1. Xdebug is only buildable as a shared extension. On Linux, you'll need to use a `SPC_TARGET` with a glibc variant (e.g. `native-native-gnu.2.17`) instead of the default musl static target.
2. When using Linux/glibc or macOS, you can compile Xdebug as a shared extension using `--build-shared="xdebug"`.
The compiled `./php` binary can be configured and run by specifying the INI, e.g. `./php -d 'zend_extension=/path/to/xdebug.so' your-code.php`.
## xml
1. xml includes xml, xmlreader, xmlwriter, xsl, dom, simplexml, etc.
When adding xml extensions, it is best to enable these extensions at the same time.
2. libxml is included in xml extension. Enabling xml is equivalent to enabling libxml.
## glfw
1. glfw depends on OpenGL, and linux environment also needs X11, which cannot be linked statically.
2. macOS platform, we can compile and link system builtin OpenGL and related libraries dynamically.
## rar
1. The rar extension currently has a problem when compiling phpmicro with the `common` extension collection in the macOS x86_64 environment.
## pgsql
~~pgsql ssl connection is not compatible with openssl 3.2.0. See:~~
- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
pgsql 16.2 has fixed this bug, now it's working.
When pgsql uses SSL connection, there may be `error:80000002:system library::No such file or directory` error.
For details on the solution, see [FAQ](../faq/).
## openssl
When using openssl-based extensions (such as curl, pgsql and other network libraries),
there may be an `error:80000002:system library::No such file or directory` error.
For details on the solution, see [FAQ](../faq/).
## password-argon2
1. password-argon2 is not a standard extension. The algorithm `PASSWORD_ARGON2ID` for the `password_hash` function needs libsodium or libargon2 to work.
2. using password-argon2 enables multithread support for this.
## ffi
1. Due to the limitation of musl libc's static linkage, you cannot use ffi because dynamic libraries cannot be loaded.
If you need to use the ffi extension, use a glibc-based `SPC_TARGET` (e.g. `native-native-gnu.2.17`). See [SAPI Reference](./sapi-reference) for details.
2. macOS supports the ffi extension, but errors will occur when some kernels do not contain debugging symbols.
3. Windows x64 supports the ffi extension.
## xhprof
The xhprof extension consists of three parts: `xhprof_extension`, `xhprof_html`, `xhprof_libs`.
Only `xhprof_extension` is included in the compiled binary.
If you need to use xhprof,
please download the source code from [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) and specify the `xhprof_libs` and `xhprof_html` paths for use.
## event
If you enable event extension on macOS, the `openpty` will be disabled due to issue:
- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
## parallel
Parallel is only supported on PHP 8.0 ZTS and above.
## spx
1. SPX does not support Windows, and the official repository does not support static compilation. static-php-cli uses a [modified version](https://github.com/static-php/php-spx).
## mimalloc
1. This is not technically an extension, but a library.
2. Building with `--with-libs="mimalloc"` on Linux or macOS will override the default allocator.
3. This is experimental for now, but is recommended in threaded environments.

16
docs/en/guide/extensions.md
View File

@@ -1,3 +1,17 @@
<script setup>
import SearchTable from "../../.vitepress/components/SearchTable.vue";
</script>
# Supported Extensions
<!-- TODO: Auto-generated by `bin/spc dev:gen-ext-docs`. Placeholder until command is implemented in v3. -->
> - ✅: Supported
> - blank: Not supported or not yet ported
<search-table />
::: tip
If an extension you need is missing, you can file a [feature request](https://github.com/crazywhalecc/static-php-cli/issues).
Some extensions or their library dependencies have optional features (e.g. gd can optionally use libwebp, freetype, etc.).
Running `bin/spc build gd --build-cli` alone will not include them — StaticPHP follows a minimal-dependency principle by default.
:::

37
docs/en/guide/first-build.md
View File

@@ -15,7 +15,7 @@ StaticPHP supports two build workflows — pick the one that fits your situation
| Approach | When to use |
|---|---|
| `craft` (one-shot) | Everyday use, getting started quickly |
| Step-by-step | CI/CD pipelines, when you need to separate download and build phases |
| Step-by-step | Fine-grained control over the build pipeline |
## Option 1: One-Shot Build with `craft` (Recommended)
@@ -76,39 +76,30 @@ This approach lets you run download and compile as separate steps — useful whe
```bash
# Download only what the chosen extensions need (recommended)
spc download --for-extensions=bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer --with-php=8.4
spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.4
# Download by specific libraries
spc download --for-libs=curl,openssl --with-php=8.4
# Download by specific package names
spc download "curl,openssl" --with-php=8.4
```
Downloads are cached in `downloads/` and reused across builds automatically.
```bash
# Slow connection? Increase parallelism and retries
spc download --for-extensions=bcmath,openssl,curl -P 4 --retry=3
spc download --for-extensions="bcmath,openssl,curl" --parallel 10 --retry=3
# Use pre-built binaries where available — skips compiling those dependencies
spc download --for-extensions=bcmath,openssl,curl --prefer-binary
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary
```
### Step 2: Build PHP
```bash
# Build the cli SAPI
spc build:php bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer --build-cli
spc build:php "bcmath,phar,zlib,openssl,curl,fileinfo,tokenizer" --build-cli
# Build multiple SAPIs in one go
spc build:php bcmath,posix,phar,zlib,openssl,curl --build-cli --build-micro
# Build all SAPIs
spc build:php bcmath,posix,phar,zlib,openssl,curl --build-all
```
`build:php` will automatically fetch any missing dependencies before building. If you already ran `download`, pass `--no-download` to skip that step:
```bash
spc build:php bcmath,openssl,curl --build-cli --no-download
spc build:php "bcmath,phar,zlib,openssl,curl" --build-cli --build-micro
```
#### Common Build Options
@@ -118,9 +109,8 @@ spc build:php bcmath,openssl,curl --build-cli --no-download
| `--build-cli` | Build the cli SAPI |
| `--build-fpm` | Build php-fpm (not available on Windows) |
| `--build-micro` | Build micro.sfx |
| `--build-embed` | Build the embed SAPI (not available on Windows) |
| `--build-frankenphp` | Build FrankenPHP (not available on Windows) |
| `--build-all` | Build all SAPIs |
| `--build-embed` | Build the embed SAPI |
| `--build-frankenphp` | Build FrankenPHP |
| `--enable-zts` | Enable thread-safe (ZTS) mode |
| `--no-strip` | Keep debug symbols; do not strip the binary |
| `-I key=value` | Hard-compile an INI option into PHP |
@@ -129,7 +119,7 @@ spc build:php bcmath,openssl,curl --build-cli --no-download
Example — baking in a larger memory limit and disabling the `system` function:
```bash
spc build:php bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
spc build:php "bcmath,pcntl,posix" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
```
## Packaging a micro App
@@ -160,7 +150,7 @@ spc micro:combine your-app.phar --output=your-app -N /path/to/custom.ini
If a build fails or you want to trace what's happening, use `-v` / `-vv` / `-vvv`:
```bash
spc build:php bcmath,openssl --build-cli -vv
spc build:php "bcmath,openssl" --build-cli -vv
```
- `-v` shows `INFO`-level logs: which modules are running and what build commands are being executed.
@@ -172,7 +162,7 @@ To wipe compiled artifacts and start fresh without re-downloading, run `reset`:
```bash
spc reset
# Then rebuild
spc build:php bcmath,openssl --build-cli
spc build:php "bcmath,openssl" --build-cli
```
::: tip
@@ -184,6 +174,7 @@ If you're stuck, open an [Issue](https://github.com/static-php/static-php-cli/is
## What's Next
- [PHP SAPI Reference](./sapi-reference) — Build options and usage guide for each PHP SAPI
- [CLI Reference](./cli-reference) — Full documentation for every command and option
- [Extensions](./extensions) — Browse supported extensions and their dependencies
- [Troubleshooting](./troubleshooting) — Diagnose common build failures

4
docs/en/guide/index.md
View File

@@ -4,6 +4,8 @@
StaticPHP is a build tool that compiles the PHP interpreter together with any extensions you need into a single self-contained binary. The target system doesn't need PHP or any runtime libraries installed — just copy the binary and run it. Builds target Linux, macOS, and Windows.
StaticPHP isn't limited to PHP. Built on the same infrastructure, it can also compile standalone static binaries for common tools like `curl`, `pkg-config`, and `htop` — no dependencies required on the target machine. Support for more tools (including `openssl` and other frequently-used CLI utilities) is planned.
## Why bother with a static PHP binary?
A typical PHP installation is tightly coupled to the system: you install PHP, then extensions, then spend time dealing with version mismatches across distros. A static binary sidesteps all of that — what you get is a single executable that runs on any machine of the same architecture, no setup required.
@@ -16,7 +18,7 @@ Common use cases:
## phpmicro: ship PHP and your code as one file
[phpmicro](https://github.com/easysoft/phpmicro) is a third-party PHP SAPI that StaticPHP supports out of the box. It merges the PHP interpreter with your `.php` source or `.phar` archive into a single self-extracting executable (`.sfx`).
[phpmicro](https://micro.static-php.dev) is a third-party PHP SAPI that StaticPHP supports out of the box. It merges the PHP interpreter with your `.php` source or `.phar` archive into a single self-extracting executable (`.sfx`).
```
micro.sfx + your-app.phar = your-app # one file, zero dependencies

277
docs/en/guide/sapi-reference.md Normal file
View File

@@ -0,0 +1,277 @@
---
outline: 'deep'
---
# PHP SAPI Reference
::: tip
If you installed spc as a pre-built binary, replace every `spc` in this page with `./spc` (or `.\spc.exe` on Windows).
If you installed from source, use `bin/spc` instead.
:::
This page describes the build options and usage for each PHP SAPI supported by StaticPHP.
## Overview
| SAPI | Build flag | Output path (Linux/macOS) | Output path (Windows) | Platform support |
|---|---|---|---|---|
| cli | `--build-cli` | `buildroot/bin/php` | `buildroot/bin/php.exe` | Linux, macOS, Windows |
| fpm | `--build-fpm` | `buildroot/bin/php-fpm` | — | Linux, macOS |
| micro | `--build-micro` | `buildroot/bin/micro.sfx` | `buildroot/bin/micro.sfx` | Linux, macOS, Windows |
| embed | `--build-embed` | `buildroot/lib/libphp.a` | `buildroot/lib/php8embed.lib` | Linux, macOS, Windows |
| frankenphp | `--build-frankenphp` | `buildroot/bin/frankenphp` | `buildroot/bin/frankenphp.exe` | Linux, macOS, Windows |
## cli
The `cli` SAPI is the standard PHP command-line binary for running scripts, interactive shells, and CLI applications.
### Build
```bash
spc build:php "bcmath,openssl,curl" --build-cli
```
The output is `buildroot/bin/php` on Linux and macOS, and `buildroot/bin/php.exe` on Windows.
See [build:php — SAPI Selection](./cli-reference#sapi-selection) and [build:php — Common Build Options](./cli-reference#common-build-options) for the full option reference.
### Usage
```bash
# Check version and loaded extensions
./buildroot/bin/php -v
./buildroot/bin/php -m
# Run a script
./buildroot/bin/php your-script.php
# Interactive mode
./buildroot/bin/php -a
```
### php.ini search path
The static PHP cli binary searches for `php.ini` in this order:
1. The path specified with the `-c /path/to/php.ini` command-line flag
2. The path set in the `PHP_INI_PATH` environment variable
3. The directory specified at compile time via `--with-config-file-path` (default: `/usr/local/etc/php`)
Run `./buildroot/bin/php --ini` to see which ini file is actually loaded.
### Hard-coded INI
Use `-I` at build time to bake INI settings directly into the binary, so no external `php.ini` is required:
```bash
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system,exec"
```
Hard-coded INI applies to the `cli`, `micro`, and `embed` SAPIs.
## fpm
The `fpm` SAPI (FastCGI Process Manager) is used with web servers such as Nginx or Apache for traditional web application deployments.
::: warning
`fpm` is not supported on Windows.
:::
### Build
```bash
spc build:php "bcmath,openssl,curl,pdo_mysql" --build-fpm
```
The output is `buildroot/bin/php-fpm`.
See [build:php — SAPI Selection](./cli-reference#sapi-selection) and [build:php — Common Build Options](./cli-reference#common-build-options) for the full option reference.
### Usage
Copy `buildroot/bin/php-fpm` to your server and use it like a regular `php-fpm` binary:
```bash
# Check version
./buildroot/bin/php-fpm -v
# Start with a specific config file
./buildroot/bin/php-fpm -c /path/to/php.ini -y /path/to/php-fpm.conf
# Test config file
./buildroot/bin/php-fpm -t
```
### Example: Nginx + php-fpm
```nginx
server {
listen 80;
root /var/www/html;
index index.php;
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
Example `php-fpm.conf`:
```ini
[global]
pid = /var/run/php-fpm.pid
error_log = /var/log/php-fpm.log
[www]
listen = 127.0.0.1:9000
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
```
## micro
The `micro` SAPI is built on [phpmicro](https://github.com/easysoft/phpmicro) and produces a self-contained executable stub. With `spc micro:combine`, you can merge `micro.sfx` with your PHP code into a single portable binary that requires no PHP installation on the target machine.
### Build
```bash
spc build:php "bcmath,phar,openssl,curl" --build-micro
```
The output is `buildroot/bin/micro.sfx`.
See [build:php — SAPI Selection](./cli-reference#sapi-selection), [build:php — Common Build Options](./cli-reference#common-build-options), and [build:php — micro Options](./cli-reference#micro-options) for the full option reference.
### Packaging an application
Use `micro:combine` to bundle a PHP script or phar into a standalone executable:
```bash
# Bundle a PHP script
echo "<?php echo 'Hello, World!' . PHP_EOL;" > hello.php
spc micro:combine hello.php --output=hello
./hello
# Bundle a phar
spc micro:combine your-app.phar --output=your-app
./your-app
```
### Injecting INI settings
INI configuration can be injected at packaging time via command-line options or an ini file:
```bash
# Inject via command-line options (-I is shorthand for --with-ini-set)
spc micro:combine your-app.phar --output=your-app -I "memory_limit=512M" -I "curl.cainfo=/etc/ssl/certs/ca-certificates.crt"
# Inject from an ini file (-N is shorthand for --with-ini-file)
spc micro:combine your-app.phar --output=your-app -N /path/to/custom.ini
```
::: tip
The INI injected with `-I` here is runtime configuration appended to the `micro.sfx` file as a special structure. This is distinct from INI hard-coded at compile time using `-I` during `build:php`. Both can coexist.
:::
### Pretending to be the cli SAPI
Some frameworks check the `PHP_SAPI` value and refuse to run outside `cli`. Since `micro`'s `PHP_SAPI` is `micro` by default, you can make it report `cli` instead:
```bash
spc build:php "bcmath,phar" --build-micro --with-micro-fake-cli
```
### Specifying a custom micro.sfx path
```bash
spc micro:combine your-app.phar --output=your-app --with-micro=/path/to/your/micro.sfx
```
### phar path considerations
When packaging a phar, internal relative paths may behave differently than expected. See the [Developer Guide — Phar directory issue](../develop/structure) for details.
## embed
The `embed` SAPI compiles PHP into a static library (`libphp.a` on Linux/macOS, `php8embed.lib` on Windows) that can be linked into C/C++ programs to run PHP code directly.
### Build
```bash
spc build:php "bcmath,openssl" --build-embed
```
Output:
- Linux/macOS: `buildroot/lib/libphp.a`, headers in `buildroot/include/`
- Windows: `buildroot/lib/php8embed.lib`, headers in `buildroot/include/`
See [build:php — SAPI Selection](./cli-reference#sapi-selection), [build:php — Common Build Options](./cli-reference#common-build-options), and [build:php — embed Options](./cli-reference#embed-options) for the full option reference.
::: tip
Detailed instructions for linking and using `libphp.a` / `php8embed.lib` in your own projects — including compiler selection, `dev:shell` usage, and a complete C example — will be covered in the Developer Guide.
:::
## frankenphp
The `frankenphp` SAPI builds a [FrankenPHP](https://github.com/php/frankenphp) binary — a modern PHP application server with Caddy built in, supporting HTTP/2, HTTP/3, automatic HTTPS, and more.
::: tip
The `frankenphp` 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.
:::
::: warning
FrankenPHP requires thread-safe mode. Always pass `--enable-zts` when building.
:::
### Build
```bash
spc build:php "bcmath,openssl,curl,pdo_mysql" --build-frankenphp --enable-zts
```
The output is `buildroot/bin/frankenphp` on Linux/macOS, and `buildroot/bin/frankenphp.exe` on Windows.
See [build:php — SAPI Selection](./cli-reference#sapi-selection), [build:php — Common Build Options](./cli-reference#common-build-options), and [build:php — frankenphp Options](./cli-reference#frankenphp-options) for the full option reference.
### Usage
```bash
# Check version
./buildroot/bin/frankenphp version
# Run in PHP development server mode
./buildroot/bin/frankenphp php-server
# Run with a Caddyfile
./buildroot/bin/frankenphp run --config /path/to/Caddyfile
```
For full usage, refer to the [FrankenPHP documentation](https://frankenphp.dev/docs/).
## Dynamic Extension Loading
Whether a static PHP binary can load extensions at runtime via `dl()` depends on how the binary was linked.
**macOS** — The build always links dynamically against system libraries. Extensions built as `.so` files can be loaded at runtime via `dl()` or `php.ini` as usual.
**Linux** — StaticPHP's default build target is `native-native-musl`: a fully static binary linked against musl libc. Because there is no dynamic linker available at runtime, `dl()` is disabled, the FFI extension cannot be used, and no external `.so` extensions can be loaded.
To support dynamic extension loading on Linux, set the `SPC_TARGET` environment variable before building:
```bash
SPC_TARGET=native-native-gnu.2.17 spc build:php "bcmath,openssl" --build-cli
```
If you installed from source, you can also set `SPC_TARGET=native-native-gnu.2.17` in `config/env.ini` to make it the default for all builds.
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 `dl()`, FFI, and loading `.so` extensions at runtime, but cannot run on musl-based systems such as Alpine Linux.
**Windows** — PHP extensions on Windows are distributed as `.dll` 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.

44
docs/en/guide/troubleshooting.md
View File

@@ -1,5 +1,43 @@
# Troubleshooting
<!-- TODO: Categorized common build failures and fixes.
Sections: Download issues / Compilation errors / Extension conflicts / Windows-specific / glibc Linux.
Migrate and expand from v2 troubleshooting.md. -->
Various failures may be encountered in the process of using StaticPHP,
here will describe how to check the errors by yourself and report an Issue.
## Download Failure
Problems with downloading resources are one of the most common problems with spc.
The main reason is that the addresses used for SPC download resources are generally the official website of the corresponding project or GitHub, etc.,
and these websites may occasionally go down and block IP addresses.
After encountering a download failure,
you can try to call the download command multiple times.
When downloading extensions, you may eventually see errors like `curl: (56) The requested URL returned error: 403` which are often caused by GitHub rate limiting.
You can verify this by adding `-vvv` to the command and will see something like `[DEBU] Running command (no output) : curl -sfSL "https://api.github.com/repos/openssl/openssl/releases"`.
To fix this, [create](https://github.com/settings/tokens) a personal access token on GitHub and set it as an environment variable `GITHUB_TOKEN=<XXX>`.
If you confirm that the address is indeed inaccessible,
you can submit an Issue or PR to update the url or download type.
## Doctor Can't Fix Something
In most cases, the doctor module can automatically repair and install missing system environments,
but there are also special circumstances where the automatic repair function cannot be used normally.
Due to system limitations (for example, software such as Visual Studio cannot be automatically installed under Windows),
the automatic repair function cannot be used for some projects.
When encountering a function that cannot be automatically repaired,
if you encounter the words `Some check items can not be fixed`,
it means that it cannot be automatically repaired.
Please submit an issue according to the method displayed on the terminal or repair the environment yourself.
## Compile Error
When you encounter a compilation error, if the `-vvv` log is not enabled, please enable the debug log first,
and then determine the command that reported the error.
The error terminal output is very important for fixing compilation errors.
When submitting an issue, please upload the last error fragment of the terminal log (or the entire terminal log output),
and include the `spc` command and parameters used.
If you are rebuilding, please refer to the [First Build - Debugging and Rebuilding](./first-build#debugging-and-rebuilding) section.