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

Temp

Browse Source
This commit is contained in:
crazywhalecc
2026-04-19 11:49:55 +08:00
parent a175c5862d
commit a348e838d7
120 changed files with 6346 additions and 3391 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs-v2/en/guide/action-build.md Normal file
View File

@@ -0,0 +1,31 @@
# GitHub Action Build
Action Build refers to compiling directly using GitHub Action.
If you don't want to compile it yourself, you can download the artifact from the existing Action in this project,
or you can download it from a self-hosted server：[Enter](https://dl.static-php.dev/static-php-cli/common/).
> Self-hosted binaries are also built from Actions: [repo](https://github.com/static-php/static-php-cli-hosted).
> The extensions included are: bcmath,bz2,calendar,ctype,curl,dom,exif,fileinfo,filter,ftp,gd,gmp,iconv,xml,mbstring,mbregex,mysqlnd,openssl,
> pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,redis,session,simplexml,soap,sockets,sqlite3,tokenizer,xmlwriter,xmlreader,zlib,zip
## Build Guide
Using GitHub Action makes it easy to build a statically compiled PHP and phpmicro,
while also defining the extensions to compile.
1. Fork project.
2. Go to the Actions of the project and select `CI`.
3. Select `Run workflow`, fill in the PHP version you want to compile, the target type, and the list of static extensions. (comma separated, e.g. `bcmath,curl,mbstring`)
4. If you need shared extensions (for example `xdebug`), set `shared-extensions` (comma separated, e.g. `xdebug`).
5. If you need FrankenPHP, enable `build-frankenphp` and also enable `enable-zts`.
6. After waiting for about a period of time, enter the corresponding task and get `Artifacts`.
If you enable `debug`, all logs will be output at build time, including compiled logs, for troubleshooting.
> If you need to build in other environments, you can use [manual build](./manual-build).
## Extensions
You can go to [extensions](./extensions) check here to see if all the extensions you need currently support.
and then go to [command generator](./cli-generator) select the extension you need to compile, copy the extensions string to `extensions` option.

228
docs-v2/en/guide/build-on-windows.md Normal file
View File

@@ -0,0 +1,228 @@
# Build on Windows
Because the Windows system is an NT kernel, the compilation tools and operating system interfaces
used by Unix-like operating systems are almost completely different,
so the build process on Windows will be slightly different from that of Unix systems.
## GitHub Actions Build
Building the Windows version of static-php from Actions is now supported.
Like Linux and macOS, you need to Fork the static-php-cli repository to your GitHub account first,
then you can enter [Extension List](./extensions) to select the extension to be compiled,
and then go to your own `CI on Windows` select the PHP version, fill in the extension list (comma separated), and click Run.
If you're going to develop or build locally, please read on.
## Requirements
The tools required to build static PHP on Windows are the same as PHP's official Windows build tools.
You can read [Official Documentation](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2).
To sum up, you need the following environment and tools:
- Windows 10/11 (requires build 17063 or later)
- Visual Studio 2019/2022 (recommended 2022)
- C++ desktop development for Visual Studio
- Git for Windows
- [php-sdk-binary-tools](https://github.com/php/php-sdk-binary-tools) (can be installed automatically using doctor)
- strawberry-perl (can be installed automatically using doctor)
- nasm (can be installed automatically using doctor)
::: tip
The construction of static-php-cli on Windows refers to using MSVC to build PHP and is not based on MinGW, Cygwin, WSL and other environments.
If you prefer to use WSL, please refer to the chapter on Building on Linux.
:::
After installing Visual Studio and selecting the C++ desktop development workload,
you may download about 8GB of compilation tools, and the download speed depends on your network conditions.
### Install Git
Git for Windows can be downloaded and installed from [here](https://git-scm.com/download/win) `Standalone Installer 64-bit` version,
installed in the default location (`C:\Program Files\Git\`).
If you don't want to download and install manually,
you can also use Visual Studio Installer and check Git in the **Individual component** tab.
### Prepare static-php-cli
Downloading the static-php-cli project is very simple, just use git clone.
It is recommended to place the project in `C:\spc-build\` or a similar directory.
It is best **not to have spaces in the path**.
```shell
mkdir "C:\spc-build"
cd C:\spc-build
git clone https://github.com/crazywhalecc/static-php-cli.git
cd static-php-cli
```
It is a bit strange that static-php-cli itself requires a PHP environment,
but now you can quickly install the PHP environment through a script.
Generally, your computer will not have the Windows version of PHP installed,
so we recommend that you use `bin/setup-runtime` directly after downloading static-php-cli to install PHP and Composer in the current directory.
```shell
# Install PHP and Composer to the ./runtime/ directory
bin/setup-runtime
# After installation, if you need to use PHP and Composer in global commands,
# use the following command to add the runtime/ directory to PATH
bin/setup-runtime -action add-path
# Delete the runtime/ directory in PATH
bin/setup-runtime -action remove-path
```
Finally, now that you have PHP and Composer installed, you need to install static-php-cli's Composer dependencies:
```shell
composer install
```
### Install other Tools (automatic)
For `php-sdk-binary-tools`, `strawberry-perl`, and `nasm`,
we recommend that you directly use the command `bin/spc doctor` to check and install them.
If doctor successfully installs automatically, please **skip** the steps below to manually install the above tools.
But if the automatic installation fails, please refer to the manual installation method below.
### Install php-sdk-binary-tools (manual)
```shell
cd C:\spc-build\static-php-cli
git clone https://github.com/php/php-sdk-binary-tools.git
```
> You can also set the global variable `PHP_SDK_PATH` in Windows settings and
> clone the project to the path corresponding to the variable.
> Under normal circumstances, you don't need to change it.
### Install strawberry-perl (manual)
> If you don't need to compile the openssl extension, you don't need to install perl.
1. Download the latest version of strawberry-perl from [GitHub](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/).
2. Install to the `C:\spc-build\static-php-cli\pkgroot\perl\` directory.
> You can download the `-portable` version and extract it directly to the above directory.
> The last `perl.exe` should be located at `C:\spc-build\static-php-cli\pkgroot\perl\perl\bin\perl.exe`.
### Install nasm (manual)
> If you don't need to compile openssl extension, you don't need to install nasm.
1. Download the nasm tool (x64) from [official website](https://www.nasm.us/pub/nasm/releasebuilds/).
2. Place `nasm.exe` and `ndisasm.exe` in the `C:\spc-build\static-php-cli\php-sdk-binary-tools\bin\` directory.
## Download required sources
Same as [Manual build - Download](./manual-build.html#command-download)
## Build PHP
Use the build command to start building the static php binary.
Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
It is recommended to use `doctor` to check the environment.
### Build SAPI
You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
and then use the command `bin/spc build` to compile.
You need to specify targets, choose from the following parameters (at least one):
- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
```shell
# Compile PHP with bcmath,openssl,zlib extensions, the compilation target is cli
bin/spc build "bcmath,openssl,zlib" --build-cli
# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro and cli
bin/spc build "bcmath,openssl,zlib" --build-micro --build-cli
```
::: warning
In Windows, it is best to use double quotes to wrap parameters containing commas, such as `"bcmath,openssl,mbstring"`.
:::
### Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```shell
bin/spc build "openssl" --build-cli --debug
```
### Build Options
During the compilation process, in some special cases,
the compiler and the content of the compilation directory need to be intervened.
You can try to use the following commands:
- `--with-clean`: clean up old make files before compiling PHP
- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extension optional functions
- `--with-config-file-scan-dir=XXX`: Set the directory to scan for `.ini` files after reading `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
- `--with-micro-logo=XXX.ico`: Customize the icon of the `exe` executable file after customizing the micro build (in the format of `.ico`)
Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
```shell
bin/spc build "bcmath,openssl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
```
Another example: Customize our hello-world.exe program logo:
```shell
bin/spc build "ffi,bcmath" --build-micro --with-micro-logo=mylogo.ico --debug
bin/spc micro:combine hello.php
# Then we got `my-app.exe` with custom logo!
my-app.exe
```
## Use php.exe
After php.exe is compiled, it is located in the `buildroot\bin\` directory. You can copy it to any location for use.
```shell
.\php -v
```
## Use micro.sfx
> phpmicro is a SelF-extracted eXecutable SAPI module,
> provided by [phpmicro](https://github.com/dixyes/phpmicro) project.
> But this project is using a [fork](https://github.com/static-php/phpmicro) of phpmicro, because we need to add some features to it.
> It can put php runtime and your source code together.
The final compilation result will output a file named `./micro.sfx`,
which needs to be used with your PHP source code like `code.php`.
This file will be located in the path `buildroot/bin/micro.sfx`.
Prepare your project source code, which can be a single PHP file or a Phar file, for use.
> If you want to combine phar files, you must add `phar` extension when compiling!
```shell
# code.php "<?php echo 'Hello world' . PHP_EOL;"
bin/spc micro:combine code.php -O my-app.exe
# Run it!!! Copy it to another computer!!!
./my-app.exe
```
If you package a PHAR file, just replace `code.php` with the phar file path.
You can use [box-project/box](https://github.com/box-project/box) to package your CLI project as Phar,
It is then combined with phpmicro to produce a standalone executable binary.
For more details on the `micro:combine` command, refer to [command](./manual-build) on Unix systems.

64
docs-v2/en/guide/build-with-glibc.md Normal file
View File

@@ -0,0 +1,64 @@
# Build glibc Compatible Linux Binary
## Why Build glibc Compatible Binary
Currently, the binaries built by static-php-cli on Linux by default are based on musl-libc (statically linked).
musl-libc is a lightweight libc implementation
that aims to be compatible with glibc and provides good support for pure static linking.
This means that the compiled static PHP executable can be used on almost any Linux distribution without worrying about the versions of libc, libstdc++, etc.
However, there are some issues with pure static linking of musl-libc binaries on Linux:
- The `dl()` function in PHP cannot be used to load dynamic libraries and external PHP extensions.
- The FFI extension in PHP cannot be used.
- In some extreme cases, performance issues may occur. See [musl-libc performance issues](https://github.com/php/php-src/issues/13648).
Different Linux distributions use different default libc.
For example, Alpine Linux uses musl libc, while most Linux distributions use glibc.
However, even so, we cannot directly use any distribution using glibc to build portable static binaries because glibc has some issues:
- Binaries built with gcc and other tools on newer versions of distributions cannot run on older versions of distributions.
- glibc is not recommended to be statically linked because some of its features require the support of dynamic libraries.
However, we can use Docker to solve this problem.
The final output is a binary **dynamically linked with glibc** and some necessary libraries,
but **statically linked with all other dependencies**.
1. Use an older version of a Linux distribution (such as CentOS 7.x), which has an older version of glibc but can run on most modern Linux distributions.
2. Build the static binary of PHP in this container so that it can run on most modern Linux distributions.
> Using glibc static binaries can run on most modern Linux distributions but cannot run on musl libc distributions, such as CentOS 6, Alpine Linux, etc.
## Build glibc Compatible Linux Binary
The latest version of static-php-cli includes the `bin/spc-gnu-docker` script,
which can create a CentOS 7.x (glibc-2.17) Docker container with one click and build a glibc compatible PHP static binary in the container.
Then, run the following command once.
The first run will take a long time because it needs to download the CentOS 7.x image and some build tools.
```bash
bin/spc-gnu-docker
```
After the image is built, you will see the same command help menu as `bin/spc`, which means the container is ready.
After the container is ready, you can refer to the [local build](./manual-build) section to build your PHP static binary.
Just replace `bin/spc` or `./spc` with `bin/spc-gnu-docker`.
```bash
bin/spc-gnu-docker build bcmath,ctype,openssl,pdo,phar,posix,session,tokenizer,xml,zip --build-cli --debug
```
## Notes
In rare cases, glibc-based static PHP may encounter segment faults and other errors, but there are currently few examples.
If you encounter any issues, please submit an issue.
glibc build is an extended feature and is not part of the default static-php support.
If you have related issues or requirements, please indicate that you are building based on glibc when submitting an issue.
If you need to build glibc-based binaries without using Docker,
please refer to the `bin/spc-gnu-docker` script to manually create a similar environment.
Please keep in mind that we only support glibc build with `bin/spc-gnu-docker`. Compilation on RHEL 9 & 10 has been tested and is stable, but if you run into issues, we may choose not to fix them.

16
docs-v2/en/guide/cli-generator.md Normal file
View File

@@ -0,0 +1,16 @@
---
aside: false
---
<script setup lang="ts">
import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
</script>
# CLI Build Command Generator
::: tip
The extensions selected below may contain extensions that are not supported by the selected operating system,
which may cause compilation to fail. Please check [Supported Extensions](./extensions) first.
:::
<cli-generator lang="en" />

26
docs-v2/en/guide/deps-map.md Normal file
View File

@@ -0,0 +1,26 @@
---
outline: 'deep'
---
# Dependency Table
When compiling PHP, each extension and library has dependencies, which may be required or optional.
You can choose whether to include these optional dependencies.
For example, when compiling the `gd` extension under Linux,
the `zlib,libpng` libraries and the `zlib` extension are forced to be compiled,
while the `libavif,libwebp,libjpeg,freetype` libraries are optional libraries and will not be compiled by default
unless specified by the `--with-libs=avif,webp,jpeg,freetype` option.
- For optional extensions (optional features of extensions), you need to specify them manually at compile time, for example, to enable igbinary support for Redis: `bin/spc build redis,igbinary`.
- For optional libraries, you need to compile and specify them through the `--with-libs=XXX` option.
- If you want to enable all optional extensions, you can use `bin/spc build redis --with-suggested-exts`.
- If you want to enable all optional libraries, you can use `--with-suggested-libs`.
## Extension Dependency Table
<!--@include: ../../deps-map-ext.md-->
## Library Dependency Table
<!--@include: ../../deps-map-lib.md-->

121
docs-v2/en/guide/env-vars.md Normal file
View File

@@ -0,0 +1,121 @@
# Environment variables
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
Starting from version 2.3.5, we have centralized the environment variables in the `config/env.ini` file.
You can set environment variables by modifying this file.
We divide the environment variables supported by static-php-cli into three types:
- Global internal environment variables: declared after static-php-cli starts, you can use `getenv()` to get them internally in static-php-cli, and you can override them before starting static-php-cli.
- Fixed environment variables: declared after static-php-cli starts, you can only use `getenv()` to get them, but you cannot override them through shell scripts.
- Config file environment variables: declared before static-php-cli build, 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/main/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
bin/spc build mbstring,pcntl --build-cli
# or direct use
SPC_CONCURRENCY=4 bin/spc build 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"
```
## Library environment variables (Unix only)
Starting from 2.2.0, static-php-cli supports custom environment variables for all compilation dependent library commands of macOS, Linux, FreeBSD and other Unix systems.
In this way, you can adjust the behavior of compiling dependent libraries through environment variables at any time.
For example, you can set the optimization parameters for compiling the xxx library through `xxx_CFLAGS=-O0`.
Of course, not every library supports the injection of environment variables.
We currently provide three wildcard environment variables with the suffixes:
- `_CFLAGS`: CFLAGS for the compiler
- `_LDFLAGS`: LDFLAGS for the linker
- `_LIBS`: LIBS for the linker
The prefix is the name of the dependent library, and the specific name of the library is subject to `lib.json`.
Among them, the library name with `-` needs to replace `-` with `_`.
Here is an example of an optimization option that replaces the openssl library compilation:
```shell
openssl_CFLAGS="-O0"
```
The library name uses the same name listed in `lib.json` and is case-sensitive.
::: tip
When no relevant environment variables are specified, except for the following variables, the remaining values are empty by default:
| var name | var default value |
|-----------------------|-------------------------------------------------------------------------------------------------|
| `pkg_config_CFLAGS` | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
| `pkg_config_LDFLAGS` | Linux: `--static`, Other: empty |
| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty |
| `imagemagick_LIBS` | macOS: `-liconv`, Other: empty |
| `ldap_LDFLAGS` | `-L$BUILD_LIB_PATH` |
| `openssl_CFLAGS` | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty |
| others... | empty |
:::
The following table is a list of library names that support customizing the above three variables:
| lib name |
|-------------|
| brotli |
| bzip |
| curl |
| freetype |
| gettext |
| gmp |
| imagemagick |
| ldap |
| libargon2 |
| libavif |
| libcares |
| libevent |
| openssl |
::: tip
Because adapting custom environment variables to each library is a particularly tedious task,
and in most cases you do not need custom environment variables for these libraries,
so we currently only support custom environment variables for some libraries.
If the library you need to customize environment variables is not listed above,
you can submit your request through [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues).
:::

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

@@ -0,0 +1,168 @@
# Extension 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 - Unable to use ssl](../faq/#unable-to-use-ssl).
## 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 like `native-native -dynamic` or `native-native-gnu`.
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, eg `./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 - Unable to use ssl](../faq/#unable-to-use-ssl).
## 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 - Unable to use ssl](../faq/#unable-to-use-ssl).
## 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, see [Compile PHP with GNU libc](./build-with-glibc).
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.

23
docs-v2/en/guide/extensions.md Normal file
View File

@@ -0,0 +1,23 @@
<script setup>
import SearchTable from "../../.vitepress/components/SearchTable.vue";
</script>
# Extensions
> - `yes`: supported
> - _blank_: not supported yet, or WIP
> - `no` with issue link: confirmed to be unavailable due to issue
> - `partial` with issue link: supported but not perfect due to issue
<search-table />
::: tip
If an extension you need is missing, you can create a [Feature Request](https://github.com/crazywhalecc/static-php-cli/issues).
Some extensions or libraries that the extension depends on will have some optional features.
For example, the gd library optionally supports libwebp, freetype, etc.
If you only use `bin/spc build gd --build-cli` they will not be included (static-php-cli defaults to the minimum dependency principle).
For more information about optional libraries, see [Extensions, Library Dependency Map](./deps-map).
For optional libraries, you can also select an extension from the [Command Generator](./cli-generator) and then select optional libraries.
:::

50
docs-v2/en/guide/index.md Normal file
View File

@@ -0,0 +1,50 @@
# Guide
Static php cli is a tool used to build statically compiled PHP binaries,
currently supporting Linux and macOS systems.
In the guide section, you will learn how to use static php cli to build standalone PHP programs.
- [Build (local)](./manual-build)
- [Build (GitHub Actions)](./action-build)
- [Supported Extensions](./extensions)
## Compilation Environment
The following is the architecture support situation, where :gear: represents support for GitHub Action build,
:computer: represents support for local manual build, and empty represents temporarily not supported.
| | x86_64 | aarch64 |
|---------|-------------------|-------------------|
| macOS | :gear: :computer: | :gear: :computer: |
| Linux | :gear: :computer: | :gear: :computer: |
| Windows | :gear: :computer: | |
| FreeBSD | :computer: | :computer: |
Current supported PHP versions for compilation:
> :warning: Partial support, there may be issues with new beta versions and old versions.
>
> :heavy_check_mark: Supported
>
> :x: Not supported
| PHP Version | Status | Comment |
|-------------|--------------------|-------------------------------------------------------------------------------------------------------------------------|
| 7.2 | :x: | |
| 7.3 | :x: | phpmicro and many extensions do not support 7.3, 7.4 versions |
| 7.4 | :x: | phpmicro and many extensions do not support 7.3, 7.4 versions |
| 8.0 | :warning: | PHP official has stopped maintaining 8.0, we no longer handle 8.0 related backport support |
| 8.1 | :warning: | PHP official only provides security updates for 8.1, we no longer handle 8.1 related backport support after 8.5 release |
| 8.2 | :heavy_check_mark: | |
| 8.3 | :heavy_check_mark: | |
| 8.4 | :heavy_check_mark: | |
| 8.5 (beta) | :warning: | PHP 8.5 is currently in beta stage |
> This table shows the support status of static-php-cli for building corresponding versions, not the PHP official support status for that version.
## PHP Support Versions
Currently, static-php-cli supports PHP versions 8.2 ~ 8.5, and theoretically supports PHP 8.1 and earlier versions, just select the earlier version when downloading.
However, due to some extensions and special components that have stopped supporting earlier versions of PHP, static-php-cli will not explicitly support earlier versions.
We recommend that you compile the latest PHP version possible for a better experience.

705
docs-v2/en/guide/manual-build.md Normal file
View File

@@ -0,0 +1,705 @@
---
outline: 'deep'
---
# Build (Linux, macOS, FreeBSD)
This section covers the build process for Linux, macOS, and FreeBSD. If you want to build on Windows,
also need to read [Build on Windows](./build-on-windows).
### Build locally (using SPC binary) (recommended)
This project provides a binary file of static-php-cli.
You can directly download the binary file of the corresponding platform and then use it to build static PHP.
Currently, the platforms supported by `spc` binary are Linux and macOS.
Here's how to download from self-hosted server:
```bash
# Download from self-hosted nightly builds (sync with main branch)
# For Linux x86_64
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
# For Linux aarch64
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
# macOS x86_64 (Intel)
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
# macOS aarch64 (Apple)
curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
# Windows (x86_64, win10 build 17063 or later)
curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
# Add execute perm (Linux and macOS only)
chmod +x ./spc
# Run (Linux and macOS)
./spc --version
# Run (Windows powershell)
.\spc.exe --version
```
> If you are using the packaged `spc` binary, you will need to replace the leading `bin/spc` with `./spc` in all the commands below.
### Build locally (using source code)
If you have problems using the spc binary, or if you need to modify the static-php-cli source code, download static-php-cli from the source code.
Currently, it supports building on macOS and Linux.
macOS supports the latest version of the operating system and two architectures,
while Linux supports Debian and derivative distributions, as well as Alpine Linux.
Because this project itself is developed using PHP,
it is also necessary to install PHP on the system during compilation.
This project also provides static binary PHP suitable for this project,
which can be selected and used according to actual situations.
```bash
# clone repo
git clone https://github.com/crazywhalecc/static-php-cli.git --depth=1
cd static-php-cli
# You need to install the PHP environment first before running Composer and this project. The installation method can be referred to below.
composer update
```
### Use Precompiled Static PHP Binaries
If you don't want to use Docker and install PHP in the system,
you can directly download the php binary cli program compiled by this project itself. The usage process is as follows:
Deploy the environment using the command, the command will download a static php-cli binary from [self-hosted server](https://dl.static-php.dev/static-php-cli/).
Next, it will automatically download Composer from [getcomposer](https://getcomposer.org/download/latest-stable/composer.phar) or [Aliyun mirror](https://mirrors.aliyun.com/composer/composer.phar).
::: tip
Using precompiled static PHP binaries is currently only supported on Linux and macOS.
The FreeBSD environment is currently not supported due to the lack of an automated build environment.
:::
```bash
bin/setup-runtime
# For users with special network environments such as mainland China, you can use mirror sites (aliyun) to speed up the download speed
bin/setup-runtime --mirror china
```
This script will download two files in total: `bin/php` and `bin/composer`. After the download is complete, there are two ways to use it:
1. Add the `bin/` directory to the PATH: `export PATH="/path/to/your/static-php-cli/bin:$PATH"`, after adding the path,
it is equivalent to installing PHP in the system, you can directly Use commands such as `composer`, `php -v`, or directly use `bin/spc`.
2. Direct call, such as executing static-php-cli command: `bin/php bin/spc --help`, executing Composer: `bin/php bin/composer update`.
### Use Docker
If you don't want to install PHP and Composer runtime environment on your system, you can use the built-in Docker environment build script.
```bash
# To use directly, replace `bin/spc` with `bin/spc-alpine-docker` in all used commands
bin/spc-alpine-docker
```
The first time the command is executed, `docker build` will be used to build a Docker image.
The default built Docker image is the `x86_64` architecture, and the image name is `cwcc-spc-x86_64`.
If you want to build `aarch64` static-php-cli in `x86_64` environment,
you can use qemu to emulate the arm image to run Docker, but the speed will be very slow.
Use command: `SPC_USE_ARCH=aarch64 bin/spc-alpine-docker`.
If it prompts that sudo is required to run after running,
execute the following command once to grant static-php-cli permission to execute sudo:
```bash
export SPC_USE_SUDO=yes
```
### Use System PHP
Below are some example commands for installing PHP and Composer in the system.
It is recommended to search for the specific installation method yourself or ask the AI search engine to obtain the answer,
which will not be elaborated here.
```bash
# [macOS], need install Homebrew first. See https://brew.sh/
# Remember change your composer executable path. For M1/M2 Chip mac, "/opt/homebrew/bin/", for Intel mac, "/usr/local/bin/". Or add it to your own path.
brew install php wget
wget https://getcomposer.org/download/latest-stable/composer.phar -O /path/to/your/bin/composer && chmod +x /path/to/your/bin/composer
# [Debian], you need to make sure your php version >= 8.1 and composer >= 2.0
sudo apt install php-cli composer php-tokenizer
# [Alpine]
apk add bash file wget xz php81 php81-common php81-pcntl php81-tokenizer php81-phar php81-posix php81-xml composer
```
::: tip
Currently, some versions of Ubuntu install older PHP versions,
so no installation commands are provided. If necessary, it is recommended to add software sources such as ppa first,
and then install the latest version of PHP and tokenizer, XML, and phar extensions.
Older versions of Debian may have an older (<= 7.4) version of PHP installed by default, it is recommended to upgrade Debian first.
:::
## Build with craft (recommended)
Using `bin/spc craft`, you can use a configuration file and a command to automatically check the environment, download source code, build dependency libraries, build PHP and extensions, etc.
You need to write a `craft.yml` file and save it in the current working directory. `craft.yml` can be generated by [command generator](./cli-generator) or written manually.
For manual writing, please refer to the comments in [craft.yml configuration](../develop/craft-yml.md) to write it.
Let's assume that you compile an extension combination and choose PHP 8.4, outputting `cli` and `fpm`:
```yaml
# path/to/craft.yml
php-version: 8.4
extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
sapi:
- cli
- fpm
```
Then use the `bin/spc craft` command to compile:
```bash
bin/spc craft --debug
```
If the build is successful, you will see the `buildroot/bin` directory in the current directory, which contains the compiled PHP binary file, or the corresponding SAPI.
- cli: The build result is `buildroot/bin/php.exe` on Windows and `buildroot/bin/php` on other platforms.
- fpm: The build result is `buildroot/bin/php-fpm`.
- micro: The build result is `buildroot/bin/micro.sfx`. If you need to further package it with PHP code, please refer to [Packaging micro binary](./manual-build#command-micro-combine).
- embed: See [Using embed](./manual-build#embed-usage).
- frankenphp: The build result is `buildroot/bin/frankenphp`.
If the build fails, you can use the `--debug` parameter to view detailed error information,
or use the `--with-clean` to clear the old compilation results and recompile.
If the build still fails to use the above method, please submit an issue and attach your `craft.yml` and `./log` archive.
## Step-by-step build command
If you have customized requirements, or the need to download and compile PHP and dependent libraries separately, you can use the `bin/spc` command to execute step by step.
### Command download - Download dependency packages
Use the command `bin/spc download` to download the source code required for compilation,
including php-src and the source code of various dependent libraries.
```bash
# Download all dependencies, defaults to php 8.4
bin/spc download --all
# Download all dependent packages, and specify the main version of PHP to download, optional: 8.1, 8.2, 8.3, 8.4
# Also supports specific version of php release: 8.3.10, 8.2.22, etc.
bin/spc download --all --with-php=8.3
# Show download progress bar while downloading (curl)
bin/spc download --all --debug
# Delete old download data
bin/spc download --clean
# Download specified dependencies
bin/spc download php-src,micro,zstd,ext-zstd
# Download only extensions and libraries to be compiled (use extensions, including suggested libraries)
bin/spc download --for-extensions=openssl,swoole,zip,pcntl,zstd
# Download resources, prefer to download dependencies with pre-built packages (reduce the time to compile dependencies)
bin/spc download --for-extensions="curl,pcntl,xml,mbstring" --prefer-pre-built
# Download only the extensions and dependent libraries to be compiled (use extensions, excluding suggested libraries)
bin/spc download --for-extensions=openssl,swoole,zip,pcntl --without-suggestions
# Download only libraries to be compiled (use libraries, including suggested libraries and required libraries, can use --for-extensions together)
bin/spc download --for-libs=liblz4,libevent --for-extensions=pcntl,rar,xml
# Download only libraries to be compiled (use libraries, excluding suggested libraries)
bin/spc download --for-libs=liblz4,libevent --without-suggestions
# When downloading sources, ignore some source caches (always force download, e.g. switching PHP version)
bin/spc download --for-extensions=curl,pcntl,xml --ignore-cache-sources=php-src --with-php=8.3.10
# Set retry times (default is 0)
bin/spc download --all --retry=2
```
If the network in your area is not good, or the speed of downloading the dependency package is too slow,
you can download `download.zip` which is packaged regularly every week from GitHub Action,
and use the command to directly use the zip archive as a dependency.
Dependent packages can be downloaded locally from [Action](https://github.com/static-php/static-php-cli-hosted/actions/workflows/download-cache.yml).
Enter Action and select the latest Workflow that has been successfully run, and download `download-files-x.y`.
```bash
bin/spc download --from-zip=/path/to/your/download.zip
```
If a source cannot be downloaded all the time, or you need to download some specific version of the package,
such as downloading the beta version of PHP, the old version of the library, etc.,
you can use the parameter `-U` or `--custom-url` to rewrite the download link,
Make the downloader force the link you specify to download packages from this source.
The method of use is `{source-name}:{url}`, which can rewrite the download URLs of multiple libraries at the same time.
Also, it is available when downloading with the `--for-extensions` option.
```bash
# Specifying to download a alpha version of PHP 8.5
bin/spc download --all -U "php-src:https://downloads.php.net/~edorian/php-8.5.0alpha2.tar.xz"
# Specifying to download an older version of the curl library
bin/spc download --all -U "curl:https://curl.se/download/curl-7.88.1.tar.gz"
```
If the source you download is not a link, but a git repository, you can use `-G` or `--custom-git` to rewrite the download link,
so that the downloader can force the use of the specified git repository to download packages from this source.
The usage method is `{source-name}:{branch}:{url}`, which can rewrite the download link of multiple libraries at the same time.
It is also available when downloading with the `--for-extensions` option.
```bash
# Specifying to download the source code of the PHP extension from the specified branch of the git repository
bin/spc download --for-extensions=redis -G "php-src:master:https://github.com/php/php-src.git"
# Download the latest code from the master branch of the swoole-src repository instead of PECL release version
bin/spc download --for-extensions=swoole -G "swoole:master:https://github.com/swoole/swoole-src.git"
```
### Command - doctor
If you can run `bin/spc` normally but cannot compile static PHP or dependent libraries normally,
you can run `bin/spc doctor` first to check whether the system itself lacks dependencies.
```bash
# Quick check
bin/spc doctor
# Quickly check and fix when it can be automatically repaired (use package management to install dependent packages, only support the above-mentioned operating systems and distributions)
bin/spc doctor --auto-fix
```
### Command - build
Use the build command to start building the static php binary.
Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
It is recommended to use `doctor` to check the environment.
#### Basic build
You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
and then use the command `bin/spc build` to compile.
You need to specify a compilation target, choose from the following parameters:
- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
- `--build-fpm`: Build a fpm sapi (php-fpm, used in conjunction with other traditional fpm architecture software such as nginx)
- `--build-cgi`: Build a cgi sapi (cgi, rarely used)
- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
- `--build-embed`: Build an embed sapi (used to embed into other C language programs)
- `--build-frankenphp`: Build a [FrankenPHP](https://github.com/php/frankenphp) executable
- `--build-all`: build all above sapi
```bash
# Compile PHP with bcmath,curl,openssl,ftp,posix,pcntl extensions, the compilation target is cli
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro
bin/spc build phar,curl,posix,pcntl,tokenizer --build-micro
```
::: tip
If you need to repeatedly build and debug, you can delete the `buildroot/` and `source/` directories so that you can re-extract and build all you need from the downloaded source code package:
```shell
# remove
rm -rf buildroot source
# build again
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
::: tip
If you want to build multiple versions of PHP and don't want to build other dependent libraries repeatedly each time,
you can use `switch-php-version` to quickly switch to another version and compile after compiling one version:
```shell
# switch to 8.4
bin/spc switch-php-version 8.4
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# switch to 8.1
bin/spc switch-php-version 8.1
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
#### Build Options
During the compilation process, in some special cases,
the compiler and the content of the compilation directory need to be intervened.
You can try to use the following commands:
- `--cc=XXX`: Specifies the execution command of the C language compiler (Linux default `musl-gcc` or `gcc`, macOS default `clang`)
- `--cxx=XXX`: Specifies the execution command of the C++ language compiler (Linux defaults to `g++`, macOS defaults to `clang++`)
- `--with-clean`: clean up old make files before compiling PHP
- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
- `--no-strip`: Do not run `strip` after compiling the PHP library to trim the binary file to reduce its size
- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extended optional functions (such as libavif of the gd library, etc.)
- `--with-config-file-path=XXX`: Set the path in which to look for `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
- `--with-config-file-scan-dir=XXX`: Set the directory to scan for `.ini` files after reading `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
- `-P xxx.php`: Inject external scripts during static-php-cli compilation (see **Inject external scripts** below for details)
- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
- `--build-shared=XXX,YYY`: compile the specified extension into a shared library (the default is to compile into a static library)
For hardcoding INI options, it works for cli, micro, embed sapi. Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
```bash
bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
```
## Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
## Command - micro:combine
Use the `micro:combine` command to build the compiled `micro.sfx` and your code (`.php` or `.phar` file) into an executable binary.
You can also use this command to directly build a micro binary injected with ini configuration.
::: tip
Injecting ini configuration refers to adding a special structure after micro.sfx to save ini configuration items before combining micro.sfx with PHP source code.
micro.sfx can identify the INI file header through a special byte, and the micro can be started with INI through the INI file header.
The original wiki of this feature is in [phpmicro - Wiki](https://github.com/easysoft/phpmicro/wiki/INI-settings), and this feature may change in the future.
:::
The following is the general usage, directly packaging the php source code into a file:
```bash
# Before doing the packaging process, you should use `build --build-micro` to compile micro.sfx
echo "<?php echo 'hello';" > a.php
bin/spc micro:combine a.php
# Just use it
./my-app
```
You can use the following options to specify the file name to be output, and you can also specify micro.sfx in other paths for packaging.
```bash
# specify the output filename
bin/spc micro:combine a.php --output=custom-bin
# Use absolute path
bin/spc micro:combine a.php -O /tmp/my-custom-app
# Specify micro.sfx in other locations for packaging
bin/spc micro:combine a.app --with-micro=/path/to/your/micro.sfx
```
If you want to inject ini configuration items, you can use the following parameters to add ini to the executable file from a file or command line option.
```bash
# Specified using command-line options (-I is shorthand for --with-ini-set)
bin/spc micro:combine a.php -I "a=b" -I "foo=bar"
# Use ini file specification (-N is shorthand for --with-ini-file)
bin/spc micro:combine a.php -N /path/to/your/custom.ini
```
::: warning
Note, please do not directly use the PHP source code or the `php.ini` file in the system-installed PHP,
it is best to manually write an ini configuration file that you need, for example:
```ini
; custom.ini
curl.cainfo=/path/to/your/cafile.pem
memory_limit=1G
```
The ini injection of this command is achieved by appending a special structure after micro.sfx,
which is different from the function of inserting hard-coded INI during compilation.
:::
If you want to package phar, just replace `a.php` with the packaged phar file.
But please note that micro.sfx under phar needs extra attention to the path problem, see [Developing - Phar directory issue](../develop/structure#phar-application-directory-issue).
## Command - extract
Use the command `bin/spc extract` to unpack and copy the source code required for compilation,
including php-src and the source code of various dependent libraries (you need to specify the name of the library to be unpacked).
For example, after we have downloaded sources, we want to distribute and execute the build process,
manually unpack and copy the package to a specified location, and we can use commands.
```bash
# Unzip the downloaded compressed package of php-src and libxml2, and store the decompressed source code in the source directory
bin/spc extract php-src,libxml2
```
## Command - dump-extensions
Use the command `bin/spc dump-extensions` to export required extensions of the current project.
```bash
# Print the extension list of the project, pass in the root directory of the project containing composer.json
bin/spc dump-extensions /path/to/your/project/
# Print the extension list of the project, excluding development dependencies
bin/spc dump-extensions /path-to/tour/project/ --no-dev
# Output in the extension list format acceptable to the spc command (comma separated)
bin/spc dump-extensions /path-to/tour/project/ --format=text
# Output as a JSON list
bin/spc dump-extensions /path-to/tour/project/ --format=json
# When the project does not have any extensions, output the specified extension combination instead of returning failure
bin/spc dump-extensions /path-to/your/project/ --no-ext-output=mbstring,posix,pcntl,phar
# Do not exclude extensions not supported by spc when outputting
bin/spc dump-extensions /path/to/your/project/ --no-spc-filter
```
It should be noted that the project directory must contain the `vendor/installed.json` and `composer.lock` files, otherwise they cannot be found normally.
## Dev Command - dev
Debug commands refer to a collection of commands that can assist in outputting some information
when you use static-php-cli to build PHP or modify and enhance the static-php-cli project itself.
- `dev:extensions`: output all currently supported extension names, or output the specified extension information
- `dev:php-version`: output the currently compiled PHP version (by reading `php_version.h`)
- `dev:sort-config`: Sort the list of configuration files in the `config/` directory in alphabetical order
- `dev:lib-ver <lib-name>`: Read the version from the source code of the dependency library (only available for specific dependency libraries)
- `dev:ext-ver <ext-name>`: Read the corresponding version from the source code of the extension (only available for specific extensions)
- `dev:pack-lib <lib-name>`: Package the specified library into a tar.gz file (maintainer only)
- `dev:gen-ext-docs`: Generate extension documentation (maintainer only)
```bash
# output all extensions information
bin/spc dev:extensions
# Output the meta information of the specified extension
bin/spc dev:extensions mongodb,curl,openssl
# Output the specified columns
# Available column name: lib-depends, lib-suggests, ext-depends, ext-suggests, unix-only, type
bin/spc dev:extensions --columns=lib-depends,type,ext-depends
# Output the currently compiled PHP version
# You need to decompress the downloaded PHP source code to the source directory first
# You can use `bin/spc extract php-src` to decompress the source code separately
bin/spc dev:php-version
# Sort the configuration files in the config/ directory in alphabetical order (e.g. ext.json)
bin/spc dev:sort-config ext
```
## Command - install-pkg
Use the command `bin/spc install-pkg` to download some precompiled or closed source tools and install them into the `pkgroot` directory.
When `bin/spc doctor` automatically repairs the Windows environment, tools such as nasm and perl will be downloaded, and the installation process of `install-pkg` will also be used.
Here is an example of installing the tool:
- Download and install UPX (Linux and Windows only): `bin/spc install-pkg upx`
- Download and install nasm (Windows only): `bin/spc install-pkg nasm`
- Download and install go-xcaddy: `bin/spc install-pkg go-xcaddy`
## Command - del-download
In some cases, you need to delete single or multiple specified download source files and re-download them, such as switching PHP versions.
The `bin/spc del-download` command is provided after the `2.1.0-beta.4` version. Specified source files can be deleted.
Deletes downloaded source files containing precompiled packages and source code named as keys in `source.json` or `pkg.json`. Here are some examples:
- Delete the old PHP source code and switch to download the 8.3 version: `bin/spc del-download php-src && bin/spc download php-src --with-php=8.3`
- Delete the download file of redis extension: `bin/spc del-download redis`
- Delete the downloaded musl-toolchain x86_64: `bin/spc del-download musl-toolchain-x86_64-linux`
## Inject External Script
Injecting external scripts refers to inserting one or more scripts during the static-php-cli compilation process
to more flexibly support parameter modifications and source code patches in different environments.
Under normal circumstances, this function mainly solves the problem that the patch cannot be modified
by modifying the static-php-cli code when compiling with `spc` binary.
There is another situation: your project directly depends on the `crazywhalecc/static-php-cli` repository and is synchronized with main branch,
but some proprietary modifications are required, and these feature are not suitable for merging into the main branch.
In view of the above situation, in the official version 2.0.0, static-php-cli has added multiple event trigger points.
You can write an external `xx.php` script and pass it in through the command line parameter `-P` and execute.
When writing to inject external scripts, the methods you will use are `builder()` and `patch_point()`.
Among them, `patch_point()` obtains the name of the current event, and `builder()` obtains the BuilderBase object.
Because the incoming patch point does not distinguish between events,
you must write the code you want to execute in `if(patch_point() === 'your_event_name')`,
otherwise it will be executed repeatedly in other events.
The following are the supported `patch_point` event names and corresponding locations:
| Event name | Event description |
|---------------------------------|----------------------------------------------------------------------------------------------------|
| before-libs-extract | Triggered before the dependent libraries extracted |
| after-libs-extract | Triggered after the compiled dependent libraries extracted |
| before-php-extract | Triggered before PHP source code extracted |
| after-php-extract | Triggered after PHP source code extracted |
| before-micro-extract | Triggered before phpmicro extract |
| after-micro-extract | Triggered after phpmicro extracted |
| before-exts-extract | Triggered before the extension (to be compiled) extracted to the PHP source directory |
| after-exts-extract | Triggered after the extension extracted to the PHP source directory |
| before-library[*name*]-build | Triggered before the library named `name` is compiled (such as `before-library[postgresql]-build`) |
| after-library[*name*]-build | Triggered after the library named `name` is compiled |
| after-shared-ext[*name*]-build | Triggered after the shared extension named `name` is compiled |
| before-shared-ext[*name*]-build | Triggered before the shared extension named `name` is compiled |
| before-php-buildconf | Triggered before compiling PHP command `./buildconf` |
| before-php-configure | Triggered before compiling PHP command `./configure` |
| before-php-make | Triggered before compiling PHP command `make` |
| before-sanity-check | Triggered after compiling PHP but before running extended checks |
The following is a simple example of temporarily modifying the PHP source code.
Enable the CLI function to search for the `php.ini` configuration in the current working directory:
```php
// a.php
<?php
// patch it before `./buildconf` executed
if (patch_point() === 'before-php-buildconf') {
\SPC\store\FileSystem::replaceFileStr(
SOURCE_PATH . '/php-src/sapi/cli/php_cli.c',
'sapi_module->php_ini_ignore_cwd = 1;',
'sapi_module->php_ini_ignore_cwd = 0;'
);
}
```
```bash
bin/spc build mbstring --build-cli -P a.php
# Write in ./
echo 'memory_limit=8G' > ./php.ini
```
```
$ buildroot/bin/php -i | grep Loaded
Loaded Configuration File => /Users/jerry/project/git-project/static-php-cli/php.ini
$ buildroot/bin/php -i | grep memory
memory_limit => 8G => 8G
```
For the objects, methods and interfaces supported by static-php-cli, you can read the source code. Most methods and objects have corresponding comments.
Commonly used objects and functions using the `-P` function are:
- `SPC\store\FileSystem`: file management class
- `::replaceFileStr(string $filename, string $search, $replace)`: Replace file string content
- `::replaceFileStr(string $filename, string $pattern, $replace)`: Regularly replace file content
- `::replaceFileUser(string $filename, $callback)`: User-defined function replaces file content
- `::copyDir(string $from, string $to)`: Recursively copy a directory to another location
- `::convertPath(string $path)`: Convert the path delimiter to the current system delimiter
- `::scanDirFiles(string $dir, bool $recursive = true, bool|string $relative = false, bool $include_dir = false)`: Traverse directory files
- `SPC\builder\BuilderBase`: Build object
- `->getPatchPoint()`: Get the current injection point name
- `->getOption(string $key, $default = null)`: Get command line and compile-time options
- `->getPHPVersionID()`: Get the currently compiled PHP version ID
- `->getPHPVersion()`: Get the currently compiled PHP version number
- `->setOption(string $key, $value)`: Set options
- `->setOptionIfNotExists(string $key, $value)`: Set option if option does not exist
::: tip
static-php-cli has many open methods, which cannot be listed in the docs,
but as long as it is a `public function` and is not marked as `@internal`, it theoretically can be called.
:::
## Multiple builds
If you need to build multiple times locally, the following method can save you time downloading resources and compiling.
- If you only switch the PHP version without changing the dependent libraries, you can use `bin/spc switch-php-version` to quickly switch the PHP version, and then re-run the same `build` command.
- If you want to rebuild once, but do not re-download the source code, you can first `rm -rf buildroot source` to delete the compilation directory and source code directory, and then rebuild.
- If you want to update a version of a dependency, you can use `bin/spc del-download <source-name>` to delete the specified source code, and then use `download <source-name>` to download it again.
- If you want to update all dependent versions, you can use `bin/spc download --clean` to delete all downloaded sources, and then download them again.
## embed usage
If you want to embed static-php into other C language programs, you can use `--build-embed` to build an embed version of PHP.
```bash
bin/spc build {your extensions} --build-embed --debug
```
Under normal circumstances, PHP embed will generate `php-config` after compilation.
For static-php, we provide `spc-config` to obtain the parameters during compilation.
In addition, when using embed SAPI (libphp.a), you need to use the same compiler as libphp, otherwise there will be a link error.
Here is the basic usage of spc-config:
```bash
# output all flags and options
bin/spc spc-config curl,zlib,phar,openssl
# output libs
bin/spc spc-config curl,zlib,phar,openssl --libs
# output includes
bin/spc spc-config curl,zlib,phar,openssl --includes
```
By default, static-php uses the following compilers on different systems:
- macOS: `clang`
- Linux (Alpine Linux): `gcc`
- Linux (glibc based distros, x86_64): `/usr/local/musl/bin/x86_64-linux-musl-gcc`
- Linux (glibc based distros, aarch64): `/usr/local/musl/bin/aarch64-linux-musl-gcc`
- FreeBSD: `clang`
Here is an example of using embed SAPI:
```c
// embed.c
#include <sapi/embed/php_embed.h>
int main(int argc,char **argv){
PHP_EMBED_START_BLOCK(argc,argv)
zend_file_handle file_handle;
zend_stream_init_filename(&file_handle,"embed.php");
if(php_execute_script(&file_handle) == FAILURE){
php_printf("Failed to execute PHP script.\n");
}
PHP_EMBED_END_BLOCK()
return 0;
}
```
```php
<?php
// embed.php
echo "Hello world!\n";
```
```bash
# compile in debian/ubuntu x86_64
/usr/local/musl/bin/x86_64-linux-musl-gcc embed.c $(bin/spc spc-config bcmath,zlib) -static -o embed
# compile in macOS/FreeBSD
clang embed.c $(bin/spc spc-config bcmath,zlib) -o embed
./embed
# out: Hello world!
```

42
docs-v2/en/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,42 @@
# Troubleshooting
Various failures may be encountered in the process of using static-php-cli,
here will describe how to check the errors by yourself and report 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 `--debug` 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 `--debug` 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 [Local Build - Multiple Builds](./manual-build#multiple-builds) section.