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

Update latest docs

Browse Source
This commit is contained in:
crazywhalecc
2026-04-23 14:09:20 +08:00
parent 3583cbe119
commit 860ff38dae
10 changed files with 916 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/en/develop/index.md
View File

@@ -1,4 +1,49 @@
# Start Developing
# Developer Guide
<!-- TODO: Developer introduction, environment setup, required PHP extensions.
Link to Vendor Mode for library authors, and Contributing for code contributors. -->
This section covers the StaticPHP development workflow and the foundational knowledge needed to understand how StaticPHP works under the hood.
## Overview
StaticPHP is a binary build tool whose core purpose is managing the build pipeline — downloading and configuring PHP source code, resolving extension dependencies, and invoking the underlying build system (e.g., Docker or a local compiler).
From a development perspective, StaticPHP is an open framework that provides the ability to statically build PHP and other open-source tools together. The project is maintained by [@crazywhalecc](https://github.com/crazywhalecc) and [@henderkes](https://github.com/henderkes), with contributions from the community.
You can think of StaticPHP as a typical PHP CLI project built on [symfony/console](https://symfony.com/doc/current/components/console.html).
## Development Environment
To get started with StaticPHP development, you'll need a PHP development environment with the required dependencies installed.
Requirements:
- PHP 8.4 or later
- Composer
- Git
- PHP extensions: `curl, dom, filter, mbstring, openssl, pcntl, phar, posix, sodium, tokenizer, xml, xmlwriter`
> These PHP extensions are required for StaticPHP's `dev` environment.
### Setup Steps
1. Clone the repository:
```bash
git clone https://github.com/crazywhalecc/static-php-cli.git
cd static-php-cli
```
2. Install PHP dependencies:
```bash
composer install
```
3. Verify the setup:
```bash
bin/spc --version
```
---
You can continue reading [Project Structure](./structure) to learn more about StaticPHP's framework architecture.

249
docs/en/develop/package-model.md
View File

@@ -1,6 +1,247 @@
# Package Model
<!-- TODO: Explain the unified package model: library / php-extension / target types.
Cover the per-package YAML format (config/pkg/), the `depends` field,
platform overrides (@windows / @unix notation), artifact.source and artifact.binary.
Show annotated example YAML for a library and an extension. -->
## Package Definition
A Package is the core concept in StaticPHP's build system, representing a buildable/installable unit such as a PHP extension, library, or build target.
Each Package contains build information, dependencies, and build logic, forming StaticPHP's build model. Package definitions are primarily implemented through YAML/JSON configuration files. The package configuration files for the `core` registry are located in the `config/pkg/` directory, and the corresponding build classes are in the `src/Package/` directory.
Packages are primarily divided into four types:
- **php-extension**: A PHP extension package containing build information and logic for a PHP extension.
- **library**: A library package containing build information and logic for build tools, dependency libraries, etc.
- **target**: A build target package representing the final build artifact, such as a PHP binary or curl binary. Inherits from the `library` package type.
- **virtual-target**: A virtual build target package representing an abstract build target that doesn't directly correspond to a build artifact, primarily used for dependency management and build scheduling.
```yaml
{pkg-name}:
type: {pkg-type}
...
```
## Artifact Definition
An Artifact is a definition independent of Packages. It contains the source archive file or pre-built binary for building packages. Each Artifact defines download URLs, extraction methods, and build artifact file paths. Packages can reference one or more Artifacts via the `artifact` field to obtain the source or binaries needed for building.
In simple terms, by default one Package corresponds to one Artifact; if multiple Packages share the same source, you can define a single Artifact for multiple Packages to reference. Artifact definitions are located in the `config/artifact/` directory, and the corresponding custom download/extract logic classes are in the `src/Package/Artifact/` directory. For special package types like virtual targets and PHP built-in extensions, a Package may also omit the Artifact field entirely.
Assuming `example-library-package` is a dependency library whose source archive is hosted at `https://example.com/example-library.tar.gz`, its Package and Artifact definitions would look like this:
```yaml
example-library-package:
type: library
artifact:
source:
type: url
url: 'https://example.com/example-library.tar.gz'
```
For more on Artifact definitions, see the [Artifact Model](./artifact-model) chapter.
## php-extension Package Type
A php-extension package represents a PHP extension. Its configuration file is located in the `config/pkg/ext/` directory, and its build class inherits from `PhpExtensionPackage` in the `src/Package/Extension/` directory. PHP extension package configurations include extension name, version, dependencies, build options, and more.
```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'
```
Allowed fields for `php-extension`:
```yaml
ext-{ext-name}: # Package name must start with ext- prefix
type: php-extension
# ── Common Fields ────────────────────────────────────────────────────────
description: '..' # Optional, human-readable package description
lang: c # Optional, implementation language of the extension (c / c++ etc.)
frameworks: [] # Optional, list of related macOS framework dependencies
artifact: '{artifact-name}' # Optional; when a string, references an Artifact definition
# with the same name; when an object, is an inline Artifact
# (built-in extensions don't need this field)
# depends / suggests support @windows / @unix / @linux / @macos suffixes
depends: [] # Optional, hard dependency list (library names as-is, PHP extensions need ext- prefix)
depends@unix: [] # Optional, hard dependencies only effective on Unix platforms
depends@windows: [] # Optional, hard dependencies only effective on Windows platforms
suggests: [] # Optional, optional dependency list (same format as depends)
suggests@unix: []
# ── php-extension Specific Fields (nested under php-extension: object) ────
php-extension:
# arg-type determines the form of arguments passed to ./configure, supports platform suffixes
# Supported platform suffixes: @unix (Linux + macOS), @linux, @macos, @windows
# Priority (using Linux as example): arg-type@linux > arg-type@unix > arg-type (no suffix)
# Built-in keywords:
# enable → --enable-{extname} (default value, used when not configured)
# enable-path → --enable-{extname}={buildroot}
# with → --with-{extname}
# with-path → --with-{extname}={buildroot}
# custom/none → Pass no arguments (handled by the #[CustomPhpConfigureArg] method in the PHP class)
# You can also write the full argument string directly, supporting the following placeholders:
# @build_root_path@ → BUILD_ROOT_PATH (absolute path of buildroot)
# @shared_suffix@ → Expands to =shared in shared builds, empty in static builds
# @shared_path_suffix@ → Expands to =shared,{buildroot} in shared builds,
# expands to ={buildroot} in static builds
arg-type: enable
arg-type@unix: '--enable-{extname}=@shared_suffix@'
arg-type@windows: with-path
zend-extension: false # Optional, true indicates this is a Zend extension (e.g., opcache, xdebug)
build-shared: true # Optional, whether building as a shared extension (.so) is allowed, default true
build-static: true # Optional, whether inline static building (compiled into PHP) is allowed, default true
build-with-php: true # Optional, true means the extension is built together via the PHP source tree
# (used for built-in extensions)
# display-name affects the php --ri argument in smoke tests and the license export display name
# If not set, defaults to the extension name (the part after ext-); if set to empty string, skips --ri check
display-name: 'My Extension'
# os restricts the extension to be available only on specified platforms;
# platforms not in the list will be rejected for building
# Allowed values: Linux, Darwin, Windows
os: [Linux, Darwin]
```
## library Package Type
A library package represents a dependency library that needs to be compiled from source (such as openssl, zlib, etc.). Its configuration file is located in the `config/pkg/lib/` directory, and its build class inherits from `LibraryPackage` in the `src/Package/Library/` directory.
Taking openssl as an example:
```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
```
Allowed fields for `library`:
```yaml
{lib-name}:
type: library # library or target (target inherits all fields from library)
# ── Common Fields ─────────────────────────────────────────────────────────
description: '..' # Optional, human-readable package description
license: MIT # Optional, SPDX license identifier (for license export)
lang: c # Optional, implementation language of the library (c / c++ etc.)
frameworks: [] # Optional, list of related framework tags
artifact: '{artifact-name}' # Required; when a string, references an Artifact definition
# with the same name; when an object, is an inline Artifact
# depends / suggests support @windows / @unix / @linux / @macos suffixes
depends: [] # Optional, hard dependency list (library names or PHP extension names with ext- prefix)
depends@unix: []
depends@windows: []
suggests: [] # Optional, optional dependency list (same format as depends)
# ── library / target Specific Fields ───────────────────────────────────────
# The following fields are used to verify that artifacts have been correctly
# installed after the build. They support @unix / @windows / @linux / @macos suffixes.
# Verify that specified header files or directories exist under buildroot/include/
# Relative paths are based on buildroot/include/, absolute paths are used directly
headers:
- openssl # Corresponds to buildroot/include/openssl/
- zlib.h # Corresponds to buildroot/include/zlib.h
headers@unix:
- ffi.h
# Verify that specified static library files exist under buildroot/lib/
# Relative paths are based on buildroot/lib/, absolute paths are used directly
static-libs@unix:
- libssl.a
static-libs@windows:
- libssl.lib
# Verify that specified .pc files exist under buildroot/lib/pkgconfig/
# Only checked on non-Windows platforms (pkg-config is not applicable on Windows)
pkg-configs:
- openssl # Corresponds to buildroot/lib/pkgconfig/openssl.pc
- libssl # Auto-completes .pc suffix
# Verify that specified executable files exist under buildroot/bin/
# Relative paths are based on buildroot/bin/, absolute paths are used directly
static-bins:
- my-tool
# List of directories injected into the global PATH after the package is installed.
# Path placeholders are supported (see below for details).
path:
- '{pkg_root_path}/rust/bin'
# Environment variables set after the package is installed (overwrites existing values).
# Path placeholders are supported.
env:
MY_VAR: '{build_root_path}/lib'
# Values appended to the end of existing environment variables after the package is installed.
# Path placeholders are supported.
append-env:
CFLAGS: ' -I{build_root_path}/include'
```
The following path placeholders are supported in string values of the `path`, `env`, and `append-env` fields:
| Placeholder | Actual Path |
|---|---|
| `{build_root_path}` | buildroot directory (`buildroot/`) |
| `{pkg_root_path}` | pkgroot directory (`pkgroot/`) |
| `{working_dir}` | Working directory (project root) |
| `{download_path}` | Download cache directory (`downloads/`) |
| `{source_path}` | Extracted source directory (`source/`) |
| `{php_sdk_path}` | Windows PHP SDK directory |
## target Package Type
A `target` package represents a final build artifact. It inherits from `library`, so it includes all definition fields of `library`. The configuration file for `target` packages is located in the `config/pkg/target/` directory, and its build class inherits from `TargetPackage` in the `src/Package/Target/` directory.
The only difference from `library` is that a `target` package can be registered as a build target and automatically registers the build command `spc build:{target-name}`.
## virtual-target Package Type
Unlike `target`, a `virtual-target` may not include an `artifact`, meaning it doesn't directly correspond to a buildable entity but is instead an abstract build target, primarily used for dependency management and build scheduling. The configuration file for `virtual-target` is located in the `config/pkg/target/` directory, and its build class inherits from `TargetPackage` in the `src/Package/Target/` directory. Its definition is essentially the same as `target`, but the `artifact` field is optional and typically not set. `virtual-target` is primarily used in the following scenarios:
- Defining an abstract build target for other packages to depend on, without directly corresponding to a buildable entity.
- Serving as a common dependency for multiple `target` packages, simplifying dependency management.
A typical example is the `php-cli`, `php-fpm` build targets for PHP. They have no independent source code and depend on `php-src`, with the final build outcome (CLI or FPM binary) determined through build scheduling.

83
docs/en/develop/registry.md
View File

@@ -1,6 +1,81 @@
# Registry & Plugin System
<!-- TODO: Explain spc.registry.yml structure.
How to add an external registry via SPC_REGISTRIES env var.
Vendor-specific configurations, overriding core packages.
Registry resolution order and conflict rules. -->
## Overview
The **Registry** is StaticPHP's core extension mechanism. Think of it as a "plugin package": a Registry consists of a declaration file (`spc.registry.yml`) and the configuration files and PHP classes it points to, describing a set of package definitions (YAML configuration) and their corresponding build logic (PHP classes). The build system loads all registered Registries at startup and merges their package definitions for use throughout the entire build process.
StaticPHP ships with a built-in core registry (`core`) that contains all definitions for PHP and related extensions, libraries, build tools, and more. The declaration file for the `core` registry is `spc.registry.yml` in the project root, which describes the mapping between the configuration file directory (`config/pkg/`, `config/artifact/`) and the build class PSR-4 namespace (`src/Package/`).
External Registries can only define new packages that don't already exist in `core`; they cannot override or modify existing definitions in the core registry. Depending on your needs, there are three ways to extend or modify StaticPHP's build capabilities:
- **Modify the `core` registry**: Directly edit files under `src/Package` and `config/pkg/`, suitable when you want to contribute changes back to the StaticPHP mainline. Please read the [Contributing Guide](../contributing/) section on contributing new packages before submitting a PR.
- **Vendor Mode**: Package your custom packages as a standalone sub-registry distributed as a Composer package, suitable for private packages or scenarios where you want to reuse build logic as a library. See [Vendor Mode](./vendor-mode/) for details.
- **External Registry (`SPC_REGISTRIES`)**: Specify one or more external registry file paths via the `SPC_REGISTRIES` environment variable, which StaticPHP loads at startup. Suitable for temporary extensions or scenarios where packaging as a Composer package isn't practical, similar to external source mechanisms in other package managers.
## Registry Declaration File
Each Registry has a declaration file, typically named `spc.registry.yml`, located in the project root or the root of a Composer package. The file format supports YAML (`.yml` / `.yaml`) and JSON (`.json`). All paths within the file are resolved relative to the directory containing the declaration file itself.
In source mode (direct git clone), StaticPHP loads `spc.registry.yml` in the project root as the core registry (`core`) by default. In Vendor mode, it automatically detects whether `spc.registry.yml` exists in the current Composer package root and loads it as a standalone registry. External registries specified via the `SPC_REGISTRIES` environment variable must also contain a valid declaration file.
Below is a complete example with all available fields (based on the `core` registry):
```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)
```
Top-level field descriptions:
| Field | Required | Description |
|---|---|---|
| `name` | ✅ | Unique registry name; loading a registry with a duplicate name is automatically skipped |
| `autoload` | | Composer autoload file path, for external registries that carry their own dependencies |
| `package` | | Package definition, including YAML config (`config`) and build classes (`psr-4` / `classes`) |
| `artifact` | | Artifact definition, including YAML config (`config`) and custom classes (`psr-4` / `classes`) |
| `doctor` | | Doctor check item definition, class loading only (`psr-4` / `classes`) |
| `command` | | Additional CLI command definition, class loading only (`psr-4` / `classes`) |
The difference between `psr-4` and `classes`: `psr-4` scans all PHP classes in the entire directory that match the namespace rules and registers them in bulk; `classes` is used to precisely specify individual classes, supporting plain array format (`["ClassName"]`, must already be available in autoload) or key-value mapping format (`{"ClassName": "path/to/file.php"}`, the loader will automatically `require` the corresponding file).

85
docs/en/develop/structure.md
View File

@@ -1,5 +1,84 @@
# Project Structure
<!-- TODO: v3 directory layout (bin/, config/pkg/, src/StaticPHP/, src/Package/, etc.).
Explain the role of each top-level directory. Internal class structure kept brief;
deep dives belong in the Concepts pages. -->
## Concepts
StaticPHP is a CLI application built on `symfony/console`, with core code located in the `src/StaticPHP` directory. It is organized into several modules:
- **Registry**: Manages registry data. Each registry contains multiple packages (Package), and the StaticPHP project ships with a built-in `core` registry that includes PHP and related extensions, dependencies, and more.
- **Package**: Represents a single package. There are four package types: `php-extension` (PHP extension), `library` (library), `target` (build target), and `virtual-target` (virtual build target). Each package contains build information, dependencies, and more.
- **Installer/Builder**: Handles installation and build logic for packages — executing build commands, extracting build artifacts, processing build results, etc.
- **Doctor**: Provides system environment checking, responsible for installing and verifying system-level dependencies such as `make`, `cmake`, `autoconf`, and more.
- **Runtime/Executor**: Contains runtime-related utility classes, such as shell command execution and CMake build execution.
- **Toolchain**: Provides toolchain abstraction interfaces for different operating systems and environments, handling system-level differences during the build process.
- **Utils**: General-purpose utility classes, such as file system operations, logging, and OS-specific helper methods.
- **DependencyResolver**: Resolves dependencies between packages and generates build order.
## Directory Layout
```
static-php-cli/
├── bin/ # Executable entry scripts (spc, spc.ps1, setup-runtime, etc.)
├── config/
│ ├── env.ini # Default environment variable configuration
│ ├── env.custom.ini # User-defined environment variables (overrides env.ini)
│ ├── artifact/ # Build artifact configuration (toolchain downloads, pre-built binaries, etc.)
│ └── pkg/ # Package configuration files (YAML)
│ ├── ext/ # PHP extension package config (ext-*.yml, builtin-extensions.yml)
│ ├── lib/ # Library package config (*.yml)
│ └── target/ # Build target config (php.yml, curl.yml, etc.)
├── src/
│ ├── bootstrap.php # Application bootstrap (auto-loading, DI container, etc.)
│ ├── globals/ # Global helper functions
│ ├── Package/ # Build logic implementations for each package (PHP classes)
│ │ ├── Artifact/ # Custom download/extract logic for build artifacts
│ │ ├── Command/ # Package-level custom commands
│ │ ├── Extension/ # PHP extension build classes (ext-*.php)
│ │ ├── Library/ # Library build classes (*.php)
│ │ └── Target/ # Build target classes (php.php, curl.php, etc.)
│ └── StaticPHP/ # Framework core code
│ ├── ConsoleApplication.php # Symfony Console application entry
│ ├── Artifact/ # Build artifact download and extraction (Downloader, Extractor, etc.)
│ ├── Attribute/ # PHP attribute definitions
│ │ ├── Artifact/ # Artifact-related attributes (CustomSource, BinaryExtract, etc.)
│ │ ├── Doctor/ # Doctor-related attributes (CheckItem, FixItem, etc.)
│ │ └── Package/ # Package build-related attributes (BuildFor, BeforeStage, AfterStage,
│ │ # CustomPhpConfigureArg, PatchBeforeBuild, etc.)
│ ├── Command/ # CLI command implementations (build-libs, build-target, doctor, etc.)
│ ├── Config/ # Configuration loading and validation (PackageConfig, ArtifactConfig, etc.)
│ ├── DI/ # Dependency injection container (ApplicationContext, CallbackInvoker, etc.)
│ ├── Doctor/ # System environment checking and fixing (Doctor, CheckResult)
│ ├── Exception/ # Custom exception classes
│ ├── Package/ # Core package models and build scheduling
│ │ ├── Package.php # Base package class
│ │ ├── LibraryPackage.php # Library package type
│ │ ├── PhpExtensionPackage.php # PHP extension package type
│ │ ├── TargetPackage.php # Build target package type
│ │ ├── PackageInstaller.php # Package installer (download, extract source)
│ │ └── PackageBuilder.php # Package builder (execute build pipeline)
│ ├── Registry/ # Registry management (Registry, PackageLoader, ArtifactLoader)
│ ├── Runtime/ # Runtime utilities
│ │ ├── Executor/ # Command executors (UnixAutoconfExecutor, UnixCMakeExecutor,
│ │ │ # WindowsCMakeExecutor, Executor base class)
│ │ ├── Shell/ # Shell abstraction (UnixShell, WindowsCmd, etc.)
│ │ └── SystemTarget.php # System target information
│ ├── Toolchain/ # Toolchain abstraction (GccNative, Musl, MSVC, Zig, ClangBrew, etc.)
│ └── Util/ # General utility classes
│ ├── System/ # OS platform utilities (LinuxUtil, MacOSUtil, WindowsUtil, etc.)
│ ├── BuildRootTracker.php # buildroot file tracking
│ ├── DependencyResolver.php # Dependency resolution and build order
│ ├── FileSystem.php # File system operations
│ ├── GlobalEnvManager.php # Global environment variable management
│ ├── InteractiveTerm.php # Interactive terminal output
│ ├── LicenseDumper.php # License export
│ ├── PkgConfigUtil.php # pkg-config utility wrapper
│ ├── SourcePatcher.php # Source code patching utility
│ └── SPCConfigUtil.php # SPC configuration reader
├── tests/ # Unit tests and integration tests
├── downloads/ # Download cache directory (source packages, pre-built binaries)
├── source/ # Extracted source code directory
├── buildroot/ # Build output directory (headers, static libraries, etc.)
├── pkgroot/ # Platform-archived build artifacts
└── spc.registry.yml # core registry definition file
```
Note that the classes in `src/Package` are responsible for implementing the build logic of specific packages, while the classes in `src/StaticPHP` provide the core functionality of the build framework, such as command scheduling, environment checking, and toolchain abstraction. The two are decoupled: `src/Package` corresponds to the packages in the `core` registry (including PHP, extensions, libraries, and build targets), while `src/StaticPHP` is the infrastructure that supports build needs across different registries and packages.