From 269cd600f8196e5def2c5156c0e2239ebcd817ca Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Wed, 29 Apr 2026 14:28:17 +0800 Subject: [PATCH] Refactor documentation structure and add new artifact model guide --- docs/.vitepress/sidebar.en.ts | 45 +- docs/.vitepress/sidebar.zh.ts | 51 +- docs/en/develop/artifact-model.md | 451 ++++++++++++++++++ .../{vendor-mode => extending}/annotations.md | 0 docs/en/develop/extending/custom-artifact.md | 8 + .../dependency-injection.md | 0 docs/en/develop/extending/index.md | 8 + .../lifecycle-hooks.md | 0 .../package-classes.md | 0 docs/en/develop/registry.md | 2 +- docs/en/develop/source-module.md | 5 - docs/en/develop/vendor-mode/index.md | 6 - docs/en/guide/installation.md | 2 +- .../{vendor-mode => extending}/annotations.md | 0 docs/zh/develop/extending/custom-artifact.md | 8 + .../dependency-injection.md | 0 docs/zh/develop/extending/index.md | 8 + .../lifecycle-hooks.md | 0 .../package-classes.md | 0 docs/zh/develop/registry.md | 2 +- docs/zh/develop/source-module.md | 5 - docs/zh/develop/vendor-mode/index.md | 6 - docs/zh/guide/installation.md | 2 +- 23 files changed, 530 insertions(+), 79 deletions(-) create mode 100644 docs/en/develop/artifact-model.md rename docs/en/develop/{vendor-mode => extending}/annotations.md (100%) create mode 100644 docs/en/develop/extending/custom-artifact.md rename docs/en/develop/{vendor-mode => extending}/dependency-injection.md (100%) create mode 100644 docs/en/develop/extending/index.md rename docs/en/develop/{vendor-mode => extending}/lifecycle-hooks.md (100%) rename docs/en/develop/{vendor-mode => extending}/package-classes.md (100%) delete mode 100644 docs/en/develop/source-module.md delete mode 100644 docs/en/develop/vendor-mode/index.md rename docs/zh/develop/{vendor-mode => extending}/annotations.md (100%) create mode 100644 docs/zh/develop/extending/custom-artifact.md rename docs/zh/develop/{vendor-mode => extending}/dependency-injection.md (100%) create mode 100644 docs/zh/develop/extending/index.md rename docs/zh/develop/{vendor-mode => extending}/lifecycle-hooks.md (100%) rename docs/zh/develop/{vendor-mode => extending}/package-classes.md (100%) delete mode 100644 docs/zh/develop/source-module.md delete mode 100644 docs/zh/develop/vendor-mode/index.md diff --git a/docs/.vitepress/sidebar.en.ts b/docs/.vitepress/sidebar.en.ts index 8a34aaba..b4d3ebd4 100644 --- a/docs/.vitepress/sidebar.en.ts +++ b/docs/.vitepress/sidebar.en.ts @@ -29,46 +29,41 @@ export default { ], '/en/develop/': [ { - text: 'Developer Guide', + text: 'Overview', items: [ { text: 'Get Started', link: '/en/develop/' }, { text: 'Project Structure', link: '/en/develop/structure' }, ], }, { - text: 'Concepts', + text: 'Configuration Reference', items: [ { text: 'Registry', link: '/en/develop/registry' }, { text: 'Package Model', link: '/en/develop/package-model' }, { text: 'Artifact Model', link: '/en/develop/artifact-model' }, - { text: 'Build Lifecycle', link: '/en/develop/build-lifecycle' }, - ], - }, - { - text: 'Modules', - items: [ - { text: 'Doctor', link: '/en/develop/doctor-module' }, - { text: 'Source', link: '/en/develop/source-module' }, { text: 'craft.yml', link: '/en/develop/craft-yml' }, + ], + }, + { + text: 'Build System', + items: [ + { text: 'Build Lifecycle', link: '/en/develop/build-lifecycle' }, { text: 'Compilation Tools', link: '/en/develop/system-build-tools' }, - ], - }, - { - text: 'Vendor Mode', - items: [ - { text: 'Introduction', link: '/en/develop/vendor-mode/' }, - { text: 'Writing Package Classes', link: '/en/develop/vendor-mode/package-classes' }, - { text: 'Dependency Injection', link: '/en/develop/vendor-mode/dependency-injection' }, - { text: 'Annotations Reference', link: '/en/develop/vendor-mode/annotations' }, - { text: 'Lifecycle Hooks', link: '/en/develop/vendor-mode/lifecycle-hooks' }, - ], - }, - { - text: 'Miscellaneous', - items: [ + { text: 'Doctor', link: '/en/develop/doctor-module' }, { text: 'PHP Source Modifications', link: '/en/develop/php-src-changes' }, ], }, + { + text: 'Extending StaticPHP', + items: [ + { text: 'Introduction', link: '/en/develop/extending/' }, + { text: 'Writing Package Classes', link: '/en/develop/extending/package-classes' }, + { text: 'Annotations Reference', link: '/en/develop/extending/annotations' }, + { text: 'Lifecycle Hooks', link: '/en/develop/extending/lifecycle-hooks' }, + { text: 'Dependency Injection', link: '/en/develop/extending/dependency-injection' }, + { text: 'Custom Artifact', link: '/en/develop/extending/custom-artifact' }, + ], + }, ], '/en/contributing/': [ { diff --git a/docs/.vitepress/sidebar.zh.ts b/docs/.vitepress/sidebar.zh.ts index 904c9fa6..f6ba09ef 100644 --- a/docs/.vitepress/sidebar.zh.ts +++ b/docs/.vitepress/sidebar.zh.ts @@ -29,46 +29,41 @@ export default { ], '/zh/develop/': [ { - text: '开发者指南', + text: '概览', items: [ { text: '开发简介', link: '/zh/develop/' }, { text: '项目结构', link: '/zh/develop/structure' }, ], }, { - text: '核心概念', + text: '配置参考', items: [ - { text: 'Registry 与插件系统', link: '/zh/develop/registry' }, + { text: 'Registry', link: '/zh/develop/registry' }, { text: 'Package 模型', link: '/zh/develop/package-model' }, { text: 'Artifact 模型', link: '/zh/develop/artifact-model' }, - { text: '构建生命周期', link: '/zh/develop/build-lifecycle' }, - ], - }, - { - text: '模块', - items: [ - { text: 'Doctor 环境检查', link: '/zh/develop/doctor-module' }, - { text: '资源模块', link: '/zh/develop/source-module' }, { text: 'craft.yml 配置', link: '/zh/develop/craft-yml' }, + ], + }, + { + text: '构建系统', + items: [ + { text: '构建生命周期', link: '/zh/develop/build-lifecycle' }, { text: '编译工具', link: '/zh/develop/system-build-tools' }, - ], - }, - { - text: 'Vendor 模式', - items: [ - { text: '简介', link: '/zh/develop/vendor-mode/' }, - { text: '编写 Package 类', link: '/zh/develop/vendor-mode/package-classes' }, - { text: '依赖注入', link: '/zh/develop/vendor-mode/dependency-injection' }, - { text: '注解参考', link: '/zh/develop/vendor-mode/annotations' }, - { text: '生命周期 Hook', link: '/zh/develop/vendor-mode/lifecycle-hooks' }, - ], - }, - { - text: '杂项', - items: [ + { text: 'Doctor 环境检查', link: '/zh/develop/doctor-module' }, { text: '对 PHP 源码的修改', link: '/zh/develop/php-src-changes' }, - ] - } + ], + }, + { + text: '扩展 StaticPHP', + items: [ + { text: '简介', link: '/zh/develop/extending/' }, + { text: '编写 Package 类', link: '/zh/develop/extending/package-classes' }, + { text: '注解参考', link: '/zh/develop/extending/annotations' }, + { text: '生命周期 Hook', link: '/zh/develop/extending/lifecycle-hooks' }, + { text: '依赖注入', link: '/zh/develop/extending/dependency-injection' }, + { text: '自定义 Artifact', link: '/zh/develop/extending/custom-artifact' }, + ], + }, ], '/zh/contributing/': [ { diff --git a/docs/en/develop/artifact-model.md b/docs/en/develop/artifact-model.md new file mode 100644 index 00000000..e3d130eb --- /dev/null +++ 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...)`) + - `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 `(?...)` and `(?...)`) +- **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="(?ncurses-(?[^"]+)\.tar\.gz)"/' + +# openssl: mirror source using filelist +artifact: + source-mirror: + type: filelist + url: 'https://www.openssl.org/source/' + regex: '/href="(?openssl-(?[^"]+)\.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 +``` diff --git a/docs/en/develop/vendor-mode/annotations.md b/docs/en/develop/extending/annotations.md similarity index 100% rename from docs/en/develop/vendor-mode/annotations.md rename to docs/en/develop/extending/annotations.md diff --git a/docs/en/develop/extending/custom-artifact.md b/docs/en/develop/extending/custom-artifact.md new file mode 100644 index 00000000..2698e9c4 --- /dev/null +++ b/docs/en/develop/extending/custom-artifact.md @@ -0,0 +1,8 @@ +# Custom Artifact + + diff --git a/docs/en/develop/vendor-mode/dependency-injection.md b/docs/en/develop/extending/dependency-injection.md similarity index 100% rename from docs/en/develop/vendor-mode/dependency-injection.md rename to docs/en/develop/extending/dependency-injection.md diff --git a/docs/en/develop/extending/index.md b/docs/en/develop/extending/index.md new file mode 100644 index 00000000..c0188449 --- /dev/null +++ b/docs/en/develop/extending/index.md @@ -0,0 +1,8 @@ +# Extending StaticPHP + + diff --git a/docs/en/develop/vendor-mode/lifecycle-hooks.md b/docs/en/develop/extending/lifecycle-hooks.md similarity index 100% rename from docs/en/develop/vendor-mode/lifecycle-hooks.md rename to docs/en/develop/extending/lifecycle-hooks.md diff --git a/docs/en/develop/vendor-mode/package-classes.md b/docs/en/develop/extending/package-classes.md similarity index 100% rename from docs/en/develop/vendor-mode/package-classes.md rename to docs/en/develop/extending/package-classes.md diff --git a/docs/en/develop/registry.md b/docs/en/develop/registry.md index 11026368..a49e6c6d 100644 --- 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 diff --git a/docs/en/develop/source-module.md b/docs/en/develop/source-module.md deleted file mode 100644 index f2825f32..00000000 --- a/docs/en/develop/source-module.md +++ /dev/null @@ -1,5 +0,0 @@ -# Source Module - - diff --git a/docs/en/develop/vendor-mode/index.md b/docs/en/develop/vendor-mode/index.md deleted file mode 100644 index 47c2e19c..00000000 --- a/docs/en/develop/vendor-mode/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Vendor Mode - - diff --git a/docs/en/guide/installation.md b/docs/en/guide/installation.md index f2df13e7..73c0134a 100644 --- a/docs/en/guide/installation.md +++ b/docs/en/guide/installation.md @@ -97,7 +97,7 @@ If you already have a PHP project and want to call StaticPHP's build APIs direct composer require crazywhalecc/static-php-cli ``` -See the [Vendor Mode guide](../develop/vendor-mode/) for details. +See the [Extending StaticPHP](../develop/extending/) guide for details. ## Verify your build environment diff --git a/docs/zh/develop/vendor-mode/annotations.md b/docs/zh/develop/extending/annotations.md similarity index 100% rename from docs/zh/develop/vendor-mode/annotations.md rename to docs/zh/develop/extending/annotations.md diff --git a/docs/zh/develop/extending/custom-artifact.md b/docs/zh/develop/extending/custom-artifact.md new file mode 100644 index 00000000..8956ba60 --- /dev/null +++ b/docs/zh/develop/extending/custom-artifact.md @@ -0,0 +1,8 @@ +# 自定义 Artifact + + diff --git a/docs/zh/develop/vendor-mode/dependency-injection.md b/docs/zh/develop/extending/dependency-injection.md similarity index 100% rename from docs/zh/develop/vendor-mode/dependency-injection.md rename to docs/zh/develop/extending/dependency-injection.md diff --git a/docs/zh/develop/extending/index.md b/docs/zh/develop/extending/index.md new file mode 100644 index 00000000..26cda4d9 --- /dev/null +++ b/docs/zh/develop/extending/index.md @@ -0,0 +1,8 @@ +# 扩展 StaticPHP + + diff --git a/docs/zh/develop/vendor-mode/lifecycle-hooks.md b/docs/zh/develop/extending/lifecycle-hooks.md similarity index 100% rename from docs/zh/develop/vendor-mode/lifecycle-hooks.md rename to docs/zh/develop/extending/lifecycle-hooks.md diff --git a/docs/zh/develop/vendor-mode/package-classes.md b/docs/zh/develop/extending/package-classes.md similarity index 100% rename from docs/zh/develop/vendor-mode/package-classes.md rename to docs/zh/develop/extending/package-classes.md diff --git a/docs/zh/develop/registry.md b/docs/zh/develop/registry.md index 7bc8fc54..f101709b 100644 --- a/docs/zh/develop/registry.md +++ b/docs/zh/develop/registry.md @@ -12,7 +12,7 @@ StaticPHP 本身携带一个内置的核心注册表（`core`），其中包含 外部 Registry 只能定义 `core` 中尚不存在的新包，不能覆盖或修改核心注册表中已有的定义。根据你的需求，有以下三种方式来扩展或修改 StaticPHP 的构建能力： - **修改 `core` 注册表**：直接修改 `src/Package` 和 `config/pkg/` 下的文件，适用于希望将改动合并回 StaticPHP 主线的情况。请先阅读 [贡献指南](../contributing/) 中关于贡献新包的部分，再提交 PR。 -- **Vendor 模式**：将自定义包封装为一个独立的子注册表，以 Composer 包的形式分发，适用于需要私有包或希望以库的形式复用构建逻辑的场景。详见 [Vendor 模式](./vendor-mode/)。 +- **Vendor 模式**：将自定义包封装为一个独立的子注册表，以 Composer 包的形式分发，适用于需要私有包或希望以库的形式复用构建逻辑的场景。详见 [扩展 StaticPHP](./extending/)。 - **外部注册表（`SPC_REGISTRIES`）**：通过环境变量 `SPC_REGISTRIES` 指定一个或多个外部注册表文件的路径，StaticPHP 会在启动时加载它们。适用于临时扩展或不便打包为 Composer 包的场景，与其他包管理器的外部源机制类似。 ## Registry 定义文件 diff --git a/docs/zh/develop/source-module.md b/docs/zh/develop/source-module.md deleted file mode 100644 index c35555d8..00000000 --- a/docs/zh/develop/source-module.md +++ /dev/null @@ -1,5 +0,0 @@ -# 资源模块 - - diff --git a/docs/zh/develop/vendor-mode/index.md b/docs/zh/develop/vendor-mode/index.md deleted file mode 100644 index b90618f6..00000000 --- a/docs/zh/develop/vendor-mode/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Vendor 模式 - - diff --git a/docs/zh/guide/installation.md b/docs/zh/guide/installation.md index 1bfce62f..fdb5fef0 100644 --- a/docs/zh/guide/installation.md +++ b/docs/zh/guide/installation.md @@ -90,7 +90,7 @@ bin/setup-runtime composer require crazywhalecc/static-php-cli ``` -Vendor 模式的详细用法见 [Vendor 模式指南](../develop/vendor-mode/)。 +Vendor 模式的详细用法见 [扩展 StaticPHP](../develop/extending/)。 ## 验证构建环境