### Setup Runtime for Source Installation (Linux/macOS)

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this script to install a self-contained PHP and Composer runtime for building from source on Linux or macOS.

```bash
bin/setup-runtime
```

--------------------------------

### Setup Runtime for Source Installation (Windows)

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this script to install a self-contained PHP and Composer runtime for building from source on Windows. Optionally add the runtime to your PATH.

```powershell
.\bin\setup-runtime.ps1
.\bin\setup-runtime.ps1 add-path   # add runtime/ to PATH
```

--------------------------------

### Build a Single Library

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Example of building a single library package, such as OpenSSL.

```bash
spc build:libs openssl
```

--------------------------------

### Start PHP-FPM with Custom Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Starts the PHP-FPM process using a specified configuration file and INI file. This is useful for custom environments.

```bash
./buildroot/bin/php-fpm -c /path/to/php.ini -y /path/to/php-fpm.conf
```

--------------------------------

### phpmicro Example

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/index.md

Demonstrates how to combine a phpmicro executable with a PHP archive to create a single-file application.

```bash
micro.sfx + your-app.phar = your-app   # one file, zero dependencies
```

--------------------------------

### Install Helper Package

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Installs a specified helper package, such as UPX or a toolchain. This command is aliased to 'i' and 'install-package' for convenience.

```bash
spc install-pkg upx
```

--------------------------------

### Verify StaticPHP Setup

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/index.md

Verify that the StaticPHP setup is successful by checking its version.

```bash
bin/spc --version
```

--------------------------------

### Build Multiple Libraries

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Example of building multiple library packages, such as OpenSSL, cURL, and zlib, by providing a comma-separated list.

```bash
spc build:libs "openssl,curl,zlib"
```

--------------------------------

### Example openssl Library Package Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/package-model.md

This is an example configuration for the openssl library package, demonstrating the use of 'ghrel' artifact source and platform-specific dependencies and static libraries.

```yaml
openssl:
  type: library
  artifact:
    source:
      type: ghrel
      repo: openssl/openssl
      match: openssl.+\.tar\.gz
      prefer-stable: true
    binary: hosted
    metadata:
      license-files: [LICENSE.txt]
      license: OpenSSL
  depends:
    - zlib
  depends@windows:
    - zlib
    - jom
  headers:
    - openssl
  static-libs@unix:
    - libssl.a
    - libcrypto.a
  static-libs@windows:
    - libssl.lib
    - libcrypto.lib
```

--------------------------------

### FrankenPHP Usage Examples

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Demonstrates common commands for using the built FrankenPHP binary, including checking the version, running the development server, and executing with a Caddyfile.

```bash
# Check version
./buildroot/bin/frankenphp version
```

```bash
# Run in PHP development server mode
./buildroot/bin/frankenphp php-server
```

```bash
# Run with a Caddyfile
./buildroot/bin/frankenphp run --config /path/to/Caddyfile
```

--------------------------------

### Build PHP CLI with a Specific Version

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

This example shows how to build the PHP CLI with specific extensions, targeting a particular PHP version for the download.

```bash
spc build:php "bcmath,openssl" --build-cli --dl-with-php=8.3
```

--------------------------------

### Build PHP with Suggested Packages

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Resolves and installs suggested packages automatically alongside the PHP build.

```bash
spc build:php --with-suggests
```

--------------------------------

### Install PHP Dependencies

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/index.md

Install the necessary PHP dependencies for StaticPHP development using Composer.

```bash
composer install
```

--------------------------------

### Example php-fpm.conf Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

A sample php-fpm.conf file demonstrating global settings and pool configuration for the 'www' pool, including PID, logging, and process management.

```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
```

--------------------------------

### Example php-extension Package Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/package-model.md

This is an example of a php-extension package configuration for the lz4 extension. It specifies the source repository, dependencies, and platform-specific build arguments for Unix and Windows.

```yaml
ext-lz4:
  type: php-extension
  artifact:
    source:
      type: git
      url: 'https://github.com/kjdev/php-ext-lz4.git'
      rev: master
      extract: php-src/ext/lz4
    metadata:
      license-files: [LICENSE]
      license: MIT
  depends:
    - liblz4
  php-extension:
    arg-type@unix: '--enable-lz4=@shared_suffix@ --with-lz4-includedir=@build_root_path@'
    arg-type@windows: '--enable-lz4'
```

--------------------------------

### Build PHP with Additional Packages

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Installs specified additional packages along with the PHP build.

```bash
spc build:php --with-packages=<list>
```

--------------------------------

### Start Interactive PHP Mode

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Launch an interactive PHP shell session using the CLI binary.

```bash
./buildroot/bin/php -a
```

--------------------------------

### Build PHP with UPX Packing

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Compresses the output binary using UPX. Ensure UPX is installed first (`spc install-pkg upx`). This option is available on Linux and Windows.

```bash
spc build:php --with-upx-pack
```

--------------------------------

### Build PHP CLI with Debug Symbols

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

This example builds the PHP CLI SAPI with extensions and retains debug symbols by skipping the stripping process.

```bash
spc build:php "bcmath,openssl" --build-cli --no-strip
```

--------------------------------

### Run a One-Shot Static PHP Build

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Execute the `spc craft` command to automatically download dependencies, compile libraries, and build the PHP binary. This is the recommended approach for everyday use and quick starts.

```bash
spc craft
```

--------------------------------

### Test PHP-FPM Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Tests the syntax and validity of the PHP-FPM configuration files before starting the service. This helps catch errors early.

```bash
./buildroot/bin/php-fpm -t
```

--------------------------------

### Download Static PHP CLI Binary

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/README.md

Download the appropriate Static PHP CLI binary for your operating system and architecture. Ensure you have curl installed.

```bash
# For Linux x86_64
curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
```

```bash
# For Linux aarch64
curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64
```

```bash
# macOS x86_64 (Intel)
curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64
```

```bash
# macOS aarch64 (Apple)
curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64
```

```bash
# Windows (x86_64, win10 build 17063 or later, please install VS2022 first)
curl.exe -fsSL -o spc.exe https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x64.exe
```

--------------------------------

### Complete Registry Declaration Example

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/registry.md

This YAML snippet shows all available fields for configuring a StaticPHP registry. It includes settings for name, autoload, package, artifact, doctor, and command configurations.

```yaml
# [Required] Unique registry name; loading a registry with a duplicate name is automatically skipped
name: my-registry

# [Optional] Composer autoload file path, used when an external registry has its own dependencies
autoload: vendor/autoload.php

# Package (library / php-extension / target) related configuration
package:
  # YAML configuration file directory or specific file paths for packages, can be an array
  config:
    - config/pkg/lib/
    - config/pkg/target/
    - config/pkg/ext/
  # PSR-4 namespace → directory path mapping for package build classes; the loader scans all PHP classes in the directory
  psr-4:
    Package: src/Package
  # You can also load specific classes as needed, supporting array format or {"ClassName": "file path"} mapping
  # classes:
  #   - Package\Library\MyLib
  #   MyLib: src/Package/Library/MyLib.php

# Artifact (build artifact) related configuration
artifact:
  # YAML configuration file directory or specific file paths for artifacts
  config:
    - config/artifact/
  # PSR-4 namespace → directory path mapping for custom artifact download/extract classes
  psr-4:
    Package\Artifact: src/Package/Artifact
  # classes: ... (same format as package.classes)

# Doctor environment check configuration
doctor:
  # PSR-4 namespace → directory path mapping for Doctor check item classes
  psr-4:
    StaticPHP\Doctor\Item: src/StaticPHP/Doctor/Item
  # classes: ... (same format as package.classes)

# Additional CLI command configuration
command:
  # PSR-4 namespace → directory path mapping for custom command classes
  psr-4:
    Package\Command: src/Package/Command
  # classes: ... (same format as package.classes)

```

--------------------------------

### Direct URL Download Shortcut

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/artifact-model.md

A bare string starting with 'http://' or 'https://' is automatically expanded into a 'type: url' object, simplifying direct URL downloads.

```yaml
artifact:
  source: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'
```

--------------------------------

### Reset Build Artifacts and Rebuild

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Wipe compiled artifacts from the `buildroot/` and `source/` directories to start a fresh build without re-downloading. This is useful when a build fails or you need to ensure a clean state.

```bash
spc reset
# Then rebuild
spc build:php "bcmath,openssl" --build-cli
```

--------------------------------

### Build static PHP with shared extensions on macOS

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/faq/index.md

On macOS, you can build statically compiled PHP binaries that support dynamically linked extensions. This example shows how to build a shared extension like `xdebug.so`.

```bash
spc build:php "bcmath,zlib" --build-shared=xdebug --build-cli
```

--------------------------------

### Combine PHP Script into Micro Executable

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Combines a PHP script into a standalone executable using the micro SAPI. The resulting executable can be run without a separate PHP installation.

```bash
# Bundle a PHP script
echo "<?php echo 'Hello, World!' . PHP_EOL;?>" > hello.php
spc micro:combine hello.php --output=hello
./hello
```

--------------------------------

### Build Libraries with Suggested Packages

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Build a library package and include its suggested packages by using the `--with-suggests` option.

```bash
spc build:libs openssl --with-suggests
```

--------------------------------

### Download Pre-built Binary for Windows x86_64

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this command to download the StaticPHP CLI binary for Windows x86_64 systems.

```powershell
curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe -o spc.exe
```

--------------------------------

### Make Binary Executable and Verify Version

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

After downloading the binary on Linux or macOS, make it executable and check the version.

```bash
chmod +x spc && ./spc --version
```

--------------------------------

### Build PHP from Source

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Use this command to compile PHP and extensions from source. Specify the required comma-separated list of extensions to compile statically.

```bash
spc build:php <extensions> [options]
```

--------------------------------

### Nginx Configuration for PHP-FPM

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Example Nginx server block configuration to proxy PHP requests to a PHP-FPM instance listening on localhost:9000.

```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;
    }
}
```

--------------------------------

### Require StaticPHP CLI as Composer Dependency

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Install the StaticPHP CLI as a Composer dependency in your existing PHP project for vendor mode integration.

```bash
composer require crazywhalecc/static-php-cli
```

--------------------------------

### Build micro.sfx as Win32 GUI App

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Builds the `micro.sfx` binary as a Win32 GUI application instead of a console application. This option is only applicable on Windows.

```bash
spc build:php --enable-micro-win32
```

--------------------------------

### Download Pre-built Binary for Linux arm64

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this command to download the StaticPHP CLI binary for Linux arm64 systems.

```shell
curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64 -o spc
```

--------------------------------

### Download Pre-built Binary for Linux x86_64

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this command to download the StaticPHP CLI binary for Linux x86_64 systems.

```shell
curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64 -o spc
```

--------------------------------

### Build static PHP with FFI and load Xdebug extension

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/faq/index.md

This command builds a static PHP binary dynamically linked against glibc, supporting FFI extensions. It allows loading the `xdebug.so` extension for the same PHP version and thread-safe type. No Docker or extra cross-compilation toolchain is required.

```bash
SPC_TARGET=native-native-gnu.2.17 spc build:php "ffi,xml" --build-cli -vvv
```

```bash
buildroot/bin/php -d "zend_extension=/path/to/php{PHP_VER}-{ts/nts}/xdebug.so" --ri xdebug
```

--------------------------------

### Attempt Automatic Fix for Missing Build Tools

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use the '--auto-fix' flag with the 'doctor' command to automatically install any missing required build tools.

```bash
./spc doctor --auto-fix
```

--------------------------------

### Build micro.sfx

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Builds the `micro.sfx` executable, a self-contained PHP binary.

```bash
spc build:php --build-micro
```

--------------------------------

### Build PHP with Micro SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Builds a PHP binary with the micro SAPI, suitable for creating self-contained executables. Includes specified extensions like 'phar'. The output binary is named 'micro.sfx'.

```bash
spc build:php "bcmath,phar,openssl,curl" --build-micro
```

--------------------------------

### v2 vs v3 Build Command Equivalents

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/migrate-from-v2.md

Use dedicated single-target commands in v3 instead of the generic `build` command with SAPI selection flags.

```bash
spc build exts --build-cli
```

```bash
spc build:php-cli exts
```

```bash
spc build exts --build-fpm
```

```bash
spc build:php-fpm exts
```

```bash
spc build exts --build-cgi
```

```bash
spc build:php-cgi exts
```

```bash
spc build exts --build-micro
```

```bash
spc build:php-micro exts
```

```bash
spc build exts --build-embed
```

```bash
spc build:php-embed exts
```

```bash
spc build exts --build-frankenphp
```

```bash
spc build:frankenphp exts
```

--------------------------------

### Download Dependencies Preferring Pre-built Binaries

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Utilize pre-built binaries where available to skip compilation for those dependencies, speeding up the build process.

```bash
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary
```

--------------------------------

### Download Pre-built Binary for macOS arm64

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this command to download the StaticPHP CLI binary for macOS arm64 systems.

```shell
curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64 -o spc
```

--------------------------------

### Build Library Packages

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Build one or more library packages from source. Specify the libraries as a comma-separated list. All download options are available with the `--dl-` prefix.

```bash
spc build:libs <libraries> [options]
```

--------------------------------

### Package Referencing a URL Artifact

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/package-model.md

This YAML example demonstrates how a 'library' type package can reference an external source archive via a URL. The 'artifact' field specifies the download source type and its URL.

```yaml
example-library-package:
  type: library
  artifact:
    source:
      type: url
      url: 'https://example.com/example-library.tar.gz'

```

--------------------------------

### Combine with Custom Micro.sfx

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Uses a custom path to the micro.sfx stub instead of the default one. This is helpful when you need to use a specific version or a modified stub.

```bash
spc micro:combine app.php --with-micro=/path/to/micro.sfx
```

--------------------------------

### Download Pre-built Binary for macOS x86_64

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Use this command to download the StaticPHP CLI binary for macOS x86_64 systems.

```shell
curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64 -o spc
```

--------------------------------

### Debug Build Process with Verbose Logging

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Use verbose flags (`-v`, `-vv`, `-vvv`) to get detailed logs during the PHP build process. This helps in diagnosing build failures and understanding internal operations.

```bash
spc build:php "bcmath,openssl" --build-cli -vv
```

--------------------------------

### Reset Build Environment

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Cleans build directories. By default, removes 'buildroot/' and 'source/'. Use options to include 'pkgroot/' and 'downloads/'. The '--yes' flag skips confirmation.

```bash
spc reset [options]
```

```bash
# Clean build directories (will prompt for confirmation)
spc reset
```

```bash
# Also clear the download cache
spc reset --with-download
```

```bash
# Full clean without prompting
spc reset --with-pkgroot --with-download --yes
```

--------------------------------

### Build PHP with Custom Config Path

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Specifies a custom directory for PHP to look for the `php.ini` configuration file.

```bash
spc build:php --with-config-file-path=<path>
```

--------------------------------

### Build PHP with FPM SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Builds a PHP binary with the FPM SAPI enabled, including specified extensions. The output binary is named 'php-fpm'.

```bash
spc build:php "bcmath,openssl,curl,pdo_mysql" --build-fpm
```

--------------------------------

### Run Full Build Pipeline with craft.yml

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Execute the full build pipeline by running the 'craft' command. It reads configuration from a 'craft.yml' file. If no path is provided, it defaults to the current working directory.

```bash
spc craft [path/to/craft.yml]
```

--------------------------------

### Run a PHP Script

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Execute a PHP script using the built CLI binary.

```bash
./buildroot/bin/php your-script.php
```

--------------------------------

### Download Dependencies for Extensions

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Download only the necessary artifacts for specified extensions. This is recommended for efficient builds. Requires PHP version 8.5.

```bash
spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.5
```

```bash
spc download "curl,openssl" --with-php=8.5
```

--------------------------------

### Build PHP CLI with Extensions and Download Options

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

This command builds the PHP CLI SAPI with specified extensions, using a particular PHP version and preferring binary downloads for dependencies. It also sets the number of parallel downloads.

```bash
spc build:php "bcmath,openssl,curl" --build-cli --dl-with-php=8.3 --dl-prefer-binary --dl-parallel=4
```

--------------------------------

### Build Static PHP Binary

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/README.md

Execute the 'spc craft' command to build your custom static PHP binary based on the craft.yml configuration. Use '-vvv' for a full console log.

```bash
./spc craft
```

```bash
# Output full console log
./spc craft -vvv
```

--------------------------------

### Configure micro.sfx to Report CLI SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Forces the `micro.sfx` binary to report its SAPI as `cli` instead of `micro`.

```bash
spc build:php --with-micro-fake-cli
```

--------------------------------

### Build PHP CLI and Micro SAPI Together

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

This command builds both the CLI and Micro SAPIs simultaneously, along with specified extensions.

```bash
spc build:php "bcmath,phar,openssl,curl" --build-cli --build-micro
```

--------------------------------

### Automatic Dependency Download in v3 Build Commands

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/migrate-from-v2.md

In v3, `build:*` commands automatically download dependencies. Use `--no-download` to opt out.

```bash
# v2 — two steps required
spc download --for-extensions=curl,gd
spc build curl,gd --build-cli
```

```bash
# v3 — one step is enough
spc build:php-cli curl,gd
```

```bash
spc build:php-cli curl,gd --no-download
```

--------------------------------

### Create and Run Static PHP Micro Application

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/README.md

Combine a PHP script into a self-contained micro-application using 'spc micro:combine'. The resulting binary can be executed directly.

```bash
# phpmicro
echo '<?php echo "Hello world!\n";' > a.php
./spc micro:combine a.php -O my-app
./my-app
```

--------------------------------

### Call PHP and Composer Directly from Runtime

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/installation.md

Execute PHP and Composer commands directly using their paths within the runtime directory, useful when not adding runtime to PATH.

```bash
runtime/php bin/spc --help
runtime/php runtime/composer install
```

--------------------------------

### Build PHP CLI SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Build the standard PHP command-line binary with specified extensions. The output path depends on the operating system.

```bash
spc build:php "bcmath,openssl,curl" --build-cli
```

--------------------------------

### Build gd Extension with Specific Libraries

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/extension-notes.md

Use this command to build the gd extension with support for freetype, libjpeg, libavif, and libwebp. The `--build-cli` flag is included.

```bash
bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
```

--------------------------------

### Migrate build command options from v2 to v3

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/migrate-from-v2.md

Shows the conversion of a v2 build command using deprecated and removed flags to their v3 equivalents. Update your scripts to use the new option names for compatibility.

```bash
# v2
spc build curl,gd --build-cli --with-libs="openssl" -L -E

# v3
spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
```

--------------------------------

### Smoke-test the Static PHP CLI Binary

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

After a successful build, verify the generated CLI binary by checking its version and loaded modules. The binaries are located in the `buildroot/bin/` directory.

```bash
./buildroot/bin/php -v
./buildroot/bin/php -m
```

--------------------------------

### Download specific artifacts

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Download a precise list of artifacts, such as PHP source and OpenSSL.

```bash
spc download "php-src,openssl"
```

--------------------------------

### Enable Dynamic Extension Loading on Linux

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Set the SPC_TARGET environment variable to 'native-native-gnu.2.17' before building to enable dynamic linking against glibc 2.17, which supports dl(), FFI, and .so extensions.

```bash
SPC_TARGET=native-native-gnu.2.17 spc build:php "bcmath,openssl" --build-cli
```

--------------------------------

### Create craft.yml Configuration

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/README.md

Define your PHP version and desired extensions in a craft.yml file. Supported PHP versions include 8.1 through 8.5.

```yaml
# PHP version support: 8.1, 8.2, 8.3, 8.4, 8.5
php-version: 8.5
# Put your extension list here
extensions: "apcu,bcmath,calendar,ctype,curl,dba,dom,exif,fileinfo,filter,gd,iconv,mbregex,mbstring,mysqli,mysqlnd,opcache,openssl,pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,readline,redis,session,simplexml,sockets,sodium,sqlite3,tokenizer,xml,xmlreader,xmlwriter,xsl,zip,zlib"
sapi:
  - cli
  - micro
download-options:
  parallel: 10
```

--------------------------------

### Run Static PHP CLI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/README.md

Execute the built static PHP CLI binary to check its version. This binary has no external dependencies.

```bash
# php-cli
buildroot/bin/php -v
```

--------------------------------

### Build PHP with CLI SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Builds the PHP Command Line Interface (CLI) SAPI. This is the default SAPI if none are specified.

```bash
spc build:php --build-cli
```

--------------------------------

### Use Local Directory as Source

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/artifact-model.md

Uses a pre-existing local directory as the source without downloading. Ideal for offline environments or local development where the source is already present. Requires the absolute path to the local directory.

```yaml
artifact:
  source:
    type: local
    dirname: /path/to/local/source
```

--------------------------------

### Build PHP CLI with Hard-coded INI Settings

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Build the PHP CLI binary with specific INI settings baked directly into the binary, eliminating the need for an external php.ini file. This is useful for ensuring consistent configurations.

```bash
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system,exec"
```

--------------------------------

### Download `spc` Binary (v2 vs v3)

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/migrate-from-v2.md

Update CI scripts or bootstrap commands that download the `spc` binary directly by changing the URL from the v2 path to the v3 path.

```bash
# v2
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
```

```bash
# v3
curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
```

--------------------------------

### Build PHP with Hardcoded INI Setting

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Bakes a specific INI setting directly into the binary at compile time. This option can be repeated for multiple settings.

```bash
spc build:php --with-hardcoded-ini=<k=v>
```

```bash
spc build:php -I <k=v>
```

--------------------------------

### Build Specific PHP SAPIs

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Use these commands to build specific PHP Server API implementations like CLI, FPM, Micro, Embed, CGI, or FrankenPHP. Specify required extensions as a comma-separated string.

```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
```

--------------------------------

### Build Micro SAPI to Fake CLI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/sapi-reference.md

Builds the micro SAPI with an option to fake the PHP_SAPI value as 'cli'. This is necessary for frameworks that refuse to run outside the CLI environment.

```bash
spc build:php "bcmath,phar" --build-micro --with-micro-fake-cli
```

--------------------------------

### Run a Verbose Static PHP Build

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/first-build.md

Use the `-v` flag with `spc craft` to increase the verbosity of the build output, providing more detail on the pipeline stages. Higher verbosity levels (`-vv`, `-vvv`) offer even more information.

```bash
spc craft -v
```

--------------------------------

### Build PHP Extensions as Shared Libraries

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Compiles specified extensions as shared `.so` or `.dll` files instead of statically linking them.

```bash
spc build:php --build-shared=<list>
```

```bash
spc build:php -D <list>
```

--------------------------------

### Configure Compiler and Linker Flags

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Outputs compiler and linker flags for linking against the PHP embed static library. Specify extensions to include. Options control the output of include paths, linker flags, and library details.

```bash
spc spc-config [extensions] [options]
```

```bash
# Output full compiler + linker flags
spc spc-config "bcmath,openssl,curl"
```

```bash
# Output include paths only
spc spc-config "bcmath,openssl" --includes
```

```bash
# Output linker flags only
spc spc-config "bcmath,openssl" --libs
```

```bash
# Use absolute library paths
spc spc-config "bcmath,openssl" --libs --absolute-libs
```

--------------------------------

### Build PHP with CGI SAPI

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Builds the PHP-CGI SAPI, suitable for environments that use the Common Gateway Interface.

```bash
spc build:php --build-cgi
```

--------------------------------

### Build PHP with Custom Config Scan Directory

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Specifies a custom directory for PHP to scan for additional `.ini` files.

```bash
spc build:php --with-config-file-scan-dir=<path>
```

--------------------------------

### Download from File List

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/artifact-model.md

Fetches filenames and versions from an HTML page using regex. Best for projects with their own FTP or web index. Requires a URL and a PCRE regex with named capture groups for file and version.

```yaml
artifact:
  source:
    type: filelist
    url: 'https://ftp.gnu.org/pub/gnu/ncurses/'
    regex: '/href="(?<file>ncurses-(?<version>[^\"]+)\.tar\.gz)"/'
```

--------------------------------

### Combine PHP Script into Executable

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Merges a PHP script with the micro.sfx stub to create a standalone executable. The default output name is 'my-app'.

```bash
spc micro:combine app.php
```

--------------------------------

### Build PHP CLI and Bake INI Settings

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

This command builds the PHP CLI SAPI with specified extensions and embeds custom INI settings directly into the binary.

```bash
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
```

--------------------------------

### Optimize downloads with parallelism and retries

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Accelerate the download process by configuring parallel downloads and specifying the number of retries for failed downloads.

```bash
spc download --for-extensions="bcmath,openssl,curl" --parallel 8 --retry=3
```

--------------------------------

### Download artifacts for extensions

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Use this command to download specific artifacts required by your chosen PHP extensions. You can specify the PHP version and force re-downloads if necessary.

```bash
spc download --for-extensions="bcmath,openssl,curl" --with-php=8.5
```

```bash
spc download --for-extensions="bcmath,openssl,curl" --ignore-cache="php-src" --with-php=8.3
```

```bash
spc download --for-extensions="bcmath" --custom-url "php-src:https://downloads.php.net/~user/php-8.5.0alpha1.tar.xz"
```

--------------------------------

### Enter Development Shell

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

The `dev:shell` command provides an interactive shell with StaticPHP's build environment pre-loaded. This is useful for compiling small programs or inspecting the build environment.

```bash
spc dev:shell
```

--------------------------------

### Combine with INI File

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Injects INI settings from a specified file into the standalone executable. This is useful for managing multiple configuration options efficiently.

```bash
spc micro:combine app.php --with-ini-file=custom.ini
```

--------------------------------

### Download PHP Extension from Packagist (PIE)

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/develop/artifact-model.md

Downloads a PHP extension from Packagist following the PIE specification. Fetches metadata via the Packagist API and downloads the source archive. Requires the Packagist package path in 'vendor/package' format.

```yaml
artifact:
  source:
    type: pie
    repo: xdebug/xdebug
```

--------------------------------

### Run Environment Diagnostics

Source: https://github.com/crazywhalecc/static-php-cli/blob/v3/docs/en/guide/cli-reference.md

Use the `doctor` command to diagnose if the current environment can compile PHP normally. Options include automatic fixing of detected issues.

```bash
spc doctor [--auto-fix[=never]]
```