Refactor documentation structure and add new artifact model guide

2026-07-03 23:05:41 +08:00 · 2026-04-29 14:28:17 +08:00
parent 3c4f39735e
commit 269cd600f8
23 changed files with 530 additions and 79 deletions
--- a/docs/en/develop/artifact-model.md
+++ b/docs/en/develop/artifact-model.md
@@ -0,0 +1,451 @@
+---
+outline: 'deep'
+---
+
+# Artifact Model
+
+An **Artifact** is a core concept in the StaticPHP build system. It represents a source archive or pre-built binary required to build a package. Each artifact describes where to download the file, how to extract it, and the resulting path layout. Packages reference one or more artifacts via the `artifact` field to obtain the source code or binaries they need.
+
+## Defining an Artifact
+
+Here is a minimal artifact object that points to a source archive (curl's source code):
+
+```yaml
+&:
+  source:
+    type: ghrel
+    repo: curl/curl
+    match: curl.+\.tar\.xz
+    prefer-stable: true
+```
+
+There are two ways to define an artifact and associate it with a package: **inline** (defined directly inside the package file) or **standalone** (defined in a separate file and referenced by name):
+
+::: code-group
+```yaml [Inline Artifact]
+# This is a package declaration
+curl:
+  type: target
+  artifact:
+    source:
+      type: ghrel
+      repo: curl/curl
+      match: curl.+\.tar\.xz
+      prefer-stable: true
+```
+```yaml [Standalone Artifact]
+# This is a standalone artifact declaration, typically placed under config/artifact/
+curl-src:
+  source:
+    type: ghrel
+    repo: curl/curl
+    match: curl.+\.tar\.xz
+    prefer-stable: true
+```
+```yaml [Package Referencing a Standalone Artifact]
+# This is a package declaration
+curl:
+  type: target
+  artifact: curl-src
+```
+:::
+
+## Structure
+
+An artifact has three top-level sections: `source`, `binary`, and `metadata`.
+
+- `source` — the source code archive
+- `binary` — pre-built binaries for specific platforms
+- `metadata` — additional information such as license paths
+
+Both `source` and `binary` accept either an inline source object or a reference to a standalone artifact by name (as shown above).
+
+Full artifact object format:
+
+```yaml
+&:
+  source: {source-object} # (optional)
+  binary:
+    windows-x86_64: {source-object} # (optional)
+    linux-x86_64: {source-object} # (optional)
+    linux-aarch64: {source-object} # (optional)
+    macos-x86_64: {source-object} # (optional)
+    macos-aarch64: {source-object} # (optional)
+  metadata: # (optional)
+    license: "" # (optional) SPDX identifier
+    license-files: ["LICENSE"] # License files from the source directory
+    source-root: "subdir" # (optional) Use if the actual source root is inside a subdirectory
+```
+
+The basic format of a `source-object`:
+
+```yaml
+&:
+  type: "url" # Download type
+  # ...: Additional keys depend on the type; see below
+  extract: "path/to/dir" # (optional) Override extract path; default: SOURCE_PATH/{artifact-name}
+```
+
+## Metadata
+
+The `metadata` field provides supplementary information about an artifact. It supports three subfields:
+
+### license
+
+- **Type**: `string` (optional)
+- **Description**: The open-source license identifier for this package, following the [SPDX License Identifier](https://spdx.org/licenses/) format (e.g. `MIT`, `Apache-2.0`, `GPL-2.0-only`). This is used only for annotation in the license summary of the build output and has no effect on the build process itself.
+
+```yaml
+metadata:
+  license: MIT
+```
+
+### license-files
+
+- **Type**: `string[]` (optional)
+- **Description**: A list of paths to license files. After a successful build, the framework collects these files and places them in the `license/` directory of the build output. Two path formats are supported:
+  - **Relative paths** (e.g. `LICENSE`, `COPYING`, `gettext-runtime/intl/COPYING.LIB`): resolved relative to the artifact's source root directory.
+  - **`@/` prefix** (e.g. `@/bzip2.txt`): references a license file bundled with the framework itself, resolved to `src/globals/licenses/`. This is useful when the upstream source package does not include a license file (or the license text is embedded in other documentation) — in such cases, the license text can be placed in the built-in directory and referenced with `@/`.
+
+The following built-in license files are currently available: `bzip2.txt`, `gmp.txt`, `icu.txt`, `postgresql.txt`, `sqlite.txt`, `zlib.txt`.
+
+```yaml
+# Common case: read from the source directory
+metadata:
+  license-files: [LICENSE]
+
+# Multiple license files
+metadata:
+  license-files: [LICENSE, COPYING.LESSER]
+
+# License file inside a subdirectory
+metadata:
+  license-files: [gettext-runtime/intl/COPYING.LIB]
+
+# Use a built-in license file when the source package does not include one
+metadata:
+  license-files: ['@/bzip2.txt']
+```
+
+### source-root
+
+- **Type**: `string` (optional)
+- **Description**: When the actual source root is located inside a subdirectory of the extracted archive, this field specifies that subdirectory name. The framework will use this path as the working directory during the build instead of the top-level extraction directory.
+
+```yaml
+# krb5's actual source root is in the src/ subdirectory after extraction
+metadata:
+  source-root: src
+```
+
+## Download Types
+
+Artifacts support a variety of download types. Choose the one that best fits where the package is hosted.
+
+| Type | Description |
+|---|---|
+| `url` | Download from a fixed URL. Supports `filename` (custom local filename) and `version` (manually set version). |
+| `git` | Clone from a Git repository. Supports `rev` (branch/tag/commit), `submodules` (fetch submodules), and `extract`. |
+| `ghrel` | Download from GitHub Release Assets by regex match. Requires `repo` (`owner/repo`) and `match` (filename regex). Supports `prefer-stable`. |
+| `ghtar` | Download the source tarball from a GitHub Release (`/releases` API), matching by release name with `match`. Supports `prefer-stable`. |
+| `ghtagtar` | Download the source tarball from a GitHub Tag (`/tags` API), matching by tag name with `match`. Supports `prefer-stable`. |
+| `filelist` | Scrape an HTML page for a file listing, extract the filename and version via `regex`, then download the matched file. Suitable for official download index pages (e.g. ftp.gnu.org, openssl.org). |
+| `pecl` | Download a PHP extension from [PECL](https://pecl.php.net) by `name`. Supports `prefer-stable`. |
+| `pie` | Download a PHP extension from Packagist via the [PIE](https://github.com/php/pie) spec. Requires `repo` (`vendor/package`). |
+| `php-release` | Download official PHP source from php.net. The version is controlled by the `--with-php` build argument. |
+| `bitbuckettag` | Download source tarball from the latest Bitbucket tag. Requires `repo` (`workspace/repo`). |
+| `local` | Use a pre-existing local directory as the source. Requires `dirname`. Useful for offline or development scenarios. |
+| `custom` | Fully custom download logic implemented in a PHP class under `src/Package/Artifact/`. Optionally calls a specific method via `func`. |
+
+## Type Reference
+
+### url
+
+Downloads a file from a fixed URL and extracts it automatically.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\Url`
+- **Capabilities**: Basic download only; no automatic version update checking
+- **Required**: `url` — the download address
+- **Optional**:
+  - `filename` — local filename to save as (defaults to the last path segment of the URL)
+  - `version` — manually specify a version string (this type cannot auto-detect versions)
+  - `extract` — override the extraction directory (default: `SOURCE_PATH/{artifact-name}`)
+
+```yaml
+# sqlite downloaded from a fixed URL
+artifact:
+  source:
+    type: url
+    url: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'
+```
+
+::: tip
+
+Inside an artifact, a bare string starting with `http://` or `https://` is automatically expanded into a `type: url` object, so you can often just write the URL directly:
+
+```yaml
+artifact:
+  source: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'
+```
+:::
+
+---
+
+### git
+
+Clones a Git repository as the source. Supports two modes: clone a specific branch/tag/commit (`rev`), or use a regex to match the highest-versioned branch from all remote refs (`regex`).
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\Git`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**: `url` — repository URL
+- **Optional** (at least one of `rev` or `regex` is required):
+  - `rev` — clone a specific branch, tag, or commit hash
+  - `regex` — match remote branch names with a PCRE regex; the highest matching version is selected (must include a named capture group `(?P<version>...)`)
+  - `submodules` — whether to fetch git submodules (boolean)
+  - `extract` — override the clone target directory
+
+```yaml
+# php-glfw cloned from the master branch
+artifact:
+  source:
+    type: git
+    url: 'https://github.com/mario-deluna/php-glfw'
+    rev: master
+```
+
+---
+
+### ghrel
+
+Downloads a file from GitHub Release Assets using a regex to match the asset filename. Best suited for repositories that upload pre-compiled packages or source archives as release assets.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubRelease`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`), integrity verification (`ValidatorInterface`, SHA256)
+- **Required**:
+  - `repo` — repository path in `owner/repo` format
+  - `match` — PCRE regex (without delimiters) to match the asset filename, e.g. `openssl.+\.tar\.gz`
+- **Optional**:
+  - `prefer-stable` — skip pre-release versions (default: `true`)
+  - `query` — query string appended to the API URL (e.g. `?per_page=5`)
+  - `extract` — override extraction directory
+
+```yaml
+# openssl downloaded from GitHub Release Assets
+artifact:
+  source:
+    type: ghrel
+    repo: openssl/openssl
+    match: openssl.+\.tar\.gz
+    prefer-stable: true
+```
+
+---
+
+### ghtar
+
+Downloads the source tarball automatically generated by a GitHub Release (the "Source code" archive on the Release page). Unlike `ghrel` which downloads uploaded assets, `ghtar` uses the auto-generated tarball from the `/releases` API.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubTarball`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**: `repo` — repository path in `owner/repo` format
+- **Optional**:
+  - `prefer-stable` — skip pre-release versions (default: `true`)
+  - `match` — regex filter applied to `tarball_url` (if omitted, the first result is used)
+  - `query` — query string appended to the API URL
+  - `extract` — override extraction directory
+
+```yaml
+# librdkafka downloaded via GitHub Release tarball
+artifact:
+  source:
+    type: ghtar
+    repo: confluentinc/librdkafka
+```
+
+---
+
+### ghtagtar
+
+Downloads a source tarball from a GitHub Tag via the `/tags` API. Functionally identical to `ghtar`, but targets the tags endpoint instead of releases — useful for repositories that tag releases without creating a formal GitHub Release.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\GitHubTarball` (shared with `ghtar`)
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**: `repo` — repository path in `owner/repo` format
+- **Optional**:
+  - `prefer-stable` — skip pre-release versions (default: `true`)
+  - `match` — regex filter applied to tag names (if omitted, the latest tag is used)
+  - `query` — query string appended to the API URL
+  - `extract` — override extraction directory
+
+```yaml
+# brotli: only match v1.x tags
+artifact:
+  source:
+    type: ghtagtar
+    repo: google/brotli
+    match: 'v1\.\d.*'
+
+# libpng: match v1.6.x tags, with pagination
+artifact:
+  source:
+    type: ghtagtar
+    repo: pnggroup/libpng
+    match: v1\.6\.\d+
+    query: '?per_page=150'
+```
+
+---
+
+### filelist
+
+Fetches an HTML page (typically an official download index), extracts filenames and version numbers from the page content using a regex, then automatically selects and downloads the highest stable version. Pre-release versions (those containing keywords like alpha, beta, rc, dev, nightly, or snapshot) are automatically skipped.
+
+**Best for**: projects without GitHub that publish versioned archives on their own FTP or web index, such as `https://ftp.gnu.org/pub/gnu/ncurses/`.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\FileList`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**:
+  - `url` — URL of the HTML page containing the file listing
+  - `regex` — PCRE regex to extract filenames and versions from the page (must include named capture groups `(?<file>...)` and `(?<version>...)`)
+- **Optional**:
+  - `extract` — override extraction directory
+  - `download-url` — custom download URL template supporting `{file}` and `{version}` placeholders (by default the filename is appended directly to `url`)
+
+```yaml
+# ncurses: scrape latest version from the GNU FTP index
+artifact:
+  source:
+    type: filelist
+    url: 'https://ftp.gnu.org/pub/gnu/ncurses/'
+    regex: '/href="(?<file>ncurses-(?<version>[^"]+)\.tar\.gz)"/'
+
+# openssl: mirror source using filelist
+artifact:
+  source-mirror:
+    type: filelist
+    url: 'https://www.openssl.org/source/'
+    regex: '/href="(?<file>openssl-(?<version>[^"]+)\.tar\.gz)"/'
+```
+
+---
+
+### pecl
+
+Downloads a PHP extension source package from [PECL](https://pecl.php.net) using the PECL REST API. The latest stable version is selected automatically.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\PECL`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**: `name` — PECL package name (case-insensitive, e.g. `APCu`)
+- **Optional**:
+  - `prefer-stable` — download stable releases only (default: `true`)
+  - `extract` — override extraction directory (default: `php-src/ext/{name}`)
+
+```yaml
+# APCu downloaded from PECL
+artifact:
+  source:
+    type: pecl
+    name: APCu
+```
+
+---
+
+### pie
+
+Downloads a PHP extension from [Packagist](https://repo.packagist.org) following the [PIE](https://github.com/php/pie) specification. Package metadata is fetched via the Packagist `p2/` API, and the source archive is downloaded from the `dist` field.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\PIE`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`)
+- **Required**: `repo` — Packagist package path in `vendor/package` format
+- **Optional**:
+  - `extract` — override extraction directory
+
+```yaml
+# xdebug downloaded from Packagist
+artifact:
+  source:
+    type: pie
+    repo: xdebug/xdebug
+
+# php-spx with a custom extraction path
+artifact:
+  source:
+    type: pie
+    repo: noisebynorthwest/php-spx
+    extract: php-src/ext/spx
+```
+
+---
+
+### php-release
+
+Downloads the official PHP source from [php.net](https://www.php.net). The version is determined at build time by the `--with-php` argument. SHA256 integrity is verified automatically. Passing `git` as the version will clone the `master` branch of `php/php-src` directly.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\PhpRelease`
+- **Capabilities**: Version update checking (`CheckUpdateInterface`), integrity verification (`ValidatorInterface`, SHA256)
+- **Required**: `domain` — download domain (e.g. `https://www.php.net` or a custom mirror)
+- **Optional**:
+  - `extract` — override extraction directory
+
+```yaml
+# php-src with primary and mirror sources
+artifact:
+  source:
+    type: php-release
+    domain: 'https://www.php.net'
+  source-mirror:
+    type: php-release
+    domain: 'https://phpmirror.static-php.dev'
+```
+
+---
+
+### bitbuckettag
+
+Downloads a source tarball from the latest tag of a Bitbucket repository via the Bitbucket REST API.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\BitBucketTag`
+- **Capabilities**: Basic download only; no automatic version update checking
+- **Required**: `repo` — repository path in `workspace/repo` format
+- **Optional**:
+  - `extract` — override extraction directory
+
+```yaml
+artifact:
+  source:
+    type: bitbuckettag
+    repo: snappy-m-o/php-snappy
+```
+
+---
+
+### local
+
+Uses a pre-existing local directory as the source without performing any download. Useful for offline environments or local development where the source has already been placed on disk.
+
+- **Class**: `StaticPHP\Artifact\Downloader\Type\LocalDir`
+- **Capabilities**: Basic download only; no automatic version update checking
+- **Required**: `dirname` — absolute path to the local directory
+- **Optional**:
+  - `extract` — override extraction directory
+
+```yaml
+artifact:
+  source:
+    type: local
+    dirname: /path/to/local/source
+```
+
+---
+
+### custom
+
+Delegates download logic entirely to a PHP class under `src/Package/Artifact/`. If `func` is not specified, the class's default download method is called.
+
+- **Optional**: `func` — name of the specific method to invoke in the implementation class
+
+```yaml
+artifact:
+  source:
+    type: custom
+```
--- a/docs/en/develop/vendor-mode/annotations.md
+++ b/docs/en/develop/vendor-mode/annotations.md
--- a/docs/en/develop/extending/custom-artifact.md
+++ b/docs/en/develop/extending/custom-artifact.md
@@ -0,0 +1,8 @@
+# Custom Artifact
+
+<!-- TODO: Guide for implementing a custom artifact download class under src/Package/Artifact/.
+  Explain when type: custom is appropriate (e.g. proprietary auth, non-standard archives).
+  Cover: class placement and naming, method signatures (default download method + func dispatch),
+  accessing source config fields, returning the extracted source path,
+  registering the class via spc.registry.yml artifact psr-4 mapping.
+  Provide an annotated code example. -->
--- a/docs/en/develop/vendor-mode/dependency-injection.md
+++ b/docs/en/develop/vendor-mode/dependency-injection.md
--- a/docs/en/develop/extending/index.md
+++ b/docs/en/develop/extending/index.md
@@ -0,0 +1,8 @@
+# Extending StaticPHP
+
+<!-- TODO: Introduce the three extension strategies:
+  1. Contributing to core — edit src/Package/ and config/pkg/ directly.
+  2. External Registry — point SPC_REGISTRIES at a custom spc.registry.yml.
+  3. Vendor Mode — package classes + config as a Composer library (composer require).
+  Explain when to use each approach. Show a minimal end-to-end example:
+  one Library class, one config YAML, one spc.registry.yml, run spc. -->
--- a/docs/en/develop/vendor-mode/lifecycle-hooks.md
+++ b/docs/en/develop/vendor-mode/lifecycle-hooks.md
--- a/docs/en/develop/vendor-mode/package-classes.md
+++ b/docs/en/develop/vendor-mode/package-classes.md
--- a/docs/en/develop/registry.md
+++ b/docs/en/develop/registry.md
@@ -9,7 +9,7 @@ StaticPHP ships with a built-in core registry (`core`) that contains all definit
 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.
+- **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 [Extending StaticPHP](./extending/) 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
--- a/docs/en/develop/source-module.md
+++ b/docs/en/develop/source-module.md
@@ -1,5 +0,0 @@
-# Source Module
-
-<!-- TODO: Migrate and update from v2 source-module.md.
-  Document v3 source types: url, ghrel, ghtar, ghtagtar, git, pecl (new), filelist, custom.
-  Per-package YAML source block format. Parallel download (--parallel N). -->
--- a/docs/en/develop/vendor-mode/index.md
+++ b/docs/en/develop/vendor-mode/index.md
@@ -1,6 +0,0 @@
-# Vendor Mode
-
-<!-- TODO: What vendor mode is and when to use it.
-  Installation: `composer require crazywhalecc/static-php-cli`.
-  How to register an external registry pointing to your custom package classes.
-  Minimal working example: one Library class, one config YAML, run spc. -->