fix(docs): update Windows SAPI warning and download links in CliGenerator.vue

- C:\im was outside the project so bin/spc reset could not clean it
- with the command line limit fixed a short base path is no longer
  needed; keep SPC_IMAGEMAGICK_BUILD_DIR as an override

.gitattributes

@@ -0,0 +1,24 @@
+# Force LF line endings for all text files.
+# Prevents git from auto-converting LF -> CRLF on Windows checkouts.
+* text=auto eol=lf
+
+# Explicit binary files — git won't touch line endings for these
+*.phar binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.zip binary
+*.gz binary
+*.tgz binary
+*.txz binary
+*.xz binary
+*.bz2 binary
+*.7z binary
+*.exe binary
+*.dll binary
+*.sfx binary
+*.so binary
+*.a binary
+*.o binary

.github/copilot-instructions.md

@@ -0,0 +1,24 @@
+# StaticPHP v3 Copilot Instructions
+
+> The canonical agent instructions live in [AGENTS.md](./AGENTS.md). This file provides the essential summary for GitHub Copilot; read `AGENTS.md` for the complete project map, working rules, and validation steps.
+
+StaticPHP is a PHP CLI application for building static PHP binaries, PHP SAPIs, extensions, libraries, and helper tools. Prefer the v3 architecture under `src/StaticPHP`, `src/Package`, `config/pkg`, and `config/artifact`.
+
+## Skills
+
+Use the repository skills when the task matches them:
+
+- `.github/skills/staticphp-package-maintenance`: add, modify, review, or validate package, artifact, extension, library, target, or tool definitions.
+- `.github/skills/staticphp-build-troubleshooting`: diagnose build, download, doctor, shell, terminal, CI, smoke-test, or log failures.
+- `.github/skills/staticphp-documentation-sync`: synchronize bilingual documentation (`docs/en/` and `docs/zh/`) when features, commands, configuration, APIs, or behavior change.
+
+## Quick Reference
+
+- **Entrypoint**: `php bin/spc`
+- **Config lint**: `php bin/spc dev:lint-config`
+- **CS fix**: `composer cs-fix`
+- **Tests**: `composer test`
+- **Static analysis**: `composer analyse`
+- **Extension packages**: `config/pkg/ext/ext-*.yml`, prefix with `ext-` in dependencies
+- **Platform suffixes**: `@unix`, `@linux`, `@macos`, `@windows` — prefer these over runtime conditionals
+- **Do NOT edit generated dirs**: `buildroot/`, `source/`, `downloads/`, `pkgroot/`

.github/pull_request_template.md

@@ -1,17 +1,12 @@
 ## What does this PR do?
 
+<!-- Please describe the changes made in this PR here. -->
 
 
 ## Checklist before merging
 
-> If your PR involves the changes mentioned below and completed the action, please tick the corresponding option.
-> If a modification is not involved, please skip it directly.
-
-- If you modified `*.php` or `*.json`, run them locally to ensure your changes are valid:
+- If you modified `*.php` or `*.yml`, run them locally to ensure your changes are valid:
   - [ ] `composer cs-fix`
   - [ ] `composer analyse`
   - [ ] `composer test`
-  - [ ] `bin/spc dev:sort-config`
-- If it's an extension or dependency update, please ensure the following:
-  - [ ] Add your test combination to `src/globals/test-extensions.php`.
-  - [ ] If adding new or fixing bugs, add commit message containing `extension test` or `test extensions` to trigger full test suite.
+  - [ ] `bin/spc dev:lint-config`

.github/skills/staticphp-build-troubleshooting/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: staticphp-build-troubleshooting
+description: Diagnose StaticPHP v3 failures. Use when investigating build, compile, linker, download, doctor, environment, CI, smoke-test, terminal output, spc.output.log, spc.shell.log, config.log, CMake logs, or user-provided error snippets from StaticPHP commands.
+---
+
+# StaticPHP Build Troubleshooting
+
+## Overview
+
+Use this skill to triage StaticPHP failures from the outside in: command and environment first, SPC module/stage metadata next, shell/config logs last. The goal is to isolate the failing package, stage, command, and root cause before editing code.
+
+## First Pass
+
+1. Capture the exact command, OS, architecture, PHP version, extensions/libs/targets, and whether the run used `-v`, `-vv`, or `-vvv`.
+2. Read the final terminal error first. StaticPHP prints module error info, failed package, failed stage, failed command, log paths, and extra log files when available.
+3. If log files exist, inspect them in this order:
+   - `log/spc.output.log`: user-facing SPC messages and exception summary.
+   - `log/spc.shell.log`: executed commands, working directories, env, stdout/stderr.
+   - Extra logs named in the exception output: `php-src.config.log`, `lib.<pkg>.console.log`, `lib.<pkg>.cmake-error.log`, `lib.<pkg>.cmake-configure.log`, `lib.<pkg>.cmake-output.log`.
+4. Read `references/log-triage.md` for pattern matching, likely causes, and next checks.
+
+## Diagnosis Rules
+
+- Do not start by changing shared core code. Most failures are package metadata, environment, upstream source, dependency order, or platform flags.
+- Prefer evidence from the last failing command over earlier warnings.
+- When logs are long, search backward for `Command exited`, `error:`, `undefined reference`, `not found`, `No package`, `CMake Error`, `configure: error`, `fatal error`, `Failed module`, and `Failed stage`.
+- Use `config.log` and CMake logs for configure detection failures; use `spc.shell.log` for the actual command and env.
+- Be careful with rebuild suggestions. `spc reset --with-download --yes` is destructive to caches; ask before clearing caches unless the user explicitly asked.
+
+## Repro Commands
+
+Use focused commands when reproducing:
+
+```bash
+php bin/spc doctor -vvv
+php bin/spc download --for-extensions="curl,openssl" --with-php=8.5 --parallel=4 --retry=3 -vvv
+php bin/spc build:libs "openssl" -vvv
+php bin/spc build:php "bcmath,openssl,curl" --build-cli -vvv
+php bin/spc dev:lint-config
+```
+
+Choose the smallest command that still reaches the failing package.
+
+## Fix Direction
+
+After finding the failing package/stage:
+
+- Package YAML issue: use `$staticphp-package-maintenance`, then edit `config/pkg/*` or `config/artifact/*`.
+- Build command or patch issue: inspect the package class under `src/Package/*`.
+- Environment issue: check `doctor`, toolchain classes, and `config/pkg/tool/*`.
+- Upstream download issue: check artifact type, regex, GitHub rate limiting, mirror behavior, and `GITHUB_TOKEN`.
+- Core exception/logging issue: inspect `src/StaticPHP/Exception`, `src/StaticPHP/Runtime/Shell`, or executor classes only after package-level causes are ruled out.
+
+## Resources
+
+- `references/log-triage.md`: log files, failure categories, search patterns, and likely fixes.

.github/skills/staticphp-build-troubleshooting/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "StaticPHP Build Troubleshooting"
+  short_description: "Diagnose StaticPHP build and log failures."
+  default_prompt: "Use $staticphp-build-troubleshooting to investigate a StaticPHP build, download, doctor, or log failure."

.github/skills/staticphp-build-troubleshooting/references/log-triage.md

@@ -0,0 +1,209 @@
+# StaticPHP Log Triage
+
+## Contents
+
+- Log files
+- Terminal summary
+- Search strategy
+- Failure categories
+- Rebuild hygiene
+- Reporting checklist
+
+## Log Files
+
+Default log directory is `log/`, controlled by `SPC_LOGS_DIR`. The important files are:
+
+- `spc.output.log`: StaticPHP console/logger output and exception summaries.
+- `spc.shell.log`: command execution log with command, caller, inline env, working directory, stdout, stderr, and exit code.
+- `php-src.config.log`: copied when PHP source configure fails.
+- `lib.<pkg>.console.log`: copied Autoconf `config.log` for a library when available.
+- `lib.<pkg>.cmake-configure.log`: copied CMake 3.26+ configure log.
+- `lib.<pkg>.cmake-error.log`: copied CMake error log.
+- `lib.<pkg>.cmake-output.log`: copied CMake output log.
+
+Logs are created when `SPC_ENABLE_LOG_FILE` is true. Old `*.log` files are cleaned unless `SPC_PRESERVE_LOG` is set to a truthy value. The code in `src/bootstrap.php` reads `SPC_PRESERVE_LOG` (no trailing S).
+
+## Terminal Summary
+
+StaticPHP exceptions often print:
+
+- Exception category: build, download, environment, execution, file system, patch, validation, wrong usage, registry, internal.
+- Failed module: package name, type, and sometimes class/file/line.
+- Failed stage: call chain such as `build` or `build -> configure`.
+- Failed command: the command that returned non-zero.
+- Command working directory and inline env.
+- Paths to `spc.output.log`, `spc.shell.log`, and extra logs.
+
+Use this summary to choose the first files to read. If a package and stage are present, start with that package's YAML and class after reading the relevant log tail.
+
+## Search Strategy
+
+For long logs, search from the end first.
+
+Useful patterns:
+
+```text
+Failed module:
+Failed stage:
+Failed command:
+Command exited with non-zero code
+configure: error
+CMake Error
+undefined reference
+cannot find -l
+fatal error:
+No package
+Package .* not found
+Could NOT find
+is not a valid
+permission denied
+curl: (
+HTTP/2 403
+rate limit
+```
+
+In `spc.shell.log`, each command block begins with `>>>>>>>>>>>>>>>>>>>>>>>>>>`, then prints the command, caller, env, and working dir. The last failed block is usually the highest-value evidence.
+
+## Failure Categories
+
+### Download Failure
+
+Signs:
+
+- `Download failed`
+- `curl: (56)`, `curl: (22)`, HTTP 403/404/429
+- GitHub API calls in verbose logs
+- Asset regex did not match a release asset
+
+Likely checks:
+
+- If GitHub rate limited, ask user to set `GITHUB_TOKEN`.
+- Verify artifact source type and regex in `config/pkg/*` or `config/artifact/*`.
+- Use `--dl-retry`, `--dl-parallel`, `--ignore-cache`, `--no-alt`, or custom source options only as repro aids.
+- Prefer fixing stale URLs/regexes over adding workarounds.
+
+### Doctor or Environment Failure
+
+Signs:
+
+- `Environment check failed`
+- missing `make`, `cmake`, `autoconf`, `pkg-config`, compiler, Perl, Visual Studio, MSYS2, Zig, etc.
+- `Some check items can not be fixed`
+
+Likely checks:
+
+- Run `php bin/spc doctor -vvv`.
+- Inspect `src/StaticPHP/Doctor/Item/*` for the check and fix behavior.
+- Inspect `config/pkg/tool/*` for installable helper tools.
+- On Windows, some dependencies cannot be auto-installed.
+
+### Configure Failure
+
+Signs:
+
+- `configure: error`
+- Autoconf failure before compilation
+- extra `config.log` listed
+
+Likely checks:
+
+- Read copied `php-src.config.log` or `lib.<pkg>.console.log`.
+- Look for the first compiler/linker probe that failed.
+- Check `headers`, `static-libs`, `pkg-configs`, dependency order, and `initializeEnv($pkg)` behavior.
+- For extensions, check `php-extension.arg-type` and `#[CustomPhpConfigureArg]`.
+
+### CMake Failure
+
+Signs:
+
+- `CMake Error`
+- `Could NOT find`
+- missing target, package config, or static library
+
+Likely checks:
+
+- Read `lib.<pkg>.cmake-error.log` and `lib.<pkg>.cmake-configure.log`.
+- Inspect `UnixCMakeExecutor`/`WindowsCMakeExecutor` usage in the package class.
+- Check CMake options, toolchain root path, `pkg-configs`, and transitive dependency libraries.
+
+### Compile Failure
+
+Signs:
+
+- compiler `fatal error: header.h: No such file or directory`
+- syntax/type errors from upstream source
+- incompatible PHP API or platform macros
+
+Likely checks:
+
+- Identify the source file and include path from `spc.shell.log`.
+- Verify dependency headers are installed in `buildroot/include`.
+- Check PHP version compatibility and existing patches in `src/globals/patch`.
+- Prefer targeted patches or compile flags in the package class over broad toolchain changes.
+
+### Link Failure
+
+Signs:
+
+- `undefined reference`
+- `cannot find -lfoo`
+- duplicate symbols
+- Windows unresolved external symbol or missing `.lib`
+
+Likely checks:
+
+- Verify `static-libs`, dependency order, and `getStaticLibFiles()` usage.
+- Inspect `SPC_EXTRA_LIBS`, `Libs.private` in `.pc` files, and package-specific pkg-config patching.
+- On Windows, confirm `.lib` names and required system libraries.
+- For OpenSSL/curl-like packages, search existing linker flag hooks before adding a new one.
+
+### Smoke Test or Validation Failure
+
+Signs:
+
+- `Validation failed`
+- `php --ri` failure
+- extension not loaded after build
+- micro/embed runtime smoke test fails
+
+Likely checks:
+
+- Check extension `display-name`; empty string skips `php --ri`.
+- Confirm static vs shared build settings.
+- Confirm the extension is included in the final SAPI target and not only built as a dependency.
+- Inspect `src/globals/ext-tests/*` and common tests for expected runtime behavior.
+
+### Registry or Config Failure
+
+Signs:
+
+- `Registry error`
+- unknown package, invalid field, invalid platform suffix, type mismatch
+- package referenced by attribute but missing config
+
+Likely checks:
+
+- Run `php bin/spc dev:lint-config`.
+- Inspect `ConfigValidator` tests for accepted fields and error expectations.
+- Confirm attribute type matches YAML `type`.
+- Confirm hooks reference existing package names and stages for the current platform.
+
+## Rebuild Hygiene
+
+Use the smallest cleanup that can invalidate the suspected stale state:
+
+- Redownload one artifact: `--ignore-cache="artifact-name"`.
+- Skip downloads to test local source/build logic: `--no-download`.
+- Prefer source when debugging build logic: `--dl-prefer-source`.
+- Clear build products only when necessary. `spc reset --with-download --yes` removes caches and should not be suggested casually.
+
+## Reporting Checklist
+
+When preparing an issue or PR explanation, include:
+
+- Exact `php bin/spc ...` command.
+- OS, architecture, PHP version option, and relevant env vars.
+- Failed package and stage.
+- Last failed command and exit code.
+- Tail of `spc.output.log`, relevant command block from `spc.shell.log`, and any extra config/CMake log.
+- Whether the failure reproduces after a focused clean or cache refresh.

.github/skills/staticphp-documentation-sync/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: staticphp-documentation-sync
+description: Synchronize bilingual documentation when StaticPHP v3 user-facing or developer-facing documentation must change. Use when adding, modifying, deprecating, or removing documented features, CLI commands/options, environment variables, configuration formats, public APIs/extension points, workflows, installation requirements, migration guidance, or user-visible behavior. Do not use solely for internal implementation changes, package/library additions, or build bug fixes unless they change documented behavior or require updating existing docs.
+---
+
+# StaticPHP Documentation Sync
+
+## Overview
+
+StaticPHP maintains bilingual documentation under `docs/en/` (English) and `docs/zh/` (Chinese). User-facing or developer-facing documentation changes must be reflected in both languages. Use this skill to identify affected docs, update them in sync, and validate sidebar/config consistency.
+
+## When to Use This Skill
+
+Invoke this skill when the change involves:
+
+- New or modified CLI commands, options, or arguments
+- New or changed environment variables
+- Package (extension/library/target/tool) additions, removals, or behavioral changes that affect documented support, dependencies, commands, or workflows
+- Configuration format changes (YAML fields, artifact definitions, registry)
+- Build lifecycle, doctor, or toolchain changes
+- API or extension point changes (attributes, hooks, DI, custom artifacts)
+- Workflow changes (installation, first build, migration)
+- Deprecation or removal of any documented feature
+
+Do not update docs just because code changed. Internal refactors, new libraries used only as dependencies, package build fixes, CI-only changes, and bug fixes that preserve documented behavior usually do not need documentation changes. If existing docs mention the changed behavior, command, package support, dependency, caveat, or workaround, update them.
+
+## Documentation Map
+
+```
+docs/
+├── en/                          # English docs (canonical source)
+│   ├── index.md                 # Home page hero/features
+│   ├── guide/                   # User-facing guides
+│   │   ├── index.md             # Overview
+│   │   ├── installation.md      # Installation instructions
+│   │   ├── first-build.md       # First build walkthrough
+│   │   ├── sapi-reference.md    # PHP SAPI options
+│   │   ├── cli-reference.md     # CLI commands and options
+│   │   ├── cli-generator.md     # Build command generator
+│   │   ├── migrate-from-v2.md   # v2 → v3 migration
+│   │   ├── extensions.md        # Supported extensions list
+│   │   ├── extension-notes.md   # Per-extension notes
+│   │   ├── env-vars.md          # Environment variables
+│   │   ├── deps-map.md          # Dependency map
+│   │   └── troubleshooting.md   # Troubleshooting guide
+│   ├── develop/                 # Developer docs
+│   │   ├── index.md             # Dev overview
+│   │   ├── structure.md         # Project structure
+│   │   ├── registry.md          # Registry model
+│   │   ├── package-model.md     # Package YAML model
+│   │   ├── artifact-model.md    # Artifact YAML model
+│   │   ├── craft-yml.md         # craft.yml reference
+│   │   ├── build-lifecycle.md   # Build stages/lifecycle
+│   │   ├── system-build-tools.md # System tool requirements
+│   │   ├── doctor-module.md     # Doctor module
+│   │   ├── php-src-changes.md   # PHP source patches
+│   │   └── extending/           # Extension authoring
+│   │       ├── index.md
+│   │       ├── package-classes.md
+│   │       ├── annotations.md
+│   │       ├── lifecycle-hooks.md
+│   │       ├── dependency-injection.md
+│   │       └── custom-artifact.md
+│   ├── contributing/
+│   │   └── index.md
+│   └── faq/
+│       └── index.md
+├── zh/                          # Chinese docs (mirrors en/ structure)
+│   └── (same structure as en/)
+├── .vitepress/
+│   ├── sidebar.en.ts            # English sidebar config
+│   ├── sidebar.zh.ts            # Chinese sidebar config
+│   └── config.ts                # VitePress site config
+└── deps-craft-yml.md            # Shared craft.yml include used by both languages
+```
+
+Other documentation files outside this tree may also matter, especially root-level `ext-support.md`.
+
+**Key rule**: `docs/en/` and `docs/zh/` have identical file trees. Every `.md` file under `en/` must have a corresponding file under `zh/`.
+
+## Workflow
+
+### Step 1: Identify Impact Scope
+
+Map the change to affected documentation:
+
+| Change Type | Likely Affected Docs |
+|---|---|
+| New/removed CLI command | `guide/cli-reference.md`, `guide/cli-generator.md` |
+| New/removed CLI option | `guide/cli-reference.md`, `guide/first-build.md` |
+| New env var | `guide/env-vars.md` |
+| New/removed documented extension package | `guide/extensions.md`, `guide/extension-notes.md`, `guide/deps-map.md`, root `ext-support.md` |
+| Package config field change | `develop/package-model.md`, `develop/artifact-model.md` |
+| Build lifecycle change | `develop/build-lifecycle.md` |
+| Doctor change | `develop/doctor-module.md`, `develop/system-build-tools.md` |
+| New attribute/hook/DI | `develop/extending/annotations.md`, `develop/extending/lifecycle-hooks.md`, `develop/extending/dependency-injection.md` |
+| PHP source patch | `develop/php-src-changes.md` |
+| Registry change | `develop/registry.md` |
+| Install/setup change | `guide/installation.md`, `guide/first-build.md` |
+| Deprecation/removal | All docs referencing the feature |
+| New doc page | `sidebar.en.ts`, `sidebar.zh.ts` |
+
+### Step 2: Read Current Docs
+
+Before editing, read BOTH the English and Chinese versions of each affected file to understand the current content and existing translation patterns.
+
+```bash
+# Example: check both language versions of the CLI reference
+cat docs/en/guide/cli-reference.md
+cat docs/zh/guide/cli-reference.md
+```
+
+### Step 3: Update English Docs First
+
+1. Update `docs/en/` files with accurate, complete English content.
+2. Follow existing formatting conventions (headings, code blocks, tables, admonitions).
+3. If adding a new page:
+   - Create the file under `docs/en/<category>/<name>.md`
+   - Add the corresponding entry in `docs/.vitepress/sidebar.en.ts`
+   - Ensure the file has proper VitePress frontmatter if needed
+
+### Step 4: Sync Chinese Docs
+
+1. Update `docs/zh/` files to match the English changes.
+2. Translate all changed or added prose. Do not leave placeholder text or untranslated English in Chinese docs.
+3. Match the structure and formatting of the English version exactly.
+4. If a new page was added in English, create the corresponding `docs/zh/` file and update `docs/.vitepress/sidebar.zh.ts`.
+5. Treat `docs/deps-craft-yml.md` as a special shared include for both languages. If it needs prose changes, either keep the shared content acceptable for both languages or split the included content before adding language-specific prose.
+
+### Step 5: Validate
+
+Run these checks before considering the task complete:
+
+```bash
+# Check that en/ and zh/ have matching file trees
+diff <(find docs/en -name '*.md' | sed 's|docs/en/||' | sort) \
+     <(find docs/zh -name '*.md' | sed 's|docs/zh/||' | sort)
+
+# Check that all sidebar links point to existing files
+# (manual check: every 'link' in sidebar.*.ts must resolve to an actual .md file)
+
+# Build docs when Node dependencies are available; this catches many broken links/config issues
+npm run docs:build
+```
+
+## Translation Guidelines
+
+- **Chinese docs must be complete**: Every section, paragraph, and table in the English docs must have a Chinese equivalent. Never skip sections.
+- **Code blocks and command examples**: Keep executable code and commands identical in both languages. Translate surrounding prose; translate comments inside examples only when they are explanatory docs rather than copy-pasteable source/config.
+- **Technical terms**: Use consistent translations. Refer to existing Chinese docs for established term translations. When in doubt, prefer the term used elsewhere in `docs/zh/`.
+- **Links**: Internal links in Chinese docs should point to `/zh/...` paths (not `/en/...`).
+- **YAML frontmatter**: Keep frontmatter identical between languages (layout, etc.) unless the title/tagline field is translated.
+
+## Common Pitfalls
+
+- **Don't update only one language**: This is the most common mistake. Always update both `en/` and `zh/` in the same change.
+- **Don't forget sidebar configs**: When adding, renaming, or removing doc pages, update both `sidebar.en.ts` and `sidebar.zh.ts`.
+- **Don't forget shared/root docs**: root `ext-support.md` and `docs/deps-craft-yml.md` are also documentation. Update them if relevant.
+- **Don't leave TODO markers**: Do not commit TODO translation placeholders unless the user explicitly allows it or the task is blocked; if that happens, call it out in the final response.
+- **Don't translate file paths or URLs**: Only translate human-readable content, not paths, URLs, command names, or code identifiers.

.github/skills/staticphp-package-maintenance/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: staticphp-package-maintenance
+description: Maintain StaticPHP v3 packages and artifacts. Use when adding, modifying, reviewing, or validating config under config/pkg or config/artifact; package classes under src/Package; extension/library/target/tool dependencies; PHP configure args; build hooks; package metadata; or related tests and docs.
+---
+
+# StaticPHP Package Maintenance
+
+## Overview
+
+Use this skill to make focused package changes without re-reading the entire repository. StaticPHP v3 separates declarative package/artifact YAML from package-specific PHP build logic; prefer config-only edits unless current patterns require a class.
+
+## Quick Workflow
+
+1. Identify the package kind and exact name.
+   - Extension: `config/pkg/ext/ext-name.yml`, class `src/Package/Extension/name.php`.
+   - Library: `config/pkg/lib/name.yml`, class `src/Package/Library/name.php`.
+   - Target or virtual target: `config/pkg/target/name.yml`, class `src/Package/Target/name.php`.
+   - Tool: `config/pkg/tool/name.yml`, class `src/Package/Tool/name.php`.
+   - Shared/custom artifact: `config/artifact/name.yml`, class `src/Package/Artifact/name.php`.
+
+2. Search for the closest existing package before designing anything new.
+   - Similar build system: `rg "#\\[BuildFor|UnixCMakeExecutor|UnixAutoconfExecutor|WindowsCMakeExecutor" src/Package`.
+   - Similar config fields: `rg "static-libs|pkg-configs|arg-type|depends@" config/pkg`.
+   - Similar download type: `rg "type: ghrel|type: pecl|type: pie|type: git|binary: hosted" config`.
+
+3. Read `references/package-reference.md` when changing YAML fields, artifact definitions, package naming, dependencies, platform suffixes, or validation expectations.
+
+4. Read `references/build-class-patterns.md` when PHP build logic, attributes, lifecycle hooks, custom configure args, source patching, or executor usage is needed.
+
+5. Validate narrowly, then broadly if risk warrants it.
+   - Config lint: `php bin/spc dev:lint-config`
+   - Focused tests: `vendor/bin/phpunit tests/StaticPHP/Config tests/StaticPHP/Registry tests/StaticPHP/Util/DependencyResolverTest.php --no-coverage`
+   - Full project checks: `composer test`, `composer analyse`
+
+## Editing Rules
+
+- Treat `config/pkg/*` and `config/artifact/*` as the source of package truth; package classes augment behavior.
+- Use platform suffix fields for declarative OS differences: `@unix`, `@linux`, `@macos`, `@windows`.
+- Add a PHP class only for custom build stages, validation, hook behavior, patches, or custom configure arguments.
+- Keep extension dependencies prefixed with `ext-`; libraries, tools, and targets use their package names.
+- Prefer existing helpers such as `UnixAutoconfExecutor`, `UnixCMakeExecutor`, `WindowsCMakeExecutor`, `shell()`, `cmd()`, and `FileSystem`.
+- Do not modify build outputs (`buildroot/`, `source/`, `downloads/`, `pkgroot/`) to fix package definitions.
+- If upstream metadata changes, update license metadata and smoke-test/display names when relevant.
+
+## Common Task Paths
+
+- Add a new PECL extension: define `config/pkg/ext/ext-name.yml` with `type: php-extension`, `artifact.source.type: pecl`, dependencies, and `php-extension.arg-type`; add a class only if configure args, patches, or hooks are non-standard.
+- Add a library: define `config/pkg/lib/name.yml` with artifact, dependencies, and install verification fields (`headers`, `static-libs`, `pkg-configs`, `static-bins`); add build class methods by OS.
+- Fix an existing package build: start from the failing package config/class, then inspect dependencies and hooks targeting that package before changing shared core code.
+- Update a version source: prefer artifact fields that support update checking (`ghrel`, `ghtar`, `ghtagtar`, `git` with regex, `filelist`, `pecl`, `pie`) over hard-coded URLs when upstream supports it.
+
+## Resources
+
+- `references/package-reference.md`: YAML package/artifact model, naming, fields, validation, and commands.
+- `references/build-class-patterns.md`: PHP package attributes, stages, hooks, executors, and class patterns.

.github/skills/staticphp-package-maintenance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "StaticPHP Package Maintenance"
+  short_description: "Add, update, and validate StaticPHP v3 package definitions."
+  default_prompt: "Use $staticphp-package-maintenance to add, modify, or review StaticPHP package and artifact definitions."

.github/skills/staticphp-package-maintenance/references/build-class-patterns.md

@@ -0,0 +1,143 @@
+# StaticPHP Build Class Patterns
+
+## Contents
+
+- When a class is needed
+- Package attributes
+- Stage and hook behavior
+- Executor choices
+- Common patterns
+- Failure-safe edits
+
+## When a Class Is Needed
+
+Do not add a PHP package class for simple metadata. Use YAML alone when StaticPHP can infer the configure args, dependencies, and verification.
+
+Add or update a class when the package needs:
+
+- OS-specific build commands.
+- Custom validation before building.
+- Custom PHP configure arguments.
+- Patches or file edits before build.
+- Hooks into another package's stage.
+- Custom source/binary download or extraction logic.
+- Package info shown by dev tooling.
+
+Package classes live in `src/Package/*` and are discovered through PSR-4 plus attributes. Config must exist first; `PackageLoader` throws if an attribute references an undefined package.
+
+## Package Attributes
+
+Class-level package attributes:
+
+- `#[Extension('curl')]` maps to package `ext-curl` if the prefix is omitted.
+- `#[Library('openssl')]`
+- `#[Target('php')]`
+- `#[Tool('zig')]`
+
+Method-level attributes:
+
+- `#[BuildFor('Linux'|'Darwin'|'Windows')]`: registers the `build` stage for that OS.
+- `#[Stage('name')]`: registers a named stage; defaults to the method name when omitted.
+- `#[BeforeStage('package', 'stage', 'only-when-package-resolved')]`: hook before a target package stage.
+- `#[AfterStage('package', 'stage', 'only-when-package-resolved')]`: hook after a target package stage.
+- `#[PatchBeforeBuild]`: runs once before package build unless `.spc-patched` exists; return `true` to write that marker.
+- `#[CustomPhpConfigureArg('Linux')]`: supplies custom extension configure args.
+- `#[Validate]`: validates environment/source assumptions.
+- `#[Info]`: returns package information for tooling.
+- `#[InitPackage]`: runs while loading a package class.
+- `#[ResolveBuild]`: target package callback for resolving build dependencies.
+- `#[ConditionalOn(SomeClass::class)]`: conditionally enables before/after hooks only when DI has the class.
+
+## Stage and Hook Behavior
+
+`PackageBuilder::buildPackage()` does:
+
+1. Ensure build directories exist.
+2. Skip if already installed unless forced.
+3. Ensure source exists for non-virtual packages.
+4. Emit `PatchBeforeBuild` callbacks.
+5. Run the `build` stage.
+6. Install license data.
+7. Record tool package versions where relevant.
+
+`Package::runStage()` wraps a stage with:
+
+1. `BeforeStage` callbacks.
+2. The stage method itself.
+3. `AfterStage` callbacks.
+
+SPC exceptions bind package and stage metadata. Preserve that behavior by throwing existing `SPCException` subclasses instead of raw exceptions when adding new failure paths.
+
+## Executor Choices
+
+Use existing executors where possible:
+
+- `UnixAutoconfExecutor`: for Unix packages using `./configure && make && make install`. It injects default static flags and copies `config.log` into SPC logs on failure.
+- `UnixCMakeExecutor`: for Unix CMake packages. It writes toolchain settings and copies CMake configure/error/output logs on failure.
+- `WindowsCMakeExecutor`: for Windows CMake packages.
+- `shell()->cd(...)->initializeEnv($pkg)`: for custom Unix command chains.
+- `cmd()->cd(...)`: for Windows command chains.
+
+Prefer `FileSystem` helpers for file edits and copies so behavior stays consistent.
+
+## Common Patterns
+
+Minimal library class:
+
+```php
+#[Library('example')]
+class example
+{
+    #[BuildFor('Linux')]
+    public function build(LibraryPackage $pkg): void
+    {
+        (new UnixAutoconfExecutor($pkg))
+            ->configure()
+            ->make();
+    }
+}
+```
+
+Extension hook into PHP build:
+
+```php
+#[Extension('curl')]
+class curl
+{
+    #[BeforeStage('php', [php::class, 'makeForWindows'], 'ext-curl')]
+    public function patchBeforePhpBuild(): void
+    {
+        // Adjust env, generated build files, or linker flags.
+    }
+}
+```
+
+Validation:
+
+```php
+#[Validate]
+public function validate(): void
+{
+    if (SystemTarget::getTargetOS() === 'Windows' && WindowsUtil::findCommand('perl.exe') === null) {
+        throw new EnvironmentException('You need to install perl first!');
+    }
+}
+```
+
+Custom configure args should be used when YAML `arg-type` is `custom` or when args need package/install context:
+
+```php
+#[CustomPhpConfigureArg('Linux')]
+public function configureArg(PhpExtensionPackage $ext): string
+{
+    return '--with-example=' . $ext->getBuildRootPath();
+}
+```
+
+## Failure-Safe Edits
+
+- Make hooks conditional with the third `BeforeStage`/`AfterStage` argument when a dependency must be resolved before the hook should run.
+- Keep platform-specific code under matching `#[BuildFor]` methods rather than branching heavily inside one method.
+- If a patch changes upstream source, place patch files in `src/globals/patch/` and describe them with `#[PatchDescription]` where appropriate.
+- If a class only mutates environment variables for another package, search for existing hooks first to avoid duplicate linker flags.
+- After adding attributes, run registry/config tests because invalid stages and unknown packages are caught during loading.

.github/skills/staticphp-package-maintenance/references/package-reference.md

@@ -0,0 +1,157 @@
+# StaticPHP Package Reference
+
+## Contents
+
+- Package locations
+- Package types
+- Artifact model
+- Common YAML fields
+- PHP extension fields
+- Platform suffixes
+- Validation and tests
+
+## Package Locations
+
+StaticPHP v3 keeps package metadata in YAML and behavior in PHP classes.
+
+| Kind | YAML | PHP class namespace | Typical attribute |
+|---|---|---|---|
+| PHP extension | `config/pkg/ext/ext-name.yml` | `Package\Extension` | `#[Extension('name')]` |
+| Library | `config/pkg/lib/name.yml` | `Package\Library` | `#[Library('name')]` |
+| Target | `config/pkg/target/name.yml` | `Package\Target` | `#[Target('name')]` |
+| Virtual target | `config/pkg/target/name.yml` | `Package\Target` | `#[Target('name')]` |
+| Tool | `config/pkg/tool/name.yml` | `Package\Tool` | `#[Tool('name')]` |
+| Custom artifact | `config/artifact/name.yml` | `Package\Artifact` | artifact attributes |
+
+Prefer one package per YAML file unless an existing file groups related definitions. Match nearby naming and ordering.
+
+## Package Types
+
+`php-extension` packages describe PHP extensions. Config package names must use the `ext-` prefix. Dependencies on extensions also use `ext-`.
+
+`library` packages describe buildable dependency libraries. They usually define source artifacts plus verification fields such as headers, static libraries, pkg-config files, or binaries.
+
+`target` packages represent final build outputs and inherit the library-style fields. StaticPHP automatically exposes build commands for targets.
+
+`virtual-target` packages are abstract dependency/build scheduling nodes. They may omit `artifact`.
+
+`tool` packages are helper programs or toolchains installed into `pkgroot/` or used by builds.
+
+## Artifact Model
+
+Artifacts define downloadable source archives or prebuilt binaries. Use inline artifacts for simple one-package sources and `config/artifact/*.yml` for shared, complex, or custom artifacts.
+
+Top-level artifact sections:
+
+- `source`: source archive, git checkout, PECL/PIE package, local directory, or custom source.
+- `binary`: prebuilt binary by platform, or aliases such as `hosted`/`custom`.
+- `metadata`: `license`, `license-files`, and `source-root`.
+
+Common source types:
+
+- `url`: fixed URL; supports `filename`, `version`, and `extract`.
+- `git`: repository source; use `rev` for a fixed branch/tag/commit or `regex` with named `version` capture for update checks.
+- `ghrel`: GitHub release asset by regex filename match.
+- `ghtar`: generated GitHub release tarball.
+- `ghtagtar`: generated GitHub tag tarball.
+- `filelist`: scrape a download index and extract version/filename with regex.
+- `pecl`: PECL extension by name.
+- `pie`: Packagist PIE extension by `vendor/package`.
+- `php-release`: official PHP source selected by build PHP version.
+- `local`: local source directory for development/offline use.
+- `custom`: PHP artifact class handles source or binary logic.
+
+Use `metadata.source-root` when the actual build directory is inside an extracted subdirectory.
+
+Use `metadata.license-files` for source licenses. `@/file.txt` points to bundled license files in `src/globals/licenses/`.
+
+## Common YAML Fields
+
+Shared fields:
+
+- `type`: required package type.
+- `description`: optional human-readable package description.
+- `license`: package-level license annotation where applicable.
+- `lang`: implementation language such as `c` or `c++`.
+- `frameworks`: macOS framework tags.
+- `artifact`: string reference or inline artifact object. Required for `library` and `target`; optional for built-in extensions and virtual targets.
+- `depends`: hard dependencies.
+- `suggests`: optional dependencies.
+
+Library, target, and tool verification/installation fields:
+
+- `headers`: expected files/directories under `buildroot/include`.
+- `static-libs`: expected static libraries under `buildroot/lib`.
+- `pkg-configs`: expected `.pc` files under `buildroot/lib/pkgconfig`.
+- `static-bins`: expected executables under `buildroot/bin`.
+- `path`: directories appended to PATH after install.
+- `env`: environment variables set after install.
+- `append-env`: values appended to existing environment variables.
+
+Path placeholders in `path`, `env`, and `append-env`:
+
+- `{build_root_path}`: `buildroot/`
+- `{pkg_root_path}`: `pkgroot/`
+- `{working_dir}`: repository or working directory
+- `{download_path}`: `downloads/`
+- `{source_path}`: `source/`
+- `{spc_msys2_path}`: MSYS2 root on Windows
+
+## PHP Extension Fields
+
+Extension-specific fields live under `php-extension`.
+
+- `arg-type`: configure argument behavior. Built-ins include `enable`, `enable-path`, `with`, `with-path`, `custom`, and `none`. Full strings are allowed.
+- `zend-extension`: true for Zend extensions such as opcache/xdebug.
+- `build-shared`: whether shared builds are allowed.
+- `build-static`: whether static builds are allowed.
+- `build-with-php`: true when built inside the PHP source tree.
+- `display-name`: value used for `php --ri` smoke tests and license display; empty string skips the `--ri` check.
+- `os`: allowed OS families: `Linux`, `Darwin`, `Windows`.
+
+Configure string placeholders:
+
+- `@build_root_path@`: absolute buildroot path.
+- `@shared_suffix@`: `=shared` in shared builds, empty in static builds.
+- `@shared_path_suffix@`: `=shared,{buildroot}` in shared builds, `={buildroot}` in static builds.
+
+## Platform Suffixes
+
+Many fields support platform suffixes:
+
+- `@unix`: Linux and macOS.
+- `@linux`: Linux only.
+- `@macos`: macOS only.
+- `@windows`: Windows only.
+
+For Linux, specific fields override generic fields in this order: `field@linux`, then `field@unix`, then `field`.
+
+Use suffixes for declarative differences in dependencies, headers, libraries, pkg-configs, extension args, and suggestions.
+
+## Validation and Tests
+
+Run config validation for most package edits:
+
+```bash
+php bin/spc dev:lint-config
+```
+
+Run focused tests after config or registry changes:
+
+```bash
+vendor/bin/phpunit tests/StaticPHP/Config tests/StaticPHP/Registry tests/StaticPHP/Util/DependencyResolverTest.php --no-coverage
+```
+
+Run broader checks for framework or class changes:
+
+```bash
+composer test
+composer analyse
+```
+
+Build commands are expensive. Use them for user-provided repros, package-specific fixes, or when validation cannot prove the behavior:
+
+```bash
+php bin/spc build:libs "openssl,curl" -vvv
+php bin/spc build:php "bcmath,openssl,curl" --build-cli -vvv
+```

.github/workflows/build-unix.yml

@@ -331,5 +331,4 @@ jobs:
         with:
           name: build-meta-${{ inputs.php-version }}-${{ inputs.os }}
           path: |
-            buildroot/build-extensions.json
-            buildroot/build-libraries.json
+            buildroot/build-manifest.json

.github/workflows/build-windows-x86_64.yml

@@ -115,5 +115,4 @@ jobs:
         with:
           name: build-meta
           path: |
-            buildroot/build-extensions.json
-            buildroot/build-libraries.json
+            buildroot/build-manifest.json

.github/workflows/ext-matrix-tests.yml

@@ -2,13 +2,14 @@ name: "Extension Matrix Tests"
 
 on:
   workflow_dispatch:
-  push:
+  pull_request:
+    types: [opened, synchronize, labeled]
 
 jobs:
   test:
     name: "${{ matrix.extension }} (PHP ${{ matrix.php-version }} on ${{ matrix.operating-system }})"
     runs-on: ${{ matrix.operating-system }}
-    if: contains(github.event.head_commit.message, 'extension test') || contains(github.event.head_commit.message, 'test extensions')
+    if: contains(github.event.pull_request.labels.*.name, 'need-full-test')
     strategy:
       fail-fast: false
       matrix:

.github/workflows/post-test-bot-comment.yml

@@ -0,0 +1,48 @@
+name: Post Test Bot Comment
+
+on:
+  workflow_run:
+    workflows: ["v3 Tests"]
+    types: [completed]
+
+permissions:
+  pull-requests: write
+  actions: read
+
+jobs:
+  post-comment:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Download bot output
+        id: download
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+        with:
+          name: bot-output
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post/Update comment
+        if: steps.download.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          COMMENT_BODY=$(jq -r '.comment_body' bot-output.json)
+          PR_NUMBER=$(jq -r '.pr_number' bot-output.json)
+          MARKER="<!-- spc-test-bot -->"
+
+          # Find existing bot comment id
+          EXISTING_ID=$(gh api \
+            "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+            --jq "[.[] | select(.body | startswith(\"${MARKER}\")) | .id] | first // empty")
+
+          if [ -n "$EXISTING_ID" ]; then
+            gh api --method PATCH \
+              "repos/${{ github.repository }}/issues/comments/${EXISTING_ID}" \
+              -f body="$COMMENT_BODY"
+          else
+            gh pr comment "$PR_NUMBER" \
+              --repo "${{ github.repository }}" \
+              --body "$COMMENT_BODY"
+          fi

.github/workflows/release-build.yml

@@ -38,6 +38,9 @@ jobs:
           - name: "windows-x64"
             os: "ubuntu-latest"
             filename: "spc-windows-x64.exe"
+    permissions:
+      id-token: write
+      attestations: write
     steps:
       - name: "Checkout"
         uses: "actions/checkout@v5"
@@ -105,6 +108,12 @@ jobs:
             fi
           fi
 
+      - name: "Generate build provenance attestation"
+        if: github.event_name != 'pull_request'
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: "${{ github.workspace }}/${{ matrix.operating-system.name == 'windows-x64' && 'spc.exe' || 'spc' }}"
+
       - name: "Copy file"
         run: |
           if [ "${{ matrix.operating-system.name }}" != "windows-x64" ]; then
@@ -120,6 +129,18 @@ jobs:
         with:
           files: dist/${{ matrix.operating-system.filename }}
 
+      - name: "Deploy to self-hosted OSS (nightly)"
+        # only run this step if the repository is static-php-cli and is push to v3 branch
+        if: ${{ github.repository == 'crazywhalecc/static-php-cli' && github.ref == 'refs/heads/v3' }}
+        uses: static-php/upload-s3-action@v1.0.0
+        with:
+          aws_key_id: ${{ secrets.AWS_KEY_ID }}
+          aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws_bucket: ${{ secrets.AWS_BUCKET }}
+          source_dir: "dist/"
+          destination_dir: v3/spc-bin/nightly/
+          endpoint: ${{ secrets.AWS_ENDPOINT }}
+
       - name: "Deploy to self-hosted OSS (latest)"
         # only run this step if the repository is static-php-cli and is release tag
         if: ${{ github.repository == 'crazywhalecc/static-php-cli' && startsWith(github.ref, 'refs/tags/') }}

.github/workflows/tests.yml

@@ -1,9 +1,9 @@
-name: Tests
+name: v3 Tests
 
 on:
   pull_request:
-    branches: [ "main", "v3" ]
-    types: [ opened, synchronize, reopened ]
+    branches: [ "v3" ]
+    types: [ opened, synchronize, reopened, labeled, unlabeled ]
     paths:
       - 'src/**'
       - 'config/**'
@@ -15,6 +15,10 @@ on:
 
 permissions: read-all
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -103,114 +107,164 @@ jobs:
         run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
 
       - name: "Run PHPUnit Tests"
-        run: SPC_LIBC=glibc vendor/bin/phpunit tests/ --no-coverage
+        run: vendor/bin/phpunit tests/ --no-coverage
 
-  define-matrix:
-    if: false # TODO: enable when refactoring workflows
-    name: "Define Matrix"
+  check-gate:
+    name: "Check: need-test label"
     runs-on: ubuntu-latest
     outputs:
-      php: ${{ steps.gendef.outputs.php }}
-      os: ${{ steps.gendef.outputs.os }}
+      enabled: ${{ steps.gate.outputs.enabled }}
     steps:
-      - name: "Checkout"
-        uses: actions/checkout@v4
-
-      - name: "Setup PHP"
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: 8.4
-          extensions: curl, openssl, mbstring
-
-      - name: Define
-        id: gendef
+      - name: Check label
+        id: gate
         run: |
-          PHP_VERSIONS=$(php src/globals/test-extensions.php php)
-          OS_VERSIONS=$(php src/globals/test-extensions.php os)
-          echo 'php='"$PHP_VERSIONS" >> "$GITHUB_OUTPUT"
-          echo 'os='"$OS_VERSIONS" >> "$GITHUB_OUTPUT"
+          LABELS='${{ toJSON(github.event.pull_request.labels.*.name) }}'
+          if echo "$LABELS" | grep -q '"need-test"'; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          fi
 
-
-  build:
-    if: false
-    name: "Build PHP Test (PHP ${{ matrix.php }} ${{ matrix.os }})"
-    runs-on: ${{ matrix.os }}
-    needs: [define-matrix, php-cs-fixer, phpstan, phpunit]
-    timeout-minutes: 120
-    strategy:
-      matrix:
-        php: ${{ fromJSON(needs.define-matrix.outputs.php) }}
-        os: ${{ fromJSON(needs.define-matrix.outputs.os) }}
-      fail-fast: false
+  test-bot:
+    name: "Test Bot: analyze PR"
+    needs: check-gate
+    if: needs.check-gate.outputs.enabled == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      need_test:             ${{ steps.bot.outputs.need_test }}
+      gen_matrix_args:       ${{ steps.bot.outputs.gen_matrix_args }}
+      gen_matrix_args_tier2: ${{ steps.bot.outputs.gen_matrix_args_tier2 }}
+      php_versions:          ${{ steps.bot.outputs.php_versions }}
+      tier2:                 ${{ steps.bot.outputs.tier2 }}
     steps:
-      - name: "Update runner packages"
-        if: ${{ startsWith(matrix.os, 'ubuntu-') }}
-        run: sudo apt-get update && sudo apt-get install -y ca-certificates
+      - uses: actions/checkout@v4
 
-      - name: "Checkout"
-        uses: actions/checkout@v4
-
-      - name: "Setup PHP"
+      - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.4
-          tools: pecl, composer
+          php-version: '8.4'
           extensions: curl, openssl, mbstring
           ini-values: memory_limit=-1
+          tools: composer
+
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist --no-dev
+
+      - name: Run dev:test-bot
+        id: bot
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BOT_JSON=$(php -d opcache.enable_cli=0 bin/spc dev:test-bot \
+            --pr=${{ github.event.pull_request.number }} \
+            --repo=${{ github.repository }} 2>/dev/null)
+
+          echo "need_test=$(echo "$BOT_JSON" | jq -r '.need_test')"                     >> "$GITHUB_OUTPUT"
+          echo "gen_matrix_args=$(echo "$BOT_JSON" | jq -r '.gen_matrix_args')"           >> "$GITHUB_OUTPUT"
+          echo "gen_matrix_args_tier2=$(echo "$BOT_JSON" | jq -r '.gen_matrix_args_tier2')" >> "$GITHUB_OUTPUT"
+          echo "php_versions=$(echo "$BOT_JSON" | jq -c '.php_versions')"                 >> "$GITHUB_OUTPUT"
+          echo "tier2=$(echo "$BOT_JSON" | jq -r '.tier2')"                               >> "$GITHUB_OUTPUT"
+
+          # Save JSON for the comment-posting workflow
+          jq -n --argjson bot "$BOT_JSON" \
+            --arg pr '${{ github.event.pull_request.number }}' \
+            '$bot + {pr_number: $pr}' > bot-output.json
+
+      - name: Upload bot output
+        uses: actions/upload-artifact@v4
+        with:
+          name: bot-output
+          path: bot-output.json
+          retention-days: 1
+
+  gen-matrix:
+    name: "Generate test matrix"
+    needs: test-bot
+    if: needs.test-bot.outputs.need_test == 'true'
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.build.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: curl, openssl, mbstring
+          ini-values: memory_limit=-1
+          tools: composer
+
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist --no-dev
+
+      - name: Build matrix
+        id: build
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GEN_MATRIX_ARGS:       ${{ needs.test-bot.outputs.gen_matrix_args }}
+          GEN_MATRIX_ARGS_TIER2: ${{ needs.test-bot.outputs.gen_matrix_args_tier2 }}
+          PHP_VERSIONS:          ${{ needs.test-bot.outputs.php_versions }}
+          TIER2:                 ${{ needs.test-bot.outputs.tier2 }}
+        run: |
+          # Tier1 matrix
+          MATRIX1=$(bin/spc dev:gen-ext-test-matrix $GEN_MATRIX_ARGS 2>/dev/null)
+
+          # Merge Tier2 if requested
+          if [ "$TIER2" = "true" ] && [ -n "$GEN_MATRIX_ARGS_TIER2" ]; then
+            MATRIX2=$(bin/spc dev:gen-ext-test-matrix $GEN_MATRIX_ARGS_TIER2 2>/dev/null)
+            COMBINED=$(jq -n --argjson m1 "$MATRIX1" --argjson m2 "$MATRIX2" '$m1 + $m2')
+          else
+            COMBINED=$MATRIX1
+          fi
+
+          # Expand PHP versions: cartesian product of entries × php_versions
+          FINAL=$(echo "$COMBINED" | jq --argjson versions "$PHP_VERSIONS" \
+            '[.[] | . as $entry | $versions[] | $entry + {"php-version": .}]')
+
+          echo "matrix=$(echo "$FINAL" | jq -c '{"combo": .}')" >> "$GITHUB_OUTPUT"
+
+  ext-test:
+    name: "Ext test: ${{ matrix.combo.extension }} [${{ matrix.combo.sapi }}] (PHP ${{ matrix.combo.php-version }} - ${{ matrix.combo.os }}-${{ matrix.combo.arch }})"
+    needs: gen-matrix
+    runs-on: ${{ matrix.combo.runner }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.gen-matrix.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.4
+          extensions: curl, openssl, mbstring
+          ini-values: memory_limit=-1
+          tools: composer
         env:
           phpts: nts
 
-      - name: "Cache composer packages"
-        id: composer-cache
-        uses: actions/cache@v4
-        with:
-          path: vendor
-          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-php-
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist --no-dev
 
-      # Cache downloaded source
-      - id: cache-download
-        uses: actions/cache@v4
-        with:
-          path: downloads
-          key: php-dependencies-${{ matrix.os }}
-
-      - name: "Install Dependencies"
-        run: composer update -vvv --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist --no-plugins
-
-      - name: "Run Build Tests (doctor)"
-        run: php src/globals/test-extensions.php doctor_cmd ${{ matrix.os }} ${{ matrix.php }}
-
-      - name: "Prepare UPX for Windows"
-        if: ${{ startsWith(matrix.os, 'windows-') }}
+      - name: Build
+        env:
+          SPC_USE_SUDO: "yes"
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          php src/globals/test-extensions.php install_upx_cmd ${{ matrix.os }} ${{ matrix.php }}
-          echo "UPX_CMD=$(php src/globals/test-extensions.php upx)" >> $env:GITHUB_ENV
+          ./bin/spc doctor --auto-fix
+          ${{ matrix.combo.build-args }} --dl-with-php=${{ matrix.combo.php-version }}
 
-      - name: "Prepare UPX for Linux"
-        if: ${{ startsWith(matrix.os, 'ubuntu-') }}
-        run: |
-          php src/globals/test-extensions.php install_upx_cmd ${{ matrix.os }} ${{ matrix.php }}
-          echo "UPX_CMD=$(php src/globals/test-extensions.php upx)" >> $GITHUB_ENV
-
-      - name: "Run Build Tests (download)"
-        run: php src/globals/test-extensions.php download_cmd ${{ matrix.os }} ${{ matrix.php }}
-
-      - name: "Run Build Tests (build)"
-        run: php src/globals/test-extensions.php build_cmd ${{ matrix.os }} ${{ matrix.php }}
-
-      - name: "Run Build Tests (build - embed for non-windows)"
-        if: ${{ !startsWith(matrix.os, 'windows-') }}
-        run: php src/globals/test-extensions.php build_embed_cmd ${{ matrix.os }} ${{ matrix.php }}
-
-      - name: "Upload logs"
-        if: ${{ always() && hashFiles('log/**') != '' }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: build-logs-${{ matrix.os }}-${{ matrix.php }}
-          path: log
-
-#      - name: Setup tmate session
+#      - name: Setup upterm session
 #        if: ${{ failure() }}
-#        uses: mxschmitt/action-tmate@v3
+#        uses: owenthereal/action-upterm@v1
+
+      - name: Upload logs
+        if: always() && hashFiles('log/**') != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: logs-${{ matrix.combo.os }}-${{ matrix.combo.arch }}-${{ matrix.combo.sapi }}-${{ matrix.combo.extension }}-php${{ matrix.combo.php-version }}
+          path: log

.github/workflows/vitepress-deploy.yml

@@ -1,73 +1,73 @@
-name: Docs Auto Deploy
-on:
-  push:
-    branches:
-      - v3
-    paths:
-      - 'config/**.yml'
-      - 'docs/**'
-      - 'package.json'
-      - 'yarn.lock'
-      - '.github/workflows/vitepress-deploy.yml'
-
-jobs:
-  build:
-    name: Deploy docs
-    runs-on: ubuntu-latest
-    if: github.repository == 'crazywhalecc/static-php-cli'
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v3
-        with:
-          cache: yarn
-
-      - run: yarn install --frozen-lockfile
-
-      - name: "Copy Config Files"
-        run: |
-          mkdir -p docs/.vitepress/config
-          cp -r config/* docs/.vitepress/config/
-
-      - name: "Install PHP for official runners"
-        uses: shivammathur/setup-php@v2
-        with:
-          coverage: none
-          tools: composer:v2
-          php-version: 8.4
-          ini-values: memory_limit=-1
-          extensions: curl, openssl, mbstring
-
-      - name: "Get Composer Cache Directory"
-        id: composer-cache
-        run: |
-          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
-
-      - name: "Cache Composer dependencies"
-        uses: "actions/cache@v4"
-        with:
-          path: "${{ steps.composer-cache.outputs.dir }}"
-          key: "php-8.2-locked-composer-${{ hashFiles('**/composer.lock') }}"
-          restore-keys: |
-            php-8.2-locked-composer
-
-      - name: "Install Locked Dependencies"
-        run: "composer install --no-interaction --no-progress"
-
-      # TODO: Uncomment when v3 gen commands are implemented
-      # - name: "Generate Extension Support List"
-      #   run: |
-      #     bin/spc dev:gen-ext-docs > docs/en/guide/extensions.md
-      #     bin/spc dev:gen-ext-docs > docs/zh/guide/extensions.md
-      #     bin/spc dev:gen-ext-dep-docs > docs/en/guide/deps-map.md
-      #     bin/spc dev:gen-ext-dep-docs > docs/zh/guide/deps-map.md
-
-      - name: Build
-        run: yarn docs:build
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/.vitepress/dist
+name: Docs build test and auto deploy
+on:
+  pull_request:
+    branches: [ "v3" ]
+    types: [ opened, synchronize, reopened ]
+    paths:
+      - 'config/**.yml'
+      - 'docs/**'
+      - 'package.json'
+      - 'yarn.lock'
+      - '.github/workflows/vitepress-deploy.yml'
+  push:
+    branches: [ "v3" ]
+    paths:
+      - 'config/**.yml'
+      - 'docs/**'
+      - 'package.json'
+      - 'yarn.lock'
+      - '.github/workflows/vitepress-deploy.yml'
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    if: github.repository == 'crazywhalecc/static-php-cli'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+
+      - name: Install documentation dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: "Install PHP for official runners"
+        uses: shivammathur/setup-php@v2
+        with:
+          coverage: none
+          tools: composer:v2
+          php-version: 8.4
+          ini-values: memory_limit=-1
+          extensions: curl, openssl, mbstring
+
+      - name: "Get Composer Cache Directory"
+        id: composer-cache
+        run: |
+          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: "Cache Composer dependencies"
+        uses: "actions/cache@v4"
+        with:
+          path: "${{ steps.composer-cache.outputs.dir }}"
+          key: "php-8.2-locked-composer-${{ hashFiles('**/composer.lock') }}"
+          restore-keys: |
+            php-8.2-locked-composer
+
+      - name: "Install Locked Dependencies"
+        run: "composer install --no-interaction --no-progress"
+
+      - name: Build
+        run: yarn docs:build
+
+      # Deploy to GitHub Pages only when the workflow is triggered by a push to the v3 branch
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.event_name == 'push' && github.ref == 'refs/heads/v3'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/.vitepress/dist

.gitignore

@@ -52,6 +52,7 @@ packlib_files.txt
 /node_modules/
 /docs/.vitepress/dist/
 /docs/.vitepress/cache/
+/docs/.vitepress/.temp/
 /docs/.vitepress/ext-data.json
 /docs/.vitepress/deps-data.json
 package-lock.json

AGENTS.md

@@ -0,0 +1,60 @@
+# StaticPHP v3 Agent Guide
+
+StaticPHP is a PHP CLI application for building static PHP binaries, PHP SAPIs, extensions, libraries, helper tools, and project bundles. Prefer the v3 architecture under `src/StaticPHP`, `src/Package`, `config/pkg`, and `config/artifact`.
+
+This file is the shared entry point for coding agents such as Codex, OpenCode, Claude-compatible agents, and GitHub Copilot agents. GitHub Copilot also has `.github/copilot-instructions.md`.
+
+## Skills
+
+Detailed task workflows live in `.github/skills`. Use them when the task matches:
+
+- `.github/skills/staticphp-package-maintenance`: add, modify, review, or validate package, artifact, extension, library, target, or tool definitions.
+- `.github/skills/staticphp-build-troubleshooting`: diagnose build, download, doctor, shell, terminal, CI, smoke-test, or log failures.
+- `.github/skills/staticphp-documentation-sync`: synchronize bilingual documentation (`docs/en/` and `docs/zh/`) when features, commands, configuration, APIs, or behavior change.
+
+If your agent does not automatically discover skills from `.github/skills`, read the matching `SKILL.md` manually before working on that task.
+
+## Project Map
+
+- `bin/spc`: primary CLI entrypoint.
+- `composer.json`: PHP 8.4+, Symfony Console, DI, YAML, logger; useful scripts are `composer test`, `composer analyse`, `composer lint-config`, and `composer cs-fix`.
+- `spc.registry.yml`: built-in `core` registry.
+- `config/pkg/ext`: PHP extension package YAML, usually named `ext-*.yml`.
+- `config/pkg/lib`: library package YAML.
+- `config/pkg/target`: final build target and virtual target YAML.
+- `config/pkg/tool`: helper tool package YAML.
+- `config/artifact`: standalone artifact YAML for shared or complex sources/binaries.
+- `log/`: build and shell execution logs (`spc.output.log`, `spc.shell.log`, and per-package CMake/config logs); controlled by `SPC_LOGS_DIR` and `SPC_ENABLE_LOG_FILE`.
+- `src/StaticPHP`: framework core: registry loading, config validation, dependency resolution, package install/build pipeline, doctor, toolchains, runtime shell/executors, exceptions.
+- `src/Package`: package-specific build logic registered by PHP attributes.
+- `src/globals`: constants, helper functions, patches, smoke tests, bundled license text.
+- `tests`: PHPUnit tests for config, registry, artifacts, dependency resolver, DI, commands, and utilities.
+- `docs/en/develop` and `docs/zh/develop`: developer documentation. Some pages may be TODO; verify against source when behavior matters.
+
+## Working Rules
+
+- Keep changes scoped to the requested package, artifact, command, docs, or tests.
+- Prefer existing package patterns over new abstractions. Search for a similar package first.
+- Use structured YAML config; do not encode dependency logic in PHP when config fields are enough.
+- Match package names exactly: extension packages use `ext-` in config and dependencies; `#[Extension('curl')]` expands to `ext-curl`.
+- Use platform suffixes such as `@unix`, `@linux`, `@macos`, and `@windows` instead of runtime conditionals when the difference is declarative.
+- Add or update PHP package classes only when build commands, validation, custom configure args, hooks, or source patching are required.
+- Do not edit generated build directories (`buildroot/`, `source/`, `downloads/`, `pkgroot/`) as a fix.
+
+## Validation
+
+For config or package changes, run CS checks first:
+
+```bash
+bin/spc dev:lint-config
+composer cs-fix
+```
+
+For broader PHP code changes, also run:
+
+```bash
+composer test
+composer analyse
+```
+
+Use build commands only when needed for the task or when the user provided a repro, because full static builds can be slow and platform-sensitive.

README-zh.md

@@ -1,150 +1,156 @@
-# StaticPHP
-
-[![Chinese readme](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87%20%F0%9F%87%A8%F0%9F%87%B3-moccasin?style=flat-square)](README-zh.md)
-[![English readme](https://img.shields.io/badge/README-English%20%F0%9F%87%AC%F0%9F%87%A7-moccasin?style=flat-square)](README.md)
-[![Releases](https://img.shields.io/packagist/v/crazywhalecc/static-php-cli?include_prereleases&label=Release&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/releases)
-[![CI](https://img.shields.io/github/actions/workflow/status/crazywhalecc/static-php-cli/tests.yml?branch=main&label=Build%20Test&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/actions/workflows/tests.yml)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/crazywhalecc/static-php-cli/blob/main/LICENSE)
-
-**StaticPHP** 是一个强大的工具，用于构建可移植的可执行文件，包括 PHP、扩展等。
-
-## 特性
-
-- :elephant: 支持多个 PHP 版本 - PHP 8.1, 8.2, 8.3, 8.4, 8.5
-- :handbag: 构建零依赖的单文件 PHP 可执行程序
-- :hamburger: 构建 **[phpmicro](https://github.com/static-php/phpmicro)** 自解压可执行文件（将 PHP 二进制和源码合并为单个文件）
-- :pill: 自动构建环境检查器，支持自动修复
-- :zap: 支持 `Linux`、`macOS`、`Windows`
-- :wrench: 通过 vendor 模式和自定义注册表实现便捷扩展
-- :books: 智能依赖管理
-- 📦 自包含 `spc` 可执行文件，便于自安装
-- :fire: 支持 100+ 热门 [PHP 扩展](https://static-php.dev/en/guide/extensions.html)
-- :floppy_disk: 支持 UPX 压缩（二进制体积可缩小 30-50%）
-
-**单文件独立 php-cli：**
-
-<img width="700" alt="out1" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/01a2e60f-13b0-4242-a645-f7afa4936396">
-
-**使用 phpmicro 将 PHP 代码与 PHP 解释器结合：**
-
-<img width="700" alt="out2" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/46b7128d-fb72-4169-957e-48564c3ff3e2">
-
-## 快速开始
-
-### 1. 下载 spc 二进制
-
-```bash
-# For Linux x86_64
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-x86_64
-# For Linux aarch64
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-aarch64
-# macOS x86_64 (Intel)
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-x86_64
-# macOS aarch64 (Apple)
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-aarch64
-# 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/latest/spc-windows-x64.exe
-```
-
-对于 macOS 和 Linux，请先添加可执行权限：
-
-```bash
-chmod +x ./spc
-```
-
-### 2. 构建静态 PHP
-
-首先，创建 `craft.yml` 文件，并从 [扩展列表](https://static-php.dev/en/guide/extensions.html) 或 [命令生成器](https://static-php.dev/en/guide/cli-generator.html) 指定要包含的扩展：
-
-```yml
-# 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
-```
-
-运行命令：
-
-```bash
-./spc craft
-
-# 输出完整控制台日志
-./spc craft -vvv
-```
-
-### 3. 静态 PHP 使用
-
-现在你可以将 StaticPHP 构建的二进制复制到另一台机器并在无依赖环境下运行：
-
-```
-# php-cli
-buildroot/bin/php -v
-
-# phpmicro
-echo '<?php echo "Hello world!\n";' > a.php
-./spc micro:combine a.php -O my-app
-./my-app
-```
-
-## 文档
-
-当前 README 包含基础用法。有关 StaticPHP 的完整功能集，
-请访问 <https://static-php.dev>。
-
-## 直接下载
-
-如果你暂时不想构建，或只想先测试，可以从 [Actions](https://github.com/static-php/static-php-cli-hosted/actions/workflows/build-php-bulk.yml) 下载示例预编译产物，或从自托管服务器下载。
-
-我们为每个 PHP 版本提供 2 种扩展集合：
-
-- **gigantic**：尽可能包含更多扩展，二进制大小约 100-150MB。
-- **base**：仅包含 StaticPHP 自身使用的少量扩展，二进制大小约 10MB。
-
-> WIP
-
-### 在线构建（使用 GitHub Actions）
-
-当上方直接下载的二进制无法满足你的需求时，
-你可以使用 GitHub Actions 轻松构建静态编译的 PHP，
-并同时自定义要编译的扩展列表。
-
-1. Fork 此仓库。
-2. 进入项目的 Actions 并选择 `CI`。
-3. 选择 `Run workflow`，填写你要编译的 PHP 版本、目标类型和扩展列表。（扩展用逗号分隔，例如 `bcmath,curl,mbstring`）
-4. 等待工作流执行完成后，进入对应运行记录并下载 `Artifacts`。
-
-如果你启用 `debug`，构建时将输出所有日志，包括编译日志，便于排查问题。
-
-> 我们也计划在未来提供可复用的 GitHub Actions 工作流，
-> 这样你无需 fork 本项目，也能在自己的仓库中轻松构建 static PHP。
-
-## 贡献
-
-如果你需要的扩展缺失，可以创建 issue。
-如果你熟悉本项目，也欢迎发起 pull request。
-
-如果你想贡献文档，请直接编辑 `docs/`。
-
-## 赞助本项目
-
-你可以通过 [GitHub Sponsor](https://github.com/crazywhalecc) 赞助我或我的项目。你捐赠的一部分将用于维护 **static-php.dev** 服务器。
-
-**特别感谢以下赞助商：**
-
-<a href="https://beyondco.de/"><img src="/docs/public/images/beyondcode-seeklogo.png" width="300" alt="Beyond Code Logo" /></a>
-
-<a href="https://nativephp.com/"><img src="/docs/public/images/nativephp-logo.svg" width="300" alt="NativePHP Logo" /></a>
-
-## 开源许可证
-
-本项目本身采用 MIT 许可证。
-一些新添加的扩展和依赖可能来自其他项目。
-这些源码文件头部也可能包含额外的 LICENSE 和 AUTHOR 信息。
-
-请在编译后使用 `bin/spc dump-license` 命令导出项目中使用的开源许可证，
-并遵守对应项目的 LICENSE。
+# StaticPHP
+
+[![Chinese readme](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87%20%F0%9F%87%A8%F0%9F%87%B3-moccasin?style=flat-square)](README-zh.md)
+[![English readme](https://img.shields.io/badge/README-English%20%F0%9F%87%AC%F0%9F%87%A7-moccasin?style=flat-square)](README.md)
+[![Releases](https://img.shields.io/packagist/v/crazywhalecc/static-php-cli?include_prereleases&label=Release&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/releases)
+[![CI](https://img.shields.io/github/actions/workflow/status/crazywhalecc/static-php-cli/tests.yml?branch=main&label=Build%20Test&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/crazywhalecc/static-php-cli/blob/main/LICENSE)
+[![Discord](https://img.shields.io/discord/nrSRbpMJ?label=Discord&logo=discord&style=flat-square)](https://discord.gg/xf6Rd4pEAk)
+
+**StaticPHP** 是一个强大的工具，用于构建可移植的可执行文件，包括 PHP、扩展等。
+
+> [!IMPORTANT]
+> 我们正准备发布 **v3** 版本，届时项目名称将从 **static-php-cli** 更改为 **StaticPHP**。
+> 此分支对应 v3 版本。v2 版本请查看 [v2 分支](https://github.com/crazywhalecc/static-php-cli/tree/main)。
+> 请更新您的参考资料，并关注正式版发布。
+
+## 特性
+
+- :elephant: 支持多个 PHP 版本 - PHP 8.1, 8.2, 8.3, 8.4, 8.5
+- :handbag: 构建零依赖的单文件 PHP 可执行程序
+- :hamburger: 构建 **[phpmicro](https://github.com/static-php/phpmicro)** 自解压可执行文件（将 PHP 二进制和源码合并为单个文件）
+- :pill: 自动构建环境检查器，支持自动修复
+- :zap: 支持 `Linux`、`macOS`、`Windows`
+- :wrench: 通过 vendor 模式和自定义注册表实现便捷扩展
+- :books: 智能依赖管理
+- 📦 自包含 `spc` 可执行文件，便于自安装
+- :fire: 支持 100+ 热门 [PHP 扩展](https://static-php.dev/en/guide/extensions.html)
+- :floppy_disk: 支持 UPX 压缩（二进制体积可缩小 30-50%）
+
+**单文件独立 php-cli：**
+
+<img width="700" alt="out1" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/01a2e60f-13b0-4242-a645-f7afa4936396">
+
+**使用 phpmicro 将 PHP 代码与 PHP 解释器结合：**
+
+<img width="700" alt="out2" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/46b7128d-fb72-4169-957e-48564c3ff3e2">
+
+## 快速开始
+
+### 1. 下载 spc 二进制
+
+```bash
+# For Linux x86_64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
+# For Linux aarch64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64
+# macOS x86_64 (Intel)
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64
+# macOS aarch64 (Apple)
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64
+# 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
+```
+
+对于 macOS 和 Linux，请先添加可执行权限：
+
+```bash
+chmod +x ./spc
+```
+
+### 2. 构建静态 PHP
+
+首先，创建 `craft.yml` 文件，并从 [扩展列表](https://static-php.dev/en/guide/extensions.html) 或 [命令生成器](https://static-php.dev/en/guide/cli-generator.html) 指定要包含的扩展：
+
+```yml
+# 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
+```
+
+运行命令：
+
+```bash
+./spc craft
+
+# 输出完整控制台日志
+./spc craft -vvv
+```
+
+### 3. 静态 PHP 使用
+
+现在你可以将 StaticPHP 构建的二进制复制到另一台机器并在无依赖环境下运行：
+
+```
+# php-cli
+buildroot/bin/php -v
+
+# phpmicro
+echo '<?php echo "Hello world!\n";' > a.php
+./spc micro:combine a.php -O my-app
+./my-app
+```
+
+## 文档
+
+当前 README 包含基础用法。有关 StaticPHP 的完整功能集，
+请访问 <https://static-php.dev>。
+
+## 直接下载
+
+如果你暂时不想构建，或只想先测试，可以从 [Actions](https://github.com/static-php/hosted/actions/workflows/build-php-bulk.yml) 下载示例预编译产物，或从自托管服务器下载。
+
+我们为每个 PHP 版本提供 2 种扩展集合：
+
+- **gigantic**：尽可能包含更多扩展，二进制大小约 100-150MB。
+- **base**：仅包含 StaticPHP 自身使用的少量扩展，二进制大小约 10MB。
+
+> WIP
+
+### 在线构建（使用 GitHub Actions）
+
+当上方直接下载的二进制无法满足你的需求时，
+你可以使用 GitHub Actions 轻松构建静态编译的 PHP，
+并同时自定义要编译的扩展列表。
+
+1. Fork 此仓库。
+2. 进入项目的 Actions 并选择 `CI`。
+3. 选择 `Run workflow`，填写你要编译的 PHP 版本、目标类型和扩展列表。（扩展用逗号分隔，例如 `bcmath,curl,mbstring`）
+4. 等待工作流执行完成后，进入对应运行记录并下载 `Artifacts`。
+
+如果你启用 `debug`，构建时将输出所有日志，包括编译日志，便于排查问题。
+
+> 我们也计划在未来提供可复用的 GitHub Actions 工作流，
+> 这样你无需 fork 本项目，也能在自己的仓库中轻松构建 static PHP。
+
+## 贡献
+
+如果你需要的扩展缺失，可以创建 issue。
+如果你熟悉本项目，也欢迎发起 pull request。
+
+如果你想贡献文档，请直接编辑 `docs/`。
+
+## 赞助本项目
+
+你可以通过 [GitHub Sponsor](https://github.com/crazywhalecc) 赞助我或我的项目。你捐赠的一部分将用于维护 **static-php.dev** 服务器。
+
+**特别感谢以下赞助商：**
+
+<a href="https://beyondco.de/"><img src="/docs/public/images/beyondcode-seeklogo.png" width="300" alt="Beyond Code Logo" /></a>
+
+<a href="https://nativephp.com/"><img src="/docs/public/images/nativephp-logo.svg" width="300" alt="NativePHP Logo" /></a>
+
+## 开源许可证
+
+本项目本身采用 MIT 许可证。
+一些新添加的扩展和依赖可能来自其他项目。
+这些源码文件头部也可能包含额外的 LICENSE 和 AUTHOR 信息。
+
+请在编译后使用 `bin/spc dump-license` 命令导出项目中使用的开源许可证，
+并遵守对应项目的 LICENSE。

README.md

@@ -5,9 +5,15 @@
 [![Releases](https://img.shields.io/packagist/v/crazywhalecc/static-php-cli?include_prereleases&label=Release&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/releases)
 [![CI](https://img.shields.io/github/actions/workflow/status/crazywhalecc/static-php-cli/tests.yml?branch=main&label=Build%20Test&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/actions/workflows/tests.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://github.com/crazywhalecc/static-php-cli/blob/main/LICENSE)
+[![Discord](https://img.shields.io/discord/nrSRbpMJ?label=Discord&logo=discord&style=flat-square)](https://discord.gg/xf6Rd4pEAk)
 
 **StaticPHP** is a powerful tool designed for building portable executables including PHP, extensions, and more.
 
+> [!IMPORTANT]
+> We are preparing to release **v3**, which will include a project rename from **static-php-cli** to **StaticPHP**.
+> And this branch is for v3. For v2, please check the [v2 branch](https://github.com/crazywhalecc/static-php-cli/tree/main).
+> Please update your references and stay tuned for the official release.
+
 ## Features
 
 - :elephant: Support multiple PHP versions - PHP 8.1, 8.2, 8.3, 8.4, 8.5
@@ -35,15 +41,15 @@
 
 ```bash
 # For Linux x86_64
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-x86_64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
 # For Linux aarch64
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-aarch64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64
 # macOS x86_64 (Intel)
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-x86_64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64
 # macOS aarch64 (Apple)
-curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-aarch64
+curl -fsSL -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64
 # 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/latest/spc-windows-x64.exe
+curl.exe -fsSL -o spc.exe https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x64.exe
 ```
 
 For macOS and Linux, add execute permission first:
@@ -98,7 +104,7 @@ see <https://static-php.dev>.
 
 ## Direct Download
 
-If you do not want to build yet or just want to test first, you can download example pre-compiled artifacts from [Actions](https://github.com/static-php/static-php-cli-hosted/actions/workflows/build-php-bulk.yml) or from a self-hosted server.
+If you do not want to build yet or just want to test first, you can download example pre-compiled artifacts from [Actions](https://github.com/static-php/hosted/actions/workflows/build-php-bulk.yml) or from a self-hosted server.
 
 We offer 2 types of extension sets for each PHP version:
 

bin/setup-runtime.ps1

@@ -1,116 +1,116 @@
-param (
-    [string] ${action}
-)
-
-function AddToPath {
-    param (
-        [string]$pathToAdd
-    )
-
-    $currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
-
-    if ($currentPath -notlike "*$pathToAdd*") {
-        $newPath = $currentPath + ";$pathToAdd"
-        [System.Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
-        Write-Host "Added '$pathToAdd' to Path."
-        Write-Host "To remove path, use: " -NoNewline
-        Write-Host "bin/setup-runtime remove-path" -ForegroundColor Cyan
-    } else {
-        Write-Host "Path already exists."
-    }
-}
-
-function RemoveFromPath {
-    param (
-        [string]$pathToRemove
-    )
-
-    $currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
-
-    if ($currentPath -like "*$pathToRemove*") {
-        $newPath = $currentPath -replace [regex]::Escape(';' + $pathToRemove), ''
-        [System.Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
-        Write-Host "Removed Path '$pathToRemove'"
-    } else {
-        Write-Host "Path '$pathToRemove' not in Path"
-    }
-}
-
-# working dir
-$WorkingDir = (Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Definition))
-
-if ($action -eq 'add-path') {
-    AddToPath ($WorkingDir + '\runtime')
-    exit 0
-} elseif ($action -eq 'remove-path') {
-    RemoveFromPath ($WorkingDir + '\runtime')
-    exit 0
-} elseif (-not($action -eq '')) {
-    Write-Host ("Invalid action: " + $action) -ForegroundColor Red
-    exit 1
-}
-
-# get php 8.1 specific version
-
-# php windows download
-$PHPRuntimeUrl = "https://windows.php.net/downloads/releases/archives/php-8.4.4-nts-Win32-vs17-x64.zip"
-Write-Host "Downloading PHP from: " -NoNewline
-Write-Host $PHPRuntimeUrl -ForegroundColor Cyan
-$ComposerUrl = "https://getcomposer.org/download/latest-stable/composer.phar"
-
-# create dir
-New-Item -Path "downloads" -ItemType Directory -Force | Out-Null
-
-# download php
-if (-not(Test-Path "downloads\php.zip"))
-{
-    Write-Host "Downloading PHP ..."
-    Invoke-WebRequest $PHPRuntimeUrl -OutFile "downloads\php.zip"
-}
-
-# extract php
-New-Item -Path "runtime" -ItemType Directory -Force | Out-Null
-Write-Host "Extracting php.zip ..."
-Expand-Archive -Path "downloads/php.zip" -DestinationPath "runtime" -Force
-# make php.ini
-Move-Item -Path "runtime\php.ini-production" -Destination "runtime\php.ini" -Force
-$OriginINI = Get-Content -Path "runtime\php.ini" -Raw
-$OriginINI = $OriginINI -replace ';extension=openssl', 'extension=openssl'
-$OriginINI = $OriginINI -replace ';extension=curl', 'extension=curl'
-$OriginINI = $OriginINI -replace ';extension=mbstring', 'extension=mbstring'
-$OriginINI = $OriginINI -replace ';extension=sodium', 'extension=sodium'
-$OriginINI = $OriginINI -replace ';extension_dir = "./"', ('extension_dir = "' + (Split-Path -Parent $MyInvocation.MyCommand.Definition) + '\..\runtime\ext"')
-$OriginINI | Set-Content -Path "runtime\php.ini"
-
-# download composer
-if (-not(Test-Path "runtime\composer.phar"))
-{
-    Write-Host "Downloading composer ..."
-    Invoke-WebRequest $ComposerUrl -OutFile "downloads\composer.phar"
-    Move-Item -Path "downloads\composer.phar" -Destination "runtime\composer.phar" -Force
-}
-
-# create runtime\composer.ps1
-$ComposerContent = '
-$WorkingDir = (Split-Path -Parent $MyInvocation.MyCommand.Definition)
-& ($WorkingDir + "\php.exe") (Join-Path $WorkingDir "\composer.phar") @args
-'
-$ComposerContent | Set-Content -Path 'runtime\composer.ps1' -Encoding UTF8
-
-Write-Host "Successfully downloaded PHP and Composer !" -ForegroundColor Green
-Write-Host "Use static-php-cli: " -NoNewline
-Write-Host "bin/spc" -ForegroundColor Cyan
-Write-Host "Use php:            " -NoNewline
-Write-Host "runtime/php" -ForegroundColor Cyan
-Write-Host "Use composer:       " -NoNewline
-Write-Host "runtime/composer" -ForegroundColor Cyan
-Write-Host ""
-Write-Host "Don't forget installing composer dependencies '" -NoNewline
-Write-Host "runtime/composer install" -ForegroundColor Cyan -NoNewline
-Write-Host "' before using static-php-cli !"
-Write-Host ""
-Write-Host "If you want to use this PHP for quality tools (like phpstan, php-cs-fixer) or other project,"
-Write-Host "or use PHP, Composer as system executable,"
-Write-Host "use '" -NoNewline
-Write-Host "bin/setup-runtime add-path" -ForegroundColor Cyan -NoNewline
-Write-Host "' to add runtime dir in Path."
+param (
+    [string] ${action}
+)
+
+function AddToPath {
+    param (
+        [string]$pathToAdd
+    )
+
+    $currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+
+    if ($currentPath -notlike "*$pathToAdd*") {
+        $newPath = $currentPath + ";$pathToAdd"
+        [System.Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
+        Write-Host "Added '$pathToAdd' to Path."
+        Write-Host "To remove path, use: " -NoNewline
+        Write-Host "bin/setup-runtime remove-path" -ForegroundColor Cyan
+    } else {
+        Write-Host "Path already exists."
+    }
+}
+
+function RemoveFromPath {
+    param (
+        [string]$pathToRemove
+    )
+
+    $currentPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+
+    if ($currentPath -like "*$pathToRemove*") {
+        $newPath = $currentPath -replace [regex]::Escape(';' + $pathToRemove), ''
+        [System.Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
+        Write-Host "Removed Path '$pathToRemove'"
+    } else {
+        Write-Host "Path '$pathToRemove' not in Path"
+    }
+}
+
+# working dir
+$WorkingDir = (Split-Path -Parent (Split-Path -Parent $MyInvocation.MyCommand.Definition))
+
+if ($action -eq 'add-path') {
+    AddToPath ($WorkingDir + '\runtime')
+    exit 0
+} elseif ($action -eq 'remove-path') {
+    RemoveFromPath ($WorkingDir + '\runtime')
+    exit 0
+} elseif (-not($action -eq '')) {
+    Write-Host ("Invalid action: " + $action) -ForegroundColor Red
+    exit 1
+}
+
+# get php 8.1 specific version
+
+# php windows download
+$PHPRuntimeUrl = "https://windows.php.net/downloads/releases/archives/php-8.4.4-nts-Win32-vs17-x64.zip"
+Write-Host "Downloading PHP from: " -NoNewline
+Write-Host $PHPRuntimeUrl -ForegroundColor Cyan
+$ComposerUrl = "https://getcomposer.org/download/latest-stable/composer.phar"
+
+# create dir
+New-Item -Path "downloads" -ItemType Directory -Force | Out-Null
+
+# download php
+if (-not(Test-Path "downloads\php.zip"))
+{
+    Write-Host "Downloading PHP ..."
+    Invoke-WebRequest $PHPRuntimeUrl -OutFile "downloads\php.zip"
+}
+
+# extract php
+New-Item -Path "runtime" -ItemType Directory -Force | Out-Null
+Write-Host "Extracting php.zip ..."
+Expand-Archive -Path "downloads/php.zip" -DestinationPath "runtime" -Force
+# make php.ini
+Move-Item -Path "runtime\php.ini-production" -Destination "runtime\php.ini" -Force
+$OriginINI = Get-Content -Path "runtime\php.ini" -Raw
+$OriginINI = $OriginINI -replace ';extension=openssl', 'extension=openssl'
+$OriginINI = $OriginINI -replace ';extension=curl', 'extension=curl'
+$OriginINI = $OriginINI -replace ';extension=mbstring', 'extension=mbstring'
+$OriginINI = $OriginINI -replace ';extension=sodium', 'extension=sodium'
+$OriginINI = $OriginINI -replace ';extension_dir = "./"', ('extension_dir = "' + (Split-Path -Parent $MyInvocation.MyCommand.Definition) + '\..\runtime\ext"')
+$OriginINI | Set-Content -Path "runtime\php.ini"
+
+# download composer
+if (-not(Test-Path "runtime\composer.phar"))
+{
+    Write-Host "Downloading composer ..."
+    Invoke-WebRequest $ComposerUrl -OutFile "downloads\composer.phar"
+    Move-Item -Path "downloads\composer.phar" -Destination "runtime\composer.phar" -Force
+}
+
+# create runtime\composer.ps1
+$ComposerContent = '
+$WorkingDir = (Split-Path -Parent $MyInvocation.MyCommand.Definition)
+& ($WorkingDir + "\php.exe") (Join-Path $WorkingDir "\composer.phar") @args
+'
+$ComposerContent | Set-Content -Path 'runtime\composer.ps1' -Encoding UTF8
+
+Write-Host "Successfully downloaded PHP and Composer !" -ForegroundColor Green
+Write-Host "Use static-php-cli: " -NoNewline
+Write-Host "bin/spc" -ForegroundColor Cyan
+Write-Host "Use php:            " -NoNewline
+Write-Host "runtime/php" -ForegroundColor Cyan
+Write-Host "Use composer:       " -NoNewline
+Write-Host "runtime/composer" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "Don't forget installing composer dependencies '" -NoNewline
+Write-Host "runtime/composer install" -ForegroundColor Cyan -NoNewline
+Write-Host "' before using static-php-cli !"
+Write-Host ""
+Write-Host "If you want to use this PHP for quality tools (like phpstan, php-cs-fixer) or other project,"
+Write-Host "or use PHP, Composer as system executable,"
+Write-Host "use '" -NoNewline
+Write-Host "bin/setup-runtime add-path" -ForegroundColor Cyan -NoNewline
+Write-Host "' to add runtime dir in Path."

bin/spc-debug.ps1

@@ -1,12 +1,12 @@
-$PHP_Exec = ".\runtime\php.exe"
-
-if (-not(Test-Path $PHP_Exec)) {
-    $PHP_Exec = Get-Command php.exe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Definition
-    if (-not $PHP_Exec) {
-        Write-Host "Error: PHP not found, you need to install PHP on your system or use 'bin/setup-runtime'." -ForegroundColor Red
-        exit 1
-    }
-}
-
-& "$PHP_Exec" -d xdebug.mode=debug -d xdebug.client_host=127.0.0.1 -d xdebug.client_port=9003 -d xdebug.start_with_request=yes ("bin/spc") @args
-exit $LASTEXITCODE
+$PHP_Exec = ".\runtime\php.exe"
+
+if (-not(Test-Path $PHP_Exec)) {
+    $PHP_Exec = Get-Command php.exe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Definition
+    if (-not $PHP_Exec) {
+        Write-Host "Error: PHP not found, you need to install PHP on your system or use 'bin/setup-runtime'." -ForegroundColor Red
+        exit 1
+    }
+}
+
+& "$PHP_Exec" -d xdebug.mode=debug -d xdebug.client_host=127.0.0.1 -d xdebug.client_port=9003 -d xdebug.start_with_request=yes ("bin/spc") @args
+exit $LASTEXITCODE

bin/spc.ps1

@@ -1,12 +1,12 @@
-$PHP_Exec = ".\runtime\php.exe"
-
-if (-not(Test-Path $PHP_Exec)) {
-    $PHP_Exec = Get-Command php.exe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Definition
-    if (-not $PHP_Exec) {
-        Write-Host "Error: PHP not found, you need to install PHP on your system or use 'bin/setup-runtime'." -ForegroundColor Red
-        exit 1
-    }
-}
-
-& "$PHP_Exec" ("bin/spc") @args
-exit $LASTEXITCODE
+$PHP_Exec = ".\runtime\php.exe"
+
+if (-not(Test-Path $PHP_Exec)) {
+    $PHP_Exec = Get-Command php.exe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Definition
+    if (-not $PHP_Exec) {
+        Write-Host "Error: PHP not found, you need to install PHP on your system or use 'bin/setup-runtime'." -ForegroundColor Red
+        exit 1
+    }
+}
+
+& "$PHP_Exec" ("bin/spc") @args
+exit $LASTEXITCODE

box.json

@@ -10,7 +10,6 @@
         "config",
         "src",
         "vendor/psr",
-        "vendor/laravel/prompts",
         "vendor/symfony",
         "vendor/php-di",
         "vendor/zhamao"

captainhook.json

@@ -20,7 +20,7 @@
                 ]
             },
             {
-                "action": "bin/spc dev:lint-config --check",
+                "action": "php bin/spc dev:lint-config --check",
                 "conditions": [
                     {
                         "exec": "\\CaptainHook\\App\\Hook\\Condition\\FileStaged\\InDirectory",

composer.json

@@ -12,10 +12,8 @@
         "php": ">=8.4",
         "ext-mbstring": "*",
         "ext-zlib": "*",
-        "laravel/prompts": "~0.1",
         "php-di/php-di": "^7.1",
         "symfony/console": "^5.4 || ^6 || ^7",
-        "symfony/process": "^7.2",
         "symfony/yaml": "^7.2",
         "zhamao/logger": "^1.1.4"
     },

config/artifact/ncurses.yml

@@ -1,9 +1,12 @@
 ncurses:
-  binary: hosted
   metadata:
     license-files:
       - COPYING
   source:
     type: filelist
-    url: 'https://ftp.gnu.org/pub/gnu/ncurses/'
+    url: 'https://ftp.gnu.org/gnu/ncurses/'
+    regex: '/href="(?<file>ncurses-(?<version>[^"]+)\.tar\.gz)"/'
+  source-mirror:
+    type: filelist
+    url: 'https://ftpmirror.gnu.org/gnu/ncurses/'
     regex: '/href="(?<file>ncurses-(?<version>[^"]+)\.tar\.gz)"/'

config/env.ini

@@ -53,8 +53,8 @@ PHP_BUILD_PROVIDER="StaticPHP ${SPC_VERSION}"
 SPC_ENABLE_LOG_FILE="yes"
 ; The LOG DIR for spc logs
 SPC_LOGS_DIR="${WORKING_DIR}/log"
-; Preserve old logs when running new builds
-SPC_PRESERVE_LOGS="no"
+; Preserve old logs when running new builds (code checks SPC_PRESERVE_LOG, not SPC_PRESERVE_LOGS)
+SPC_PRESERVE_LOG="no"
 
 ; EXTENSION_DIR where the built php will look for extension when a .ini instructs to load them
 ; only useful for builds targeting not pure-static linking
@@ -68,8 +68,8 @@ SPC_PRESERVE_LOGS="no"
 [windows]
 ; build target: win7-static
 SPC_TARGET=native-windows
-; php-sdk-binary-tools path
-PHP_SDK_PATH="${WORKING_DIR}\php-sdk-binary-tools"
+; MSYS2 root directory (msys64 subfolder), used by the Windows toolchain
+SPC_MSYS2_PATH="${PKG_ROOT_PATH}\msys2-build-essentials\msys64"
 ; upx executable path
 UPX_EXEC="${PKG_ROOT_PATH}\bin\upx.exe"
 ; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
@@ -94,7 +94,7 @@ SPC_MICRO_PATCHES=static_extensions_win32,cli_checks,disable_huge_page,vcruntime
 ; `native-native`               - links against system libc dynamically
 ; `native-native-musl`          - links against musl libc statically
 ; `native-native-musl -dynamic` - links against musl libc dynamically
-SPC_TARGET=native-native-musl
+SPC_TARGET=${GNU_ARCH}-linux-musl
 
 ; compiler environments (default value is defined by selected toolchain)
 CC=${SPC_DEFAULT_CC}
@@ -102,9 +102,9 @@ CXX=${SPC_DEFAULT_CXX}
 AR=${SPC_DEFAULT_AR}
 LD=${SPC_DEFAULT_LD}
 ; default compiler flags, used in CMake toolchain file, openssl and pkg-config build
-SPC_DEFAULT_C_FLAGS="-fPIC -Os"
-SPC_DEFAULT_CXX_FLAGS="-fPIC -Os"
-SPC_DEFAULT_LD_FLAGS=""
+SPC_DEFAULT_CFLAGS="-fPIC -O3 -pipe -fno-plt -fno-semantic-interposition -fstack-clash-protection -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -ffunction-sections -fdata-sections"
+SPC_DEFAULT_CXXFLAGS="${SPC_DEFAULT_CFLAGS}"
+SPC_DEFAULT_LDFLAGS="-Wl,-z,relro -Wl,--as-needed -Wl,-z,now -Wl,-z,noexecstack -Wl,--gc-sections"
 ; upx executable path
 UPX_EXEC=${PKG_ROOT_PATH}/bin/upx
 ; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
@@ -114,15 +114,15 @@ SPC_MICRO_PATCHES=cli_checks,disable_huge_page
 ; buildconf command
 SPC_CMD_PREFIX_PHP_BUILDCONF="./buildconf --force"
 ; configure command
-SPC_CMD_PREFIX_PHP_CONFIGURE="./configure --prefix= --with-valgrind=no --disable-shared --enable-static --disable-all --disable-phpdbg --with-pic"
+SPC_CMD_PREFIX_PHP_CONFIGURE="./configure --prefix= --with-valgrind=no --disable-shared --enable-static --disable-all --disable-phpdbg --enable-rtld-now --enable-re2c-cgoto --disable-rpath --with-pic"
 
 ; *** default build vars for building php ***
 ; embed type for php, static (libphp.a) or shared (libphp.so)
 SPC_CMD_VAR_PHP_EMBED_TYPE="static"
 ; EXTRA_CFLAGS for `configure` and `make` php
-SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fno-ident -fPIE ${SPC_DEFAULT_C_FLAGS}"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fno-ident -fPIE -fvisibility=hidden -fvisibility-inlines-hidden ${SPC_DEFAULT_CFLAGS}"
 ; EXTRA_CXXFLAGS for `configure` and `make` php
-SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fPIE ${SPC_DEFAULT_CXX_FLAGS}"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fPIE -fvisibility=hidden -fvisibility-inlines-hidden ${SPC_DEFAULT_CXXFLAGS}"
 ; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.so
 SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
 
@@ -142,9 +142,9 @@ CXX=${SPC_DEFAULT_CXX}
 AR=${SPC_DEFAULT_AR}
 LD=${SPC_DEFAULT_LD}
 ; default compiler flags, used in CMake toolchain file, openssl and pkg-config build
-SPC_DEFAULT_C_FLAGS="--target=${MAC_ARCH}-apple-darwin -Os"
-SPC_DEFAULT_CXX_FLAGS="--target=${MAC_ARCH}-apple-darwin -Os"
-SPC_DEFAULT_LD_FLAGS=""
+SPC_DEFAULT_CFLAGS="--target=${MAC_ARCH}-apple-darwin -O3 -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -ffunction-sections -fdata-sections"
+SPC_DEFAULT_CXXFLAGS="${SPC_DEFAULT_CFLAGS}"
+SPC_DEFAULT_LDFLAGS="-Wl,-dead_strip"
 ; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
 SPC_MICRO_PATCHES=cli_checks,macos_iconv
 
@@ -152,15 +152,15 @@ SPC_MICRO_PATCHES=cli_checks,macos_iconv
 ; buildconf command
 SPC_CMD_PREFIX_PHP_BUILDCONF="./buildconf --force"
 ; configure command
-SPC_CMD_PREFIX_PHP_CONFIGURE="./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-phpdbg"
+SPC_CMD_PREFIX_PHP_CONFIGURE="./configure --prefix= --with-valgrind=no --disable-shared --enable-static --disable-all --disable-phpdbg --enable-rtld-now --enable-re2c-cgoto --disable-rpath --with-pic"
 
 ; *** default build vars for building php ***
 ; embed type for php, static (libphp.a) or shared (libphp.dylib)
 SPC_CMD_VAR_PHP_EMBED_TYPE="static"
 ; EXTRA_CFLAGS for `configure` and `make` php
-SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fpic -fpie -Werror=unknown-warning-option ${SPC_DEFAULT_C_FLAGS}"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fpic -fpie -fvisibility=hidden -fvisibility-inlines-hidden -Werror=unknown-warning-option ${SPC_DEFAULT_CFLAGS}"
 ; EXTRA_CXXFLAGS for `configure` and `make` php
-SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fpie -Werror=unknown-warning-option ${SPC_DEFAULT_CXX_FLAGS}"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fpie -fvisibility=hidden -fvisibility-inlines-hidden -Werror=unknown-warning-option ${SPC_DEFAULT_CXXFLAGS}"
 ; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.dylib
 SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
 ; minimum compatible macOS version (LLVM vars, availability not guaranteed)

config/pkg/ext/builtin-extensions.yml

@@ -186,6 +186,7 @@ ext-password-argon2:
   type: php-extension
   depends:
     - libargon2
+  suggests:
     - ext-openssl
   php-extension:
     os:
@@ -348,6 +349,7 @@ ext-xmlreader:
   type: php-extension
   depends:
     - ext-xml
+    - ext-dom
   php-extension:
     arg-type: enable
     build-with-php: true

config/pkg/ext/ext-clickhouse.yml

@@ -0,0 +1,19 @@
+ext-clickhouse:
+  type: php-extension
+  artifact:
+    source:
+      type: ghtar
+      repo: iliaal/php_clickhouse
+      extract: php-src/ext/clickhouse
+      prefer-stable: true
+    metadata:
+      license-files: [LICENSE]
+      license: PHP-3.01
+  suggests@unix:
+    - openssl
+  lang: cpp
+  php-extension:
+    os:
+      - Linux
+      - Darwin
+    arg-type@unix: custom

config/pkg/ext/ext-ds.yml

@@ -2,8 +2,10 @@ ext-ds:
   type: php-extension
   artifact:
     source:
-      type: pecl
-      name: ds
+      type: git
+      url: 'https://github.com/php-ds/ext-ds.git'
+      rev: master
+      extract: php-src/ext/ds
     metadata:
       license-files: [LICENSE]
       license: MIT

config/pkg/ext/ext-fastchart.yml

@@ -0,0 +1,20 @@
+ext-fastchart:
+  type: php-extension
+  artifact:
+    source:
+      type: ghtar
+      repo: iliaal/fastchart
+      extract: php-src/ext/fastchart
+      prefer-stable: true
+    metadata:
+      license-files: [LICENSE]
+  depends:
+    - freetype
+  suggests:
+    - libpng
+    - libjpeg
+    - libwebp
+  php-extension:
+    os:
+      - Linux
+      - Darwin

config/pkg/ext/ext-fastjson.yml

@@ -0,0 +1,14 @@
+ext-fastjson:
+  type: php-extension
+  artifact:
+    source:
+      type: ghtar
+      repo: iliaal/fastjson
+      extract: php-src/ext/fastjson
+      prefer-stable: true
+    metadata:
+      license-files: [LICENSE]
+  php-extension:
+    os:
+      - Linux
+      - Darwin

config/pkg/ext/ext-gearman.yml

@@ -0,0 +1,16 @@
+ext-gearman:
+  type: php-extension
+  artifact:
+    source:
+      type: pecl
+      name: gearman
+    metadata:
+      license-files: [LICENSE]
+      license: PHP-3.01
+  depends:
+    - libgearman
+  php-extension:
+    os:
+      - Linux
+      - Darwin
+    arg-type: '--with-gearman@shared_path_suffix@'

config/pkg/ext/ext-gmssl.yml

@@ -10,3 +10,5 @@ ext-gmssl:
       license: PHP-3.01
   depends:
     - gmssl
+  php-extension:
+    arg-type: with-path

config/pkg/ext/ext-imagick.yml

@@ -13,4 +13,5 @@ ext-imagick:
     os:
       - Linux
       - Darwin
+      - Windows
     arg-type: custom

config/pkg/ext/ext-rdkafka.yml

@@ -3,7 +3,7 @@ ext-rdkafka:
   artifact:
     source:
       type: ghtar
-      repo: arnaud-lb/php-rdkafka
+      repo: php-rdkafka/php-rdkafka
       extract: php-src/ext/rdkafka
     metadata:
       license-files: [LICENSE]

config/pkg/ext/ext-swoole.yml

@@ -5,7 +5,6 @@ ext-swoole:
       type: ghtar
       repo: swoole/swoole-src
       extract: php-src/ext/swoole
-      match: v6\.+
       prefer-stable: true
     metadata:
       license-files: [LICENSE]

config/pkg/ext/ext-swow.yml

@@ -14,5 +14,6 @@ ext-swow:
     - curl
     - ext-openssl
     - ext-curl
+    - postgresql
   php-extension:
     arg-type: custom

config/pkg/ext/ext-zip.yml

@@ -10,6 +10,11 @@ ext-zip:
       license: PHP-3.01
   depends:
     - libzip
+  depends@windows:
+    - libzip
+    - zlib
+    - xz
+    - bzip2
   php-extension:
     arg-type: custom
     arg-type@windows: enable

config/pkg/lib/brotli.yml

@@ -5,7 +5,6 @@ brotli:
       type: ghtagtar
       repo: google/brotli
       match: 'v1\.\d.*'
-    binary: hosted
     metadata:
       license-files: [LICENSE]
       license: MIT

config/pkg/lib/bzip2.yml

@@ -8,7 +8,6 @@ bzip2:
       type: filelist
       url: 'https://sourceware.org/pub/bzip2/'
       regex: '/href="(?<file>bzip2-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
     metadata:
       license-files: ['@/bzip2.txt']
       license: bzip2-1.0.6

config/pkg/lib/gettext-win.yml

@@ -4,6 +4,6 @@ gettext-win:
     source:
       type: git
       url: 'https://github.com/winlibs/gettext.git'
-      rev: master
+      rev: '0.18'
   static-libs@windows:
     - libintl_a.lib

config/pkg/lib/gettext.yml

@@ -3,7 +3,11 @@ gettext:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/pub/gnu/gettext/'
+      url: 'https://ftp.gnu.org/gnu/gettext/'
+      regex: '/href="(?<file>gettext-(?<version>[^"]+)\.tar\.xz)"/'
+    source-mirror:
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/gettext/'
       regex: '/href="(?<file>gettext-(?<version>[^"]+)\.tar\.xz)"/'
     metadata:
       license-files: [gettext-runtime/intl/COPYING.LIB]

config/pkg/lib/glfw.yml

@@ -1,6 +1,12 @@
 glfw:
   type: library
   artifact: glfw
+  frameworks:
+    - Cocoa
+    - CoreFoundation
+    - CoreVideo
+    - IOKit
+    - QuartzCore
   headers:
     - GLFW/glfw3.h
     - GLFW/glfw3native.h

config/pkg/lib/gmp.yml

@@ -6,8 +6,9 @@ gmp:
       url: 'https://ftp.gnu.org/gnu/gmp/'
       regex: '/href="(?<file>gmp-(?<version>[^"]+)\.tar\.xz)"/'
     source-mirror:
-      type: url
-      url: 'https://dl.static-php.dev/static-php-cli/deps/gmp/gmp-6.3.0.tar.xz'
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/gmp/'
+      regex: '/href="(?<file>gmp-(?<version>[^"]+)\.tar\.xz)"/'
     metadata:
       license-files: ['@/gmp.txt']
       license: Custom

config/pkg/lib/idn2.yml

@@ -5,6 +5,10 @@ idn2:
       type: filelist
       url: 'https://ftp.gnu.org/gnu/libidn/'
       regex: '/href="(?<file>libidn2-(?<version>[^"]+)\.tar\.gz)"/'
+    source-mirror:
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/libidn/'
+      regex: '/href="(?<file>libidn2-(?<version>[^"]+)\.tar\.gz)"/'
     metadata:
       license-files: [COPYING.LESSERv3]
       license: LGPL-3.0-or-later

config/pkg/lib/imagemagick.yml

@@ -16,13 +16,59 @@ imagemagick:
     - libtiff
     - libheif
     - bzip2
+  depends@windows:
+    - zlib
   suggests:
     - zstd
     - xz
     - libzip
     - libxml2
+  headers@windows:
+    - imagemagick/MagickWand/MagickWand.h
   lang: cpp
   pkg-configs:
     - Magick++-7.Q16HDRI
     - MagickCore-7.Q16HDRI
     - MagickWand-7.Q16HDRI
+  static-libs@windows:
+    - CORE_RL_MagickWand_.lib
+    - CORE_RL_MagickCore_.lib
+    - CORE_RL_coders_.lib
+    - CORE_RL_filters_.lib
+    - CORE_RL_aom_.lib
+    - CORE_RL_brotli_.lib
+    - CORE_RL_bzip2_.lib
+    - CORE_RL_cairo_.lib
+    - CORE_RL_croco_.lib
+    - CORE_RL_de265_.lib
+    - CORE_RL_exr_.lib
+    - CORE_RL_ffi_.lib
+    - CORE_RL_freetype_.lib
+    - CORE_RL_fribidi_.lib
+    - CORE_RL_gdk-pixbuf_.lib
+    - CORE_RL_glib_.lib
+    - CORE_RL_harfbuzz_.lib
+    - CORE_RL_heif_.lib
+    - CORE_RL_highway_.lib
+    - CORE_RL_imath_.lib
+    - CORE_RL_jpeg-turbo-12_.lib
+    - CORE_RL_jpeg-turbo-16_.lib
+    - CORE_RL_jpeg-turbo_.lib
+    - CORE_RL_jpeg-xl_.lib
+    - CORE_RL_lcms_.lib
+    - CORE_RL_lqr_.lib
+    - CORE_RL_lzma_.lib
+    - CORE_RL_openh264_.lib
+    - CORE_RL_openjpeg_.lib
+    - CORE_RL_openjph_.lib
+    - CORE_RL_pango_.lib
+    - CORE_RL_pixman_.lib
+    - CORE_RL_png_.lib
+    - CORE_RL_raqm_.lib
+    - CORE_RL_raw_.lib
+    - CORE_RL_rsvg_.lib
+    - CORE_RL_tiff_.lib
+    - CORE_RL_webp_.lib
+    - CORE_RL_xml_.lib
+    - CORE_RL_zip_.lib
+    - CORE_RL_zlib_.lib

config/pkg/lib/libcares.yml

@@ -10,7 +10,6 @@ libcares:
       type: filelist
       url: 'https://c-ares.org/download/'
       regex: '/href="\/download\/(?<file>c-ares-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
     metadata:
       license-files: [LICENSE.md]
   headers@unix:

config/pkg/lib/libedit.yml

@@ -5,7 +5,6 @@ libedit:
       type: filelist
       url: 'https://thrysoee.dk/editline/'
       regex: '/href="(?<file>libedit-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
     metadata:
       license-files: [COPYING]
       license: BSD-3-Clause

config/pkg/lib/libevent.yml

@@ -16,3 +16,4 @@ libevent:
     - libevent_core.a
     - libevent_extra.a
     - libevent_openssl.a
+    - libevent_pthreads.a

config/pkg/lib/libgearman.yml

@@ -0,0 +1,23 @@
+libgearman:
+  type: library
+  artifact:
+    source:
+      type: ghrel
+      repo: gearman/gearmand
+      match: gearmand-.+\.tar\.gz
+      prefer-stable: true
+    metadata:
+      license-files: [COPYING]
+      license: BSD-3-Clause
+  depends:
+    - libevent
+    - libuuid
+  suggests:
+    - libmemcached
+  headers@unix:
+    - libgearman-1.0/gearman.h
+  lang: cpp
+  pkg-configs:
+    - gearmand
+  static-libs@unix:
+    - libgearman.a

config/pkg/lib/libiconv-win.yml

@@ -9,5 +9,4 @@ libiconv-win:
       license-files: [source/COPYING]
       license: GPL-3.0-or-later
   static-libs@windows:
-    - libiconv.lib
     - libiconv_a.lib

config/pkg/lib/libiconv.yml

@@ -5,7 +5,10 @@ libiconv:
       type: filelist
       url: 'https://ftp.gnu.org/gnu/libiconv/'
       regex: '/href="(?<file>libiconv-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
+    source-mirror:
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/libiconv/'
+      regex: '/href="(?<file>libiconv-(?<version>[^"]+)\.tar\.gz)"/'
     metadata:
       license-files: [COPYING.LIB]
       license: LGPL-2.0-or-later

config/pkg/lib/libpng.yml

@@ -6,7 +6,6 @@ libpng:
       repo: pnggroup/libpng
       match: v1\.6\.\d+
       query: '?per_page=150'
-    binary: hosted
     metadata:
       license-files: [LICENSE]
       license: PNG

config/pkg/lib/libsodium.yml

@@ -6,7 +6,6 @@ libsodium:
       repo: jedisct1/libsodium
       match: 'libsodium-(?!1\.0\.21)\d+(\.\d+)*\.tar\.gz'
       prefer-stable: true
-    binary: hosted
     metadata:
       license-files: [LICENSE]
   pkg-configs:

config/pkg/lib/libssh2.yml

@@ -6,12 +6,13 @@ libssh2:
       repo: libssh2/libssh2
       match: libssh2.+\.tar\.gz
       prefer-stable: true
-    binary: hosted
     metadata:
       license-files: [COPYING]
       license: BSD-3-Clause
-  depends:
+  depends@unix:
     - openssl
+  depends@windows:
+    - zlib
   headers:
     - libssh2.h
     - libssh2_publickey.h

config/pkg/lib/libunistring.yml

@@ -5,7 +5,10 @@ libunistring:
       type: filelist
       url: 'https://ftp.gnu.org/gnu/libunistring/'
       regex: '/href="(?<file>libunistring-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
+    source-mirror:
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/libunistring/'
+      regex: '/href="(?<file>libunistring-(?<version>[^"]+)\.tar\.gz)"/'
     metadata:
       license-files: [COPYING.LIB]
       license: LGPL-3.0-or-later

config/pkg/lib/libzip.yml

@@ -11,6 +11,10 @@ libzip:
       license: BSD-3-Clause
   depends:
     - zlib
+  depends@windows:
+    - zlib
+    - bzip2
+    - xz
   suggests:
     - bzip2
     - xz

config/pkg/lib/openssl.yml

@@ -4,13 +4,12 @@ openssl:
     source:
       type: ghrel
       repo: openssl/openssl
-      match: openssl.+\.tar\.gz
+      match: openssl-3.+\.tar\.gz
       prefer-stable: true
     source-mirror:
       type: filelist
       url: 'https://www.openssl.org/source/'
-      regex: '/href="(?<file>openssl-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
+      regex: '/href="(?<file>openssl-(?<version>3\.[^"]+)\.tar\.gz)"/'
     metadata:
       license-files: [LICENSE.txt]
       license: OpenSSL
@@ -18,7 +17,6 @@ openssl:
     - zlib
   depends@windows:
     - zlib
-    - jom
   headers:
     - openssl
   static-libs@unix:
@@ -27,3 +25,7 @@ openssl:
   static-libs@windows:
     - libssl.lib
     - libcrypto.lib
+  tools@windows:
+    - jom
+    - nasm
+    - strawberry-perl

config/pkg/lib/postgresql.yml

@@ -5,8 +5,6 @@ postgresql:
       type: ghtagtar
       repo: postgres/postgres
       match: REL_18_\d+
-    binary:
-      windows-x86_64: { type: url, url: 'https://get.enterprisedb.com/postgresql/postgresql-16.8-1-windows-x64-binaries.zip', extract: { lib/libpq.lib: '{build_root_path}/lib/libpq.lib', lib/libpgport.lib: '{build_root_path}/lib/libpgport.lib', lib/libpgcommon.lib: '{build_root_path}/lib/libpgcommon.lib', include/libpq-fe.h: '{build_root_path}/include/libpq-fe.h', include/postgres_ext.h: '{build_root_path}/include/postgres_ext.h', include/pg_config_ext.h: '{build_root_path}/include/pg_config_ext.h', include/libpq/libpq-fs.h: '{build_root_path}/include/libpq/libpq-fs.h' } }
     metadata:
       license-files: ['@/postgresql.txt']
       license: PostgreSQL
@@ -16,6 +14,9 @@ postgresql:
     - openssl
     - zlib
     - libedit
+  depends@windows:
+    - openssl
+    - zlib
   suggests@unix:
     - icu
     - libxslt
@@ -27,3 +28,9 @@ postgresql:
     - libpq.lib
     - libpgport.lib
     - libpgcommon.lib
+  tools@windows:
+    - python-win
+    - meson
+    - ninja
+    - winflexbison
+    - strawberry-perl

config/pkg/lib/readline.yml

@@ -3,7 +3,11 @@ readline:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/pub/gnu/readline/'
+      url: 'https://ftp.gnu.org/gnu/readline/'
+      regex: '/href="(?<file>readline-(?<version>[^"]+)\.tar\.gz)"/'
+    source-mirror:
+      type: filelist
+      url: 'https://ftpmirror.gnu.org/gnu/readline/'
       regex: '/href="(?<file>readline-(?<version>[^"]+)\.tar\.gz)"/'
     metadata:
       license-files: [COPYING]

config/pkg/lib/xz.yml

@@ -6,7 +6,6 @@ xz:
       repo: tukaani-project/xz
       match: xz.+\.tar\.xz
       prefer-stable: true
-    binary: hosted
     metadata:
       license-files: [COPYING]
       license: 0BSD

config/pkg/lib/zlib.yml

@@ -5,7 +5,6 @@ zlib:
       type: ghrel
       repo: madler/zlib
       match: zlib.+\.tar\.gz
-    binary: hosted
     metadata:
       license-files: ['@/zlib.txt']
       license: Zlib-Custom

config/pkg/lib/zstd.yml

@@ -19,3 +19,4 @@ zstd:
     - libzstd.a
   static-libs@windows:
     - zstd.lib
+    - libzstd.lib

config/pkg/target/curl.yml

@@ -16,6 +16,8 @@ curl:
     - zlib
     - libssh2
     - nghttp2
+    - brotli
+    - zstd
   suggests@unix:
     - libssh2
     - brotli
@@ -27,9 +29,6 @@ curl:
     - ldap
     - idn2
     - krb5
-  suggests@windows:
-    - brotli
-    - zstd
   frameworks:
     - CoreFoundation
     - CoreServices

config/pkg/target/frankenphp.yml

@@ -10,10 +10,8 @@ frankenphp:
       license: MIT
   depends:
     - php-embed
-    - go-xcaddy
   depends@windows:
     - php-embed
-    - go-win
     - pthreads4w
   suggests@unix:
     - brotli
@@ -24,3 +22,7 @@ frankenphp:
     - frankenphp
   static-bins@windows:
     - frankenphp.exe
+  tools:
+    - go-xcaddy
+  tools@windows:
+    - go-win

config/pkg/target/msys2-build-essentials.yml

@@ -0,0 +1,8 @@
+msys2-build-essentials:
+  type: target
+  artifact:
+    binary: custom
+  env:
+    SPC_MSYS2_PATH: '{pkg_root_path}/msys2-build-essentials/msys64'
+  path@windows:
+    - '{pkg_root_path}/msys2-build-essentials/msys64/usr/bin'

config/pkg/target/nasm.yml

@@ -1,5 +0,0 @@
-nasm:
-  type: target
-  artifact:
-    binary:
-      windows-x86_64: { type: url, url: 'https://dl.static-php.dev/static-php-cli/deps/nasm/nasm-2.16.01-win64.zip', extract: { nasm.exe: '{php_sdk_path}/bin/nasm.exe', ndisasm.exe: '{php_sdk_path}/bin/ndisasm.exe' } }

config/pkg/target/php-sdk-binary-tools.yml

@@ -1,5 +0,0 @@
-php-sdk-binary-tools:
-  type: target
-  artifact:
-    binary:
-      windows-x86_64: { type: git, rev: master, url: 'https://github.com/php/php-sdk-binary-tools.git', extract: '{php_sdk_path}' }

config/pkg/target/pkg-config.yml

@@ -1,9 +0,0 @@
-pkg-config:
-  type: target
-  artifact:
-    source: 'https://dl.static-php.dev/static-php-cli/deps/pkg-config/pkg-config-0.29.2.tar.gz'
-    binary:
-      linux-x86_64: { type: ghrel, repo: static-php/static-php-cli-hosted, match: pkg-config-x86_64-linux-musl-1.2.5.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
-      linux-aarch64: { type: ghrel, repo: static-php/static-php-cli-hosted, match: pkg-config-aarch64-linux-musl-1.2.5.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
-      macos-x86_64: { type: ghrel, repo: static-php/static-php-cli-hosted, match: pkg-config-x86_64-darwin.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
-      macos-aarch64: { type: ghrel, repo: static-php/static-php-cli-hosted, match: pkg-config-aarch64-darwin.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }

config/pkg/target/zig.yml

@@ -1,4 +0,0 @@
-zig:
-  type: target
-  artifact:
-    binary: custom

config/pkg/tool/7za-win.yml

@@ -0,0 +1,9 @@
+7za-win:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64: { type: url, url: 'https://dl.static-php.dev/v3/tools/7zip/7za.exe', extract: '{pkg_root_path}/bin/7za.exe' }
+  tool:
+    provides:
+      - 7za.exe
+    binary-subdir: bin

config/pkg/tool/go-win.yml

@@ -1,10 +1,15 @@
 go-win:
-  type: target
+  type: tool
   artifact:
     binary: custom
   env:
     GOROOT: '{pkg_root_path}/go-win'
     GOBIN: '{pkg_root_path}/go-win/bin'
-    GOPATH: '{pkg_root_path}/go-win/go'
+    GOPATH: '{pkg_root_path}/go-win/gopath'
   path@windows:
     - '{pkg_root_path}/go-win/bin'
+  tool:
+    provides:
+      - go.exe
+      - gofmt.exe
+    binary-subdir: go-win/bin

config/pkg/tool/go-xcaddy.yml

@@ -1,5 +1,5 @@
 go-xcaddy:
-  type: target
+  type: tool
   artifact:
     binary: custom
   env:
@@ -8,5 +8,8 @@ go-xcaddy:
     GOPATH: '{pkg_root_path}/go-xcaddy/go'
   path@unix:
     - '{pkg_root_path}/go-xcaddy/bin'
-  static-bins:
-    - xcaddy
+  tool:
+    provides:
+      - go
+      - gofmt
+    binary-subdir: go-xcaddy/bin

config/pkg/tool/jom.yml

@@ -1,7 +1,11 @@
 jom:
-  type: target
+  type: tool
   artifact:
     binary:
       windows-x86_64: { type: url, url: 'https://download.qt.io/official_releases/jom/jom.zip', extract: '{pkg_root_path}/jom' }
   path@windows:
     - '{pkg_root_path}\jom'
+  tool:
+    provides:
+      - jom.exe
+    binary-subdir: jom

config/pkg/tool/meson.yml

@@ -0,0 +1,11 @@
+meson:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64: { type: url, url: 'https://github.com/mesonbuild/meson/releases/download/1.11.1/meson-1.11.1-py3-none-any.whl', extract: '{pkg_root_path}/meson/meson-1.11.1-py3-none-any.whl' }
+  path@windows:
+    - '{pkg_root_path}\meson'
+  tool:
+    provides:
+      - meson.bat
+    binary-subdir: meson

config/pkg/tool/nasm.yml

@@ -0,0 +1,10 @@
+nasm:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64: { type: url, url: 'https://dl.static-php.dev/static-php-cli/deps/nasm/nasm-2.16.01-win64.zip', extract: { nasm.exe: '{pkg_root_path}/bin/nasm.exe', ndisasm.exe: '{pkg_root_path}/bin/ndisasm.exe' } }
+  tool:
+    provides:
+      - nasm.exe
+      - ndisasm.exe
+    binary-subdir: bin

config/pkg/tool/ninja.yml

@@ -0,0 +1,9 @@
+ninja:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64: { type: url, url: 'https://github.com/ninja-build/ninja/releases/download/v1.13.2/ninja-win.zip', extract: { ninja.exe: '{pkg_root_path}/bin/ninja.exe' } }
+  tool:
+    provides:
+      - ninja.exe
+    binary-subdir: bin

config/pkg/tool/pkg-config.yml

@@ -0,0 +1,13 @@
+pkg-config:
+  type: tool
+  artifact:
+    source: 'https://dl.static-php.dev/static-php-cli/deps/pkg-config/pkg-config-0.29.2.tar.gz'
+    binary:
+      linux-x86_64: { type: ghrel, repo: static-php/hosted, match: pkg-config-x86_64-linux-musl-1.2.5.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
+      linux-aarch64: { type: ghrel, repo: static-php/hosted, match: pkg-config-aarch64-linux-musl-1.2.5.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
+      macos-x86_64: { type: ghrel, repo: static-php/hosted, match: pkg-config-x86_64-darwin.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
+      macos-aarch64: { type: ghrel, repo: static-php/hosted, match: pkg-config-aarch64-darwin.txz, extract: { bin/pkg-config: '{pkg_root_path}/bin/pkg-config' } }
+  tool:
+    provides:
+      - pkg-config
+    binary-subdir: bin

config/pkg/tool/protoc.yml

@@ -1,8 +1,12 @@
 protoc:
-  type: target
+  type: tool
   artifact:
     binary:
       linux-x86_64: { type: ghrel, repo: protocolbuffers/protobuf, match: 'protoc-([0-9.]+)-linux-x86_64\.zip', extract: '{pkg_root_path}/protoc' }
       linux-aarch64: { type: ghrel, repo: protocolbuffers/protobuf, match: 'protoc-([0-9.]+)-linux-aarch_64\.zip', extract: '{pkg_root_path}/protoc' }
   path:
     - '{pkg_root_path}/protoc/bin'
+  tool:
+    provides:
+      - protoc
+    binary-subdir: protoc/bin

config/pkg/tool/python-win.yml

@@ -0,0 +1,8 @@
+python-win:
+  type: tool
+  artifact:
+    binary: custom
+  tool:
+    provides:
+      - python.exe
+    binary-subdir: python-win/tools

config/pkg/tool/strawberry-perl.yml

@@ -1,5 +1,9 @@
 strawberry-perl:
-  type: target
+  type: tool
   artifact:
     binary:
       windows-x86_64: { type: url, url: 'https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/download/SP_5380_5361/strawberry-perl-5.38.0.1-64bit-portable.zip', extract: '{pkg_root_path}/strawberry-perl' }
+  tool:
+    provides:
+      - perl.exe
+    binary-subdir: strawberry-perl/perl/bin

config/pkg/tool/upx.yml

@@ -1,7 +1,13 @@
 upx:
-  type: target
+  type: tool
   artifact:
     binary:
       linux-x86_64: { type: ghrel, repo: upx/upx, match: upx.+-amd64_linux\.tar\.xz, extract: { upx: '{pkg_root_path}/bin/upx' } }
       linux-aarch64: { type: ghrel, repo: upx/upx, match: upx.+-arm64_linux\.tar\.xz, extract: { upx: '{pkg_root_path}/bin/upx' } }
       windows-x86_64: { type: ghrel, repo: upx/upx, match: upx.+-win64\.zip, extract: { upx.exe: '{pkg_root_path}/bin/upx.exe' } }
+  tool:
+    provides:
+      - upx
+    provides@windows:
+      - upx.exe
+    binary-subdir: bin

config/pkg/tool/vswhere.yml

@@ -1,5 +1,9 @@
 vswhere:
-  type: target
+  type: tool
   artifact:
     binary:
       windows-x86_64: { type: url, url: 'https://github.com/microsoft/vswhere/releases/download/3.1.7/vswhere.exe', extract: '{pkg_root_path}/bin/vswhere.exe' }
+  tool:
+    provides:
+      - vswhere.exe
+    binary-subdir: bin

config/pkg/tool/winflexbison.yml

@@ -0,0 +1,12 @@
+winflexbison:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64: { type: url, url: 'https://github.com/lexxmark/winflexbison/releases/download/v2.5.25/win_flex_bison-2.5.25.zip', extract: '{pkg_root_path}/winflexbison' }
+  path@windows:
+    - '{pkg_root_path}\winflexbison'
+  tool:
+    provides:
+      - win_flex.exe
+      - win_bison.exe
+    binary-subdir: winflexbison

config/pkg/tool/zig.yml

@@ -0,0 +1,14 @@
+zig:
+  type: tool
+  artifact:
+    binary: custom
+  tool:
+    provides:
+      - zig
+      - zig-cc
+      - zig-c++
+      - zig-ar
+      - zig-ld.lld
+      - zig-ranlib
+      - zig-objcopy
+    binary-subdir: zig

docs/.vitepress/components/CliGenerator.vue

@@ -45,7 +45,7 @@
         <label :for="'build_' + item">{{ item }}</label>
       </div>
     </div>
-    <div v-if="selectedSystem === 'windows' && (checkedTargets.includes('fpm') || checkedTargets.includes('embed') || checkedTargets.includes('frankenphp'))" class="warning custom-block">
+    <div v-if="selectedSystem === 'windows' && checkedTargets.includes('fpm')" class="warning custom-block">
       <p class="custom-block-title">WARNING</p>
       <p>{{ I18N[lang].windowsSAPIUnavailable }}</p>
     </div>
@@ -157,7 +157,7 @@
         <div class="warning custom-block">
           <p class="custom-block-title">WARNING</p>
           <p>{{ I18N[lang].windowsDownSPCWarning }}</p>
-          <a href="https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe" target="_blank">https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe</a>
+          <a href="https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe" target="_blank">https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe</a>
         </div>
       </div>
     </div>
@@ -278,7 +278,7 @@ const spcCommand = computed(() => {
 const spcDownloadCommand = computed(() => {
   const os = selectedSystem.value === 'macos' ? 'macos' : 'linux';
   const arch = selectedArch.value;
-  return `curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-${os}-${arch} -o spc && chmod +x spc`;
+  return `curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-${os}-${arch} -o spc && chmod +x spc`;
 });
 
 const doctorCommandString = computed(() => `${spcCommand.value} doctor --auto-fix`);
@@ -425,7 +425,7 @@ const I18N: Record<string, Record<string, string>> = {
     downloadPhpVersion: '下载 PHP 版本',
     downloadSPCBinaryCommand: '下载 spc 二进制命令',
     selectedSystem: '选择操作系统',
-    windowsSAPIUnavailable: 'Windows 目前不支持 fpm、embed、frankenphp 构建！',
+    windowsSAPIUnavailable: 'Windows 目前不支持 fpm 构建！',
     useUPX: '是否开启 UPX 压缩（减小二进制体积）',
     windowsDownSPCWarning: 'Windows 下请手动下载 spc.exe 二进制文件！',
     usePreBuilt: '如果可能，使用预编译的依赖库（减少编译时间）',
@@ -459,7 +459,7 @@ const I18N: Record<string, Record<string, string>> = {
     downloadPhpVersion: 'PHP version',
     downloadSPCBinaryCommand: 'Download spc binary',
     selectedSystem: 'Select OS',
-    windowsSAPIUnavailable: 'Windows does not support fpm, embed and frankenphp build!',
+    windowsSAPIUnavailable: 'Windows does not support fpm build!',
     useUPX: 'Enable UPX compression (reduce binary size)',
     windowsDownSPCWarning: 'Please download the spc.exe binary manually on Windows!',
     usePreBuilt: 'Use pre-built dependencies where available (reduce compile time)',

docs/.vitepress/sidebar.en.ts

@@ -8,6 +8,7 @@ export default {
         { text: 'First Build', link: '/en/guide/first-build' },
         { text: 'PHP SAPI Reference', link: '/en/guide/sapi-reference' },
         { text: 'CLI Reference', link: '/en/guide/cli-reference' },
+        { text: 'Migrating from v2', link: '/en/guide/migrate-from-v2' },
       ],
     },
     {
@@ -29,46 +30,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/': [
     {

docs/.vitepress/sidebar.zh.ts

@@ -8,6 +8,7 @@ export default {
         { text: '第一次构建', link: '/zh/guide/first-build' },
         { text: 'PHP SAPI 构建参考', link: '/zh/guide/sapi-reference' },
         { text: '命令行参考', link: '/zh/guide/cli-reference' },
+        { text: '从 v2 迁移', link: '/zh/guide/migrate-from-v2' },
       ],
     },
     {
@@ -29,46 +30,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/': [
     {

docs/deps-craft-yml.md

@@ -0,0 +1,88 @@
+```yaml
+# PHP version to build (default: 8.5)
+php-version: 8.5
+# [REQUIRED] Static PHP extensions to build (list or comma-separated are both accepted)
+extensions: bcmath,fileinfo,phar,zlib,sodium,posix,pcntl
+# Extra packages to build (list or comma-separated are both accepted)
+packages: [ ]
+# [REQUIRED] Build SAPIs (list or comma-separated are both accepted)
+# Available: cli, micro, fpm, embed, frankenphp, cgi, all
+sapi: cli,micro,fpm
+# Show full console output (default: false)
+debug: false
+# Before build, remove all old build files and sources (default: false)
+clean-build: false
+# Build options (same as `build:php` command options, all options are optional)
+build-options:
+  # Build with all suggested packages (libraries and extensions) as well (default: false)
+  with-suggests: false
+  # Build extra shared extensions (comma-separated string)
+  build-shared: ""
+  # Build without stripping the binary (default: false)
+  no-strip: false
+  # Disable Opcache JIT (default: false)
+  disable-opcache-jit: false
+  # Enable thread-safe (ZTS) support (default: false)
+  enable-zts: false
+  # Disable smoke test, or for specific SAPIs comma-separated (default: false)
+  no-smoke-test: false
+  # PHP configuration options (same as --with-config-file-path)
+  with-config-file-path: ""
+  # PHP configuration options (same as --with-config-file-scan-dir)
+  with-config-file-scan-dir: ""
+  # Hardcoded INI options for cli and micro SAPI (e.g. "memory_limit=4G", list accepted)
+  with-hardcoded-ini: [ ]
+  # Pretend micro SAPI as cli SAPI to avoid some frameworks to limit the usage of micro SAPI
+  with-micro-fake-cli: false
+  # Additional patch point injection files (e.g. "path/to/patch.php", list accepted)
+  with-added-patch: [ ]
+  # Ignore micro extension tests (if you are using micro SAPI, default: false)
+  without-micro-ext-test: false
+  # UPX pack the binary (default: false)
+  with-upx-pack: false
+  # Set the micro.exe program icon (only for Windows, default: "")
+  with-micro-logo: ""
+  # Set micro SAPI as win32 mode, without this, micro SAPI will be compiled as a console application (only for Windows, default: false)
+  enable-micro-win32: false
+  # Path to a folder to be embedded in FrankenPHP (frankenphp SAPI only)
+  with-frankenphp-app: ""
+
+# Build options for shared extensions (list or comma-separated are both accepted)
+shared-extensions: [ ]
+
+# Download options
+download-options:
+  # Number of parallel downloads (default: 1)
+  parallel: 1
+  # Retries count for downloading sources (default: 0)
+  retry: 0
+  # Prefer source downloads when both source and binary are available (default: false)
+  prefer-source: false
+  # Prefer binary downloads when both source and binary are available (default: false)
+  prefer-binary: false
+  # Only download source artifacts, skip binary artifacts (default: false)
+  source-only: false
+  # Only download binary artifacts, skip source artifacts (default: false)
+  binary-only: false
+  # Ignore download cache for specified packages, comma separated (default: false)
+  ignore-cache: false
+  # Do not use alternative mirror download sources (default: false)
+  no-alt: false
+  # Do not clone shallowly repositories when downloading sources (default: false)
+  no-shallow-clone: false
+  # Use custom url for specified sources, format: "{source-name}:{url}" (e.g. "php-src:https://example.com/php-8.4.0.tar.gz")
+  custom-url: [ ]
+  # Use custom git repo for specified sources, format: "{source-name}:{branch}:{url}" (e.g. "php-src:master:https://github.com/php/php-src.git")
+  custom-git: [ ]
+  # Use custom local source path, format: "{source-name}:{path}" (e.g. "php-src:/path/to/php-src")
+  custom-local: [ ]
+
+craft-options:
+  doctor: true
+  download: true
+
+# Extra environment variables
+extra-env:
+  # e.g. Use github token to avoid rate limit
+  GITHUB_TOKEN: your-github-token
+```

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

docs/en/develop/craft-yml.md

@@ -4,4 +4,4 @@ aside: false
 
 # craft.yml Configuration
 
-<!-- TODO: Full reference for craft.yml fields. -->
+<!--@include: ../../deps-craft-yml.md-->

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

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