Merge branch 'v3' into v3c/artifact-static-helpers

Build the CC/CXX/AR/LD/RANLIB map once and hand it to shell()->setEnv()
so the configure/make invocations don't have to repeat the same prefix
on every line. For the sudo make-install path the env still needs to
be on the command line (sudo strips the parent env), so the same map
is rendered into $envFlags and prepended there. Also adds RANLIB,
which the upstream Makefile honours.

.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/workflows/release-build.yml

@@ -120,6 +120,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,171 @@ 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:
+      pull-requests: write
+      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"
+
+          COMMENT_BODY=$(echo "$BOT_JSON" | jq -r '.comment_body')
+          MARKER="<!-- spc-test-bot -->"
+
+          # Find existing bot comment id
+          EXISTING_ID=$(gh api \
+            repos/${{ github.repository }}/issues/${{ github.event.pull_request.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 ${{ github.event.pull_request.number }} \
+              --repo ${{ github.repository }} \
+              --body "$COMMENT_BODY"
+          fi
+
+  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 }} (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.extension }}-php${{ matrix.combo.php-version }}
+          path: log

.github/workflows/vitepress-deploy.yml

@@ -1,8 +1,16 @@
-name: Docs Auto Deploy
+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
+    branches: [ "v3" ]
     paths:
       - 'config/**.yml'
       - 'docs/**'
@@ -20,15 +28,8 @@ jobs:
         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/
+      - run: npm install
 
       - name: "Install PHP for official runners"
         uses: shivammathur/setup-php@v2
@@ -55,19 +56,13 @@ jobs:
       - 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
+        run: npm run 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

README-zh.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** 是一个强大的工具，用于构建可移植的可执行文件，包括 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
@@ -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
 ```
 
 对于 macOS 和 Linux，请先添加可执行权限：

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:

composer.lock

@@ -8,16 +8,16 @@
     "packages": [
         {
             "name": "laravel/prompts",
-            "version": "v0.3.16",
+            "version": "v0.3.17",
             "source": {
                 "type": "git",
                 "url": "https://github.com/laravel/prompts.git",
-                "reference": "11e7d5f93803a2190b00e145142cb00a33d17ad2"
+                "reference": "6a82ac19a28b916ae0885828795dbd4c59d9a818"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/laravel/prompts/zipball/11e7d5f93803a2190b00e145142cb00a33d17ad2",
-                "reference": "11e7d5f93803a2190b00e145142cb00a33d17ad2",
+                "url": "https://api.github.com/repos/laravel/prompts/zipball/6a82ac19a28b916ae0885828795dbd4c59d9a818",
+                "reference": "6a82ac19a28b916ae0885828795dbd4c59d9a818",
                 "shasum": ""
             },
             "require": {
@@ -61,22 +61,22 @@
             "description": "Add beautiful and user-friendly forms to your command-line applications.",
             "support": {
                 "issues": "https://github.com/laravel/prompts/issues",
-                "source": "https://github.com/laravel/prompts/tree/v0.3.16"
+                "source": "https://github.com/laravel/prompts/tree/v0.3.17"
             },
-            "time": "2026-03-23T14:35:33+00:00"
+            "time": "2026-04-20T16:07:33+00:00"
         },
         {
             "name": "laravel/serializable-closure",
-            "version": "v2.0.11",
+            "version": "v2.0.13",
             "source": {
                 "type": "git",
                 "url": "https://github.com/laravel/serializable-closure.git",
-                "reference": "d1af40ac4a6ccc12bd062a7184f63c9995a63bdd"
+                "reference": "b566ee0dd251f3c4078bed003a7ce015f5ea6dce"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/laravel/serializable-closure/zipball/d1af40ac4a6ccc12bd062a7184f63c9995a63bdd",
-                "reference": "d1af40ac4a6ccc12bd062a7184f63c9995a63bdd",
+                "url": "https://api.github.com/repos/laravel/serializable-closure/zipball/b566ee0dd251f3c4078bed003a7ce015f5ea6dce",
+                "reference": "b566ee0dd251f3c4078bed003a7ce015f5ea6dce",
                 "shasum": ""
             },
             "require": {
@@ -124,7 +124,7 @@
                 "issues": "https://github.com/laravel/serializable-closure/issues",
                 "source": "https://github.com/laravel/serializable-closure"
             },
-            "time": "2026-04-07T13:32:18+00:00"
+            "time": "2026-04-16T14:03:50+00:00"
         },
         {
             "name": "php-di/invoker",
@@ -359,16 +359,16 @@
         },
         {
             "name": "symfony/console",
-            "version": "v7.4.8",
+            "version": "v7.4.9",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/console.git",
-                "reference": "1e92e39c51f95b88e3d66fa2d9f06d1fb45dd707"
+                "reference": "d7d2b64a45a89d607865927b176fa51c33ddbb58"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/console/zipball/1e92e39c51f95b88e3d66fa2d9f06d1fb45dd707",
-                "reference": "1e92e39c51f95b88e3d66fa2d9f06d1fb45dd707",
+                "url": "https://api.github.com/repos/symfony/console/zipball/d7d2b64a45a89d607865927b176fa51c33ddbb58",
+                "reference": "d7d2b64a45a89d607865927b176fa51c33ddbb58",
                 "shasum": ""
             },
             "require": {
@@ -433,7 +433,7 @@
                 "terminal"
             ],
             "support": {
-                "source": "https://github.com/symfony/console/tree/v7.4.8"
+                "source": "https://github.com/symfony/console/tree/v7.4.9"
             },
             "funding": [
                 {
@@ -453,7 +453,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-03-30T13:54:39+00:00"
+            "time": "2026-04-22T15:21:55+00:00"
         },
         {
             "name": "symfony/deprecation-contracts",
@@ -524,7 +524,7 @@
         },
         {
             "name": "symfony/polyfill-ctype",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-ctype.git",
@@ -583,7 +583,7 @@
                 "portable"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-ctype/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-ctype/tree/v1.37.0"
             },
             "funding": [
                 {
@@ -607,16 +607,16 @@
         },
         {
             "name": "symfony/polyfill-intl-grapheme",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-intl-grapheme.git",
-                "reference": "ad1b7b9092976d6c948b8a187cec9faaea9ec1df"
+                "reference": "4864388bfbd3001ce88e234fab652acd91fdc57e"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/ad1b7b9092976d6c948b8a187cec9faaea9ec1df",
-                "reference": "ad1b7b9092976d6c948b8a187cec9faaea9ec1df",
+                "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/4864388bfbd3001ce88e234fab652acd91fdc57e",
+                "reference": "4864388bfbd3001ce88e234fab652acd91fdc57e",
                 "shasum": ""
             },
             "require": {
@@ -665,7 +665,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-intl-grapheme/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-intl-grapheme/tree/v1.37.0"
             },
             "funding": [
                 {
@@ -685,11 +685,11 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-04-10T16:19:22+00:00"
+            "time": "2026-04-26T13:13:48+00:00"
         },
         {
             "name": "symfony/polyfill-intl-normalizer",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-intl-normalizer.git",
@@ -750,7 +750,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.37.0"
             },
             "funding": [
                 {
@@ -774,7 +774,7 @@
         },
         {
             "name": "symfony/polyfill-mbstring",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-mbstring.git",
@@ -835,7 +835,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.37.0"
             },
             "funding": [
                 {
@@ -1177,16 +1177,16 @@
         },
         {
             "name": "zhamao/logger",
-            "version": "1.1.4",
+            "version": "1.1.6",
             "source": {
                 "type": "git",
                 "url": "https://github.com/zhamao-robot/zhamao-logger.git",
-                "reference": "b28c0c26d59d58f153c764f224c21c5901213e25"
+                "reference": "ac5fa59428165d252566bb50c2f558fe871b7686"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/zhamao-robot/zhamao-logger/zipball/b28c0c26d59d58f153c764f224c21c5901213e25",
-                "reference": "b28c0c26d59d58f153c764f224c21c5901213e25",
+                "url": "https://api.github.com/repos/zhamao-robot/zhamao-logger/zipball/ac5fa59428165d252566bb50c2f558fe871b7686",
+                "reference": "ac5fa59428165d252566bb50c2f558fe871b7686",
                 "shasum": ""
             },
             "require": {
@@ -1230,19 +1230,19 @@
             "authors": [
                 {
                     "name": "jerry",
-                    "email": "admin@zhamao.me"
+                    "email": "github@cwcc.me"
                 },
                 {
                     "name": "sunxyw",
                     "email": "dev@sunxyw.xyz"
                 }
             ],
-            "description": "Another Console Logger for CLI Applications",
+            "description": "Another Colorful Console Logger for CLI Applications",
             "support": {
                 "issues": "https://github.com/zhamao-robot/zhamao-logger/issues",
-                "source": "https://github.com/zhamao-robot/zhamao-logger/tree/1.1.4"
+                "source": "https://github.com/zhamao-robot/zhamao-logger/tree/1.1.6"
             },
-            "time": "2025-11-08T15:38:01+00:00"
+            "time": "2026-05-06T06:47:06+00:00"
         }
     ],
     "packages-dev": [
@@ -1906,16 +1906,16 @@
         },
         {
             "name": "amphp/socket",
-            "version": "v2.3.1",
+            "version": "v2.4.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/amphp/socket.git",
-                "reference": "58e0422221825b79681b72c50c47a930be7bf1e1"
+                "reference": "dadb63c5d3179fd83803e29dfeac27350e619314"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/amphp/socket/zipball/58e0422221825b79681b72c50c47a930be7bf1e1",
-                "reference": "58e0422221825b79681b72c50c47a930be7bf1e1",
+                "url": "https://api.github.com/repos/amphp/socket/zipball/dadb63c5d3179fd83803e29dfeac27350e619314",
+                "reference": "dadb63c5d3179fd83803e29dfeac27350e619314",
                 "shasum": ""
             },
             "require": {
@@ -1924,17 +1924,17 @@
                 "amphp/dns": "^2",
                 "ext-openssl": "*",
                 "kelunik/certificate": "^1.1",
-                "league/uri": "^6.5 | ^7",
-                "league/uri-interfaces": "^2.3 | ^7",
+                "league/uri": "^7",
+                "league/uri-interfaces": "^7",
                 "php": ">=8.1",
-                "revolt/event-loop": "^1 || ^0.2"
+                "revolt/event-loop": "^1"
             },
             "require-dev": {
                 "amphp/php-cs-fixer-config": "^2",
                 "amphp/phpunit-util": "^3",
                 "amphp/process": "^2",
                 "phpunit/phpunit": "^9",
-                "psalm/phar": "5.20"
+                "psalm/phar": "6.16.1"
             },
             "type": "library",
             "autoload": {
@@ -1978,7 +1978,7 @@
             ],
             "support": {
                 "issues": "https://github.com/amphp/socket/issues",
-                "source": "https://github.com/amphp/socket/tree/v2.3.1"
+                "source": "https://github.com/amphp/socket/tree/v2.4.0"
             },
             "funding": [
                 {
@@ -1986,7 +1986,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2024-04-21T14:33:03+00:00"
+            "time": "2026-04-19T15:09:56+00:00"
         },
         {
             "name": "amphp/sync",
@@ -2885,16 +2885,16 @@
         },
         {
             "name": "friendsofphp/php-cs-fixer",
-            "version": "v3.95.0",
+            "version": "v3.95.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer.git",
-                "reference": "4ba5ab77108583d2a89ed48e1a5c01e62cc1d3f4"
+                "reference": "a9727678fbd12997f1d9de8f4a37824ed9df1065"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/PHP-CS-Fixer/PHP-CS-Fixer/zipball/4ba5ab77108583d2a89ed48e1a5c01e62cc1d3f4",
-                "reference": "4ba5ab77108583d2a89ed48e1a5c01e62cc1d3f4",
+                "url": "https://api.github.com/repos/PHP-CS-Fixer/PHP-CS-Fixer/zipball/a9727678fbd12997f1d9de8f4a37824ed9df1065",
+                "reference": "a9727678fbd12997f1d9de8f4a37824ed9df1065",
                 "shasum": ""
             },
             "require": {
@@ -2978,7 +2978,7 @@
             ],
             "support": {
                 "issues": "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/issues",
-                "source": "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/tree/v3.95.0"
+                "source": "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/tree/v3.95.1"
             },
             "funding": [
                 {
@@ -2986,7 +2986,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2026-04-11T17:30:38+00:00"
+            "time": "2026-04-12T17:00:09+00:00"
         },
         {
             "name": "humbug/box",
@@ -3235,16 +3235,16 @@
         },
         {
             "name": "justinrainbow/json-schema",
-            "version": "6.8.0",
+            "version": "6.8.2",
             "source": {
                 "type": "git",
                 "url": "https://github.com/jsonrainbow/json-schema.git",
-                "reference": "89ac92bcfe5d0a8a4433c7b89d394553ae7250cc"
+                "reference": "2c89ebb95ca9cedc9347f780333f7b25792dcb76"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/jsonrainbow/json-schema/zipball/89ac92bcfe5d0a8a4433c7b89d394553ae7250cc",
-                "reference": "89ac92bcfe5d0a8a4433c7b89d394553ae7250cc",
+                "url": "https://api.github.com/repos/jsonrainbow/json-schema/zipball/2c89ebb95ca9cedc9347f780333f7b25792dcb76",
+                "reference": "2c89ebb95ca9cedc9347f780333f7b25792dcb76",
                 "shasum": ""
             },
             "require": {
@@ -3254,7 +3254,7 @@
             },
             "require-dev": {
                 "friendsofphp/php-cs-fixer": "3.3.0",
-                "json-schema/json-schema-test-suite": "^23.2",
+                "json-schema/json-schema-test-suite": "dev-main",
                 "marc-mabe/php-enum-phpstan": "^2.0",
                 "phpspec/prophecy": "^1.19",
                 "phpstan/phpstan": "^1.12",
@@ -3304,9 +3304,9 @@
             ],
             "support": {
                 "issues": "https://github.com/jsonrainbow/json-schema/issues",
-                "source": "https://github.com/jsonrainbow/json-schema/tree/6.8.0"
+                "source": "https://github.com/jsonrainbow/json-schema/tree/6.8.2"
             },
-            "time": "2026-04-02T12:43:11+00:00"
+            "time": "2026-05-05T05:39:01+00:00"
         },
         {
             "name": "kelunik/certificate",
@@ -4347,11 +4347,11 @@
         },
         {
             "name": "phpstan/phpstan",
-            "version": "2.1.46",
+            "version": "2.1.54",
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/a193923fc2d6325ef4e741cf3af8c3e8f54dbf25",
-                "reference": "a193923fc2d6325ef4e741cf3af8c3e8f54dbf25",
+                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/8be50c3992107dc837b17da4d140fbbdf9a5c5bd",
+                "reference": "8be50c3992107dc837b17da4d140fbbdf9a5c5bd",
                 "shasum": ""
             },
             "require": {
@@ -4396,7 +4396,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2026-04-01T09:25:14+00:00"
+            "time": "2026-04-29T13:31:09+00:00"
         },
         {
             "name": "phpunit/php-code-coverage",
@@ -6651,16 +6651,16 @@
         },
         {
             "name": "symfony/event-dispatcher",
-            "version": "v8.0.8",
+            "version": "v8.0.9",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/event-dispatcher.git",
-                "reference": "f662acc6ab22a3d6d716dcb44c381c6002940df6"
+                "reference": "0c3c1a17604c4dbbec4b93fe162c538482096e1f"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/event-dispatcher/zipball/f662acc6ab22a3d6d716dcb44c381c6002940df6",
-                "reference": "f662acc6ab22a3d6d716dcb44c381c6002940df6",
+                "url": "https://api.github.com/repos/symfony/event-dispatcher/zipball/0c3c1a17604c4dbbec4b93fe162c538482096e1f",
+                "reference": "0c3c1a17604c4dbbec4b93fe162c538482096e1f",
                 "shasum": ""
             },
             "require": {
@@ -6712,7 +6712,7 @@
             "description": "Provides tools that allow your application components to communicate with each other by dispatching events and listening to them",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/event-dispatcher/tree/v8.0.8"
+                "source": "https://github.com/symfony/event-dispatcher/tree/v8.0.9"
             },
             "funding": [
                 {
@@ -6732,7 +6732,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-03-30T15:14:47+00:00"
+            "time": "2026-04-18T13:51:42+00:00"
         },
         {
             "name": "symfony/event-dispatcher-contracts",
@@ -6812,16 +6812,16 @@
         },
         {
             "name": "symfony/filesystem",
-            "version": "v7.4.8",
+            "version": "v7.4.9",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/filesystem.git",
-                "reference": "58b9790d12f9670b7f53a1c1738febd3108970a5"
+                "reference": "dcd8f96bcdc0f128ec406c765cc066c6035d1be3"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/filesystem/zipball/58b9790d12f9670b7f53a1c1738febd3108970a5",
-                "reference": "58b9790d12f9670b7f53a1c1738febd3108970a5",
+                "url": "https://api.github.com/repos/symfony/filesystem/zipball/dcd8f96bcdc0f128ec406c765cc066c6035d1be3",
+                "reference": "dcd8f96bcdc0f128ec406c765cc066c6035d1be3",
                 "shasum": ""
             },
             "require": {
@@ -6858,7 +6858,7 @@
             "description": "Provides basic utilities for the filesystem",
             "homepage": "https://symfony.com",
             "support": {
-                "source": "https://github.com/symfony/filesystem/tree/v7.4.8"
+                "source": "https://github.com/symfony/filesystem/tree/v7.4.9"
             },
             "funding": [
                 {
@@ -6878,7 +6878,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2026-03-24T13:12:05+00:00"
+            "time": "2026-04-18T13:18:21+00:00"
         },
         {
             "name": "symfony/finder",
@@ -7021,7 +7021,7 @@
         },
         {
             "name": "symfony/polyfill-iconv",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-iconv.git",
@@ -7081,7 +7081,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-iconv/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-iconv/tree/v1.37.0"
             },
             "funding": [
                 {
@@ -7105,7 +7105,7 @@
         },
         {
             "name": "symfony/polyfill-php84",
-            "version": "v1.34.0",
+            "version": "v1.37.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-php84.git",
@@ -7161,7 +7161,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-php84/tree/v1.34.0"
+                "source": "https://github.com/symfony/polyfill-php84/tree/v1.37.0"
             },
             "funding": [
                 {

config/artifact/ncurses.yml

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

config/env.ini

@@ -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-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-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/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,7 @@ gettext:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/pub/gnu/gettext/'
+      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

@@ -3,7 +3,7 @@ gmp:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/gnu/gmp/'
+      url: 'https://ftpmirror.gnu.org/gnu/gmp/'
       regex: '/href="(?<file>gmp-(?<version>[^"]+)\.tar\.xz)"/'
     source-mirror:
       type: url

config/pkg/lib/idn2.yml

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

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

@@ -3,9 +3,8 @@ libiconv:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/gnu/libiconv/'
+      url: 'https://ftpmirror.gnu.org/gnu/libiconv/'
       regex: '/href="(?<file>libiconv-(?<version>[^"]+)\.tar\.gz)"/'
-    binary: hosted
     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,7 +6,6 @@ libssh2:
       repo: libssh2/libssh2
       match: libssh2.+\.tar\.gz
       prefer-stable: true
-    binary: hosted
     metadata:
       license-files: [COPYING]
       license: BSD-3-Clause

config/pkg/lib/libunistring.yml

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

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

config/pkg/lib/readline.yml

@@ -3,7 +3,7 @@ readline:
   artifact:
     source:
       type: filelist
-      url: 'https://ftp.gnu.org/pub/gnu/readline/'
+      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

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

docs/en/develop/registry.md

@@ -9,7 +9,7 @@ StaticPHP ships with a built-in core registry (`core`) that contains all definit
 External Registries can only define new packages that don't already exist in `core`; they cannot override or modify existing definitions in the core registry. Depending on your needs, there are three ways to extend or modify StaticPHP's build capabilities:
 
 - **Modify the `core` registry**: Directly edit files under `src/Package` and `config/pkg/`, suitable when you want to contribute changes back to the StaticPHP mainline. Please read the [Contributing Guide](../contributing/) section on contributing new packages before submitting a PR.
-- **Vendor Mode**: Package your custom packages as a standalone sub-registry distributed as a Composer package, suitable for private packages or scenarios where you want to reuse build logic as a library. See [Vendor Mode](./vendor-mode/) for details.
+- **Vendor Mode**: Package your custom packages as a standalone sub-registry distributed as a Composer package, suitable for private packages or scenarios where you want to reuse build logic as a library. See [Extending StaticPHP](./extending/) for details.
 - **External Registry (`SPC_REGISTRIES`)**: Specify one or more external registry file paths via the `SPC_REGISTRIES` environment variable, which StaticPHP loads at startup. Suitable for temporary extensions or scenarios where packaging as a Composer package isn't practical, similar to external source mechanisms in other package managers.
 
 ## Registry Declaration File

docs/en/develop/source-module.md

@@ -1,5 +0,0 @@
-# Source Module
-
-<!-- TODO: Migrate and update from v2 source-module.md.
-  Document v3 source types: url, ghrel, ghtar, ghtagtar, git, pecl (new), filelist, custom.
-  Per-package YAML source block format. Parallel download (--parallel N). -->

docs/en/develop/vendor-mode/index.md

@@ -1,6 +0,0 @@
-# Vendor Mode
-
-<!-- TODO: What vendor mode is and when to use it.
-  Installation: `composer require crazywhalecc/static-php-cli`.
-  How to register an external registry pointing to your custom package classes.
-  Minimal working example: one Library class, one config YAML, run spc. -->

docs/en/guide/cli-reference.md

@@ -29,14 +29,14 @@ spc download [artifacts] [options]
 | `--for-packages=<list>`         |       | Download artifacts needed by the given packages       |
 | `--without-suggests`            |       | Skip suggested packages when using `--for-extensions` |
 | `--clean`                       |       | Delete existing download cache before fetching        |
-| `--with-php=<ver>`              |       | PHP version in `major.minor` format (default: `8.4`)  |
+| `--with-php=<ver>`              |       | PHP version in `major.minor` format (default: `8.5`)  |
 | `--prefer-binary`               | `-p`  | Prefer pre-built binaries over source archives        |
 | `--prefer-source`               |       | Prefer source archives over pre-built binaries        |
 | `--source-only`                 |       | Only download source artifacts                        |
 | `--binary-only`                 |       | Only download binary artifacts                        |
 | `--parallel=<n>`                | `-P`  | Number of parallel downloads (default: `1`)           |
 | `--retry=<n>`                   | `-R`  | Number of retries on failure (default: `0`)           |
-| `--ignore-cache=<list>`         |       | Force re-download the specified artifacts             |
+| `--ignore-cache=<list>`         | `-i`  | Force re-download the specified artifacts             |
 | `--no-alt`                      |       | Do not use alternative mirror URLs                    |
 | `--no-shallow-clone`            |       | Do not clone git repositories shallowly               |
 | `--custom-url=<src:url>`        | `-U`  | Override the download URL for a source                |
@@ -47,7 +47,7 @@ spc download [artifacts] [options]
 
 ```bash
 # Download only what the chosen extensions need
-spc download --for-extensions="bcmath,openssl,curl" --with-php=8.4
+spc download --for-extensions="bcmath,openssl,curl" --with-php=8.5
 
 # Download specific artifacts
 spc download "php-src,openssl"
@@ -125,9 +125,10 @@ These flags apply only to the combined `build:php` target. To build a specific S
 
 ### embed Options {#embed-options}
 
-| Option                  | Description                                                           |
-|-------------------------|-----------------------------------------------------------------------|
-| `--build-shared=<list>` | Compile specific extensions as shared libraries (requires embed SAPI) |
+| Option                      | Description                                                                                          |
+|-----------------------------|------------------------------------------------------------------------------------------------------|
+| `--build-shared=<list>`     | Compile specific extensions as shared libraries (requires embed SAPI)                                |
+| `--maintainer-skip-build`   | (maintainer only) Skip the PHP embed build if `libphp.a` / `libphp.so` already exists in buildroot  |
 
 ### Download Pass-through Options {#download-options}
 
@@ -135,7 +136,7 @@ All downloader options are available with the `--dl-` prefix:
 
 | Option                             | Description                                |
 |------------------------------------|--------------------------------------------|
-| `--dl-with-php=<ver>`              | PHP version to download (default: `8.4`)   |
+| `--dl-with-php=<ver>`              | PHP version to download (default: `8.5`)   |
 | `--dl-prefer-binary`               | Prefer pre-built binaries for dependencies |
 | `--dl-parallel=<n>`                | Number of parallel downloads               |
 | `--dl-retry=<n>`                   | Number of retries on failure               |
@@ -264,12 +265,12 @@ spc check-update [artifact] [options]
 
 ### Options
 
-| Option | Short | Description |
-|---|---|---|
-| `--json` | | Output results in JSON format |
+| Option | Short | Description                                                                              |
+|---|---|------------------------------------------------------------------------------------------|
+| `--json` | | Output results in JSON format                                                            |
 | `--bare` | | Check without requiring the artifact to be downloaded first (old version will be `null`) |
-| `--parallel=<n>` | `-p` | Number of parallel update checks (default: `10`) |
-| `--with-php=<ver>` | | PHP version context in `major.minor` format (default: `8.4`) |
+| `--parallel=<n>` | `-p` | Number of parallel update checks (default: `10`)                                         |
+| `--with-php=<ver>` | | PHP version context in `major.minor` format (default: `8.5`)                             |
 
 ### Examples
 
@@ -516,10 +517,3 @@ spc spc-config "bcmath,openssl" --libs
 # Use absolute library paths
 spc spc-config "bcmath,openssl" --libs --absolute-libs
 ```
-Enter an interactive shell with StaticPHP's build environment pre-loaded (compiler wrappers, `buildroot/`, `pkgroot/` paths, etc. on `PATH`).
-
-```bash
-spc dev:shell
-```
-
-Useful for compiling small programs against `libphp.a` (embed SAPI) or inspecting the build environment manually.

docs/en/guide/env-vars.md

@@ -51,6 +51,6 @@ without modifying the default `config/env.ini` file.
 SPC_CONCURRENCY=4
 
 [linux]
-SPC_DEFAULT_C_FLAGS="-O3"
+SPC_DEFAULT_CFLAGS="-O3"
 ```
 

docs/en/guide/first-build.md

@@ -26,7 +26,7 @@ The `craft` command reads a `craft.yml` file and handles everything automaticall
 Create a `craft.yml` in your working directory and declare the PHP version, extensions, and target SAPIs:
 
 ```yaml
-php-version: 8.4
+php-version: 8.5
 extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
 sapi:
   - cli
@@ -74,12 +74,16 @@ This approach lets you run download and compile as separate steps — useful whe
 
 ### Step 1: Download Dependencies
 
+In v3, you can skip this step entirely — running `build:php` directly will automatically download any missing artifacts.
+
+If you want to pre-download ahead of time, or if you're working in a slow-network environment and want to separate the download phase, use the `download` command:
+
 ```bash
 # Download only what the chosen extensions need (recommended)
-spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.4
+spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.5
 
 # Download by specific package names
-spc download "curl,openssl" --with-php=8.4
+spc download "curl,openssl" --with-php=8.5
 ```
 
 Downloads are cached in `downloads/` and reused across builds automatically.

docs/en/guide/index.md

@@ -45,6 +45,10 @@ Build your CLI with [symfony/console](https://symfony.com/doc/current/components
 
 [FrankenPHP](https://frankenphp.dev) is a modern PHP app server with built-in HTTP/2, HTTP/3, and automatic HTTPS. StaticPHP can compile FrankenPHP together with your chosen extensions into one binary. The result is a complete web server in a single file — no Nginx, no PHP-FPM, just deploy and run.
 
+## Community
+
+Join our [Discord server](https://discord.gg/xf6Rd4pEAk) to ask questions, share your builds, and connect with other StaticPHP users.
+
 ## Next steps
 
 - [Installation](./installation) — Get the StaticPHP build tool

docs/en/guide/installation.md

@@ -27,18 +27,23 @@ Pick the installation method that fits your use case:
 
 > Fun fact: `spc` itself is a static PHP binary built with StaticPHP. We use StaticPHP to build StaticPHP's own build tool.
 
-```shell
-# Linux x86_64
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-x86_64 -o spc
-# Linux arm64
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-aarch64 -o spc
-# macOS x86_64 (Intel)
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-x86_64 -o spc
-# macOS arm64 (Apple Silicon)
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-aarch64 -o spc
-# Windows x86_64 (PowerShell)
-curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe -o spc.exe
+::: code-group
+```shell [Linux x86_64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64 -o spc
 ```
+```shell [Linux arm64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64 -o spc
+```
+```shell [macOS x86_64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64 -o spc
+```
+```shell [macOS arm64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64 -o spc
+```
+```powershell [Windows x86_64]
+curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe -o spc.exe
+```
+:::
 
 On Linux and macOS, mark the binary as executable before running it:
 
@@ -82,13 +87,6 @@ The script downloads `php` and `composer` into a `runtime/` subdirectory. You th
    # Add this to ~/.bashrc or ~/.zshrc to make it permanent
    ```
 
-::: tip
-In regions with restricted access to GitHub or getcomposer.org, pass `--mirror china` to use a mirror:
-```bash
-bin/setup-runtime --mirror china
-```
-:::
-
 ## Vendor mode
 
 If you already have a PHP project and want to call StaticPHP's build APIs directly, or use a custom registry to support private libraries and extensions, pull it in as a Composer dependency:
@@ -97,7 +95,7 @@ If you already have a PHP project and want to call StaticPHP's build APIs direct
 composer require crazywhalecc/static-php-cli
 ```
 
-See the [Vendor Mode guide](../develop/vendor-mode/) for details.
+See the [Extending StaticPHP](../develop/extending/) guide for details.
 
 ## Verify your build environment
 

docs/en/guide/migrate-from-v2.md

@@ -0,0 +1,210 @@
+# Migrating from v2
+
+StaticPHP v3 is a ground-up rewrite. The core build workflow (`download → build → combine`) remains familiar, but several commands, options, and configuration fields have changed. This page covers everything you need to update before switching.
+
+::: info Scope
+This guide only covers user-facing CLI commands, options, `craft.yml` fields, and `env.ini` variable names. Internal PHP APIs are not covered.
+:::
+
+## Documentation URL Change
+
+The official documentation site has moved:
+
+- **v3 docs (current)**: [https://static-php.dev](https://static-php.dev) — the main site now hosts v3 documentation.
+- **v2 docs (archived)**: [https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 documentation is preserved here for reference.
+
+Update any bookmarks or internal links accordingly.
+
+## `spc` Binary Download URL Change
+
+The nightly `spc` self-contained binary has moved to a new path:
+
+| | URL |
+|---|---|
+| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
+| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
+
+Update any CI scripts or bootstrap commands that download the `spc` binary directly. For example:
+
+```bash
+# v2
+curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+
+# v3
+curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
+```
+
+## Removed Commands
+
+| v2 Command | v3 Replacement | Notes |
+|---|---|---|
+| `del-download` | `spc reset` | `reset` also accepts `--with-pkgroot` and `--with-download` for finer control |
+| `del-download --all` | `spc reset --with-download` | Removes the downloads cache directory |
+
+## Removed Options
+
+### `--with-added-patch` / `-P` (build command)
+
+This option allowed injecting external PHP patch scripts at specific build stages. **It has been removed in v3.**
+
+There is no direct drop-in replacement. If you relied on this feature:
+
+- Consider contributing your patches upstream to the StaticPHP repository.
+- For project-specific patches, use a custom registry with a package class. See [Writing Package Classes](/en/develop/extending/package-classes) for details.
+
+::: tip Future Plans
+A single-file hook API for lightweight patches may be provided in a future release.
+:::
+
+### Windows-only: `--with-sdk-binary-dir` and `--vs-ver`
+
+These options are no longer accepted on the command line. Instead, set the `PHP_SDK_PATH` environment variable to point to your PHP SDK binary tools directory. The Visual Studio version is now managed by the toolchain configuration.
+
+## Renamed / Deprecated Options
+
+The following options have been renamed. The old names are accepted where noted, but you should update your scripts.
+
+| v2 Option | v3 Option | Status |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | Old name kept as a deprecated alias |
+| `--with-libs=<list>` | `--with-packages=<list>` | — |
+| `--with-suggested-libs` / `-L` | `--with-suggests` | Old `-L` / `-E` flags removed |
+| `--with-suggested-exts` / `-E` | `--with-suggests` | Merged into a single flag |
+
+### Example
+
+```bash
+# v2
+spc build curl,gd --build-cli --with-libs="openssl" -L -E
+
+# v3
+spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
+```
+
+## Changed `build` Command Behaviour
+
+The `build` command (alias: `build:php`) still works. However, v3 also provides **dedicated single-target commands** that do not require SAPI selection flags:
+
+| v2 | v3 Equivalent |
+|---|---|
+| `spc build exts --build-cli` | `spc build:php-cli exts` |
+| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
+| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
+| `spc build exts --build-micro` | `spc build:php-micro exts` |
+| `spc build exts --build-embed` | `spc build:php-embed exts` |
+| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
+
+Use `build:php` when you need to build multiple SAPIs in one pass (the `--build-*` flags remain valid there).
+
+### Automatic Download in Build Commands
+
+In v3, all `build:*` commands automatically download any missing dependencies before building. You no longer need to run `spc download` as a separate step:
+
+```bash
+# v2 — two steps required
+spc download --for-extensions=curl,gd
+spc build curl,gd --build-cli
+
+# v3 — one step is enough
+spc build:php-cli curl,gd
+```
+
+To opt out of the automatic download (for example in CI where sources are pre-cached), pass `--no-download`:
+
+```bash
+spc build:php-cli curl,gd --no-download
+```
+
+## Changed `download` Command Options
+
+| v2 | v3 | Notes |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | Deprecated alias kept |
+| `--with-libs` | `--for-libs` | Separate from packages |
+| *(no equivalent)* | `--for-packages` | Unified package filter |
+| *(no equivalent)* | `--parallel` / `-P` | Parallel downloads |
+| *(no equivalent)* | `--retry` / `-R` | Retry on failure |
+
+## Removed Dev Commands
+
+These development utility commands have been removed or consolidated:
+
+| v2 Command | v3 Replacement |
+|---|---|
+| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
+| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
+| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
+| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
+| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
+
+## Renamed Dev Commands
+
+| v2 | v3 | Notes |
+|---|---|---|
+| `dev:sort-config` / `sort-config` | `dev:lint-config` | Old alias still accepted |
+
+## New Commands in v3
+
+These commands are new in v3 with no v2 equivalent:
+
+| Command | Description |
+|---|---|
+| `spc reset` | Clean `buildroot/` and `source/` directories |
+| `spc check-update` | Check for newer artifact versions |
+| `spc build:php-cli` | Build CLI SAPI (no flags needed) |
+| `spc build:php-fpm` | Build PHP-FPM (no flags needed) |
+| `spc build:php-cgi` | Build PHP CGI (no flags needed) |
+| `spc build:php-micro` | Build phpmicro (no flags needed) |
+| `spc build:php-embed` | Build embed SAPI (no flags needed) |
+| `spc build:frankenphp` | Build FrankenPHP (no flags needed) |
+| `spc dev:shell` | Interactive shell with build environment |
+| `spc dev:is-installed` | Check whether a package is installed |
+| `spc dev:dump-stages` | Dump all package build stages to JSON |
+| `spc dev:dump-capabilities` | Dump buildable/installable capabilities |
+| `spc dev:info` | Show configuration info for a package |
+
+## `craft.yml` Changes
+
+### Removed: `build-options.with-added-patch`
+
+The `with-added-patch` key inside `build-options` is no longer parsed and will be silently ignored. Remove it from your `craft.yml`:
+
+```yaml
+# v2 — remove this block
+build-options:
+  with-added-patch:
+    - my-patch.php
+```
+
+### `libs` → `packages` (both work)
+
+The top-level `libs` field still works. The preferred v3 field name is `packages`, which is a superset covering libraries and other tool packages:
+
+```yaml
+# v2
+libs: nghttp2,liblz4
+
+# v3 (preferred)
+packages: nghttp2,liblz4
+```
+
+## `env.ini` Variable Renames
+
+If you customise `config/env.ini` or export environment variables in CI, update the following names:
+
+| v2 Variable | v3 Variable |
+|---|---|
+| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
+| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
+| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
+| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
+| `SPC_LIBC` | `SPC_TARGET` |
+
+`SPC_TARGET` uses a new format that encodes both architecture and libc in a single string, for example:
+
+| v2 | v3 |
+|---|---|
+| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
+| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
+
+New logging variables were also added (`SPC_ENABLE_LOG_FILE`, `SPC_LOGS_DIR`, `SPC_PRESERVE_LOGS`). Refer to [Environment Variables](/en/guide/env-vars) for details.

docs/public/CNAME

@@ -0,0 +1 @@
+static-php.dev

docs/zh/develop/craft-yml.md

@@ -4,4 +4,4 @@ aside: false
 
 # craft.yml 配置详解
 
-<!-- TODO: craft.yml 字段完整参考。 -->
+<!--@include: ../../deps-craft-yml.md-->

docs/zh/develop/extending/custom-artifact.md

@@ -0,0 +1,8 @@
+# 自定义 Artifact
+
+<!-- TODO: 介绍如何在 src/Package/Artifact/ 下实现自定义下载类。
+  说明 type: custom 的适用场景（如需鉴权、非标准压缩包格式等）。
+  涵盖：类的位置与命名规范、方法签名（默认下载方法与 func 分发）、
+  读取配置字段、返回解压后的源码路径、
+  通过 spc.registry.yml 的 artifact psr-4 映射注册类。
+  提供带注释的完整代码示例。 -->

docs/zh/develop/extending/index.md

@@ -0,0 +1,8 @@
+# 扩展 StaticPHP
+
+<!-- TODO: 介绍三种扩展方式：
+  1. 贡献到 core —— 直接修改 src/Package/ 和 config/pkg/。
+  2. 外部 Registry —— 通过 SPC_REGISTRIES 环境变量指向自定义 spc.registry.yml。
+  3. Vendor 模式 —— 将类和配置打包为 Composer 库（composer require）。
+  说明各方式的适用场景。给出最小端到端示例：
+  一个 Library 类 + 一个配置 YAML + 一个 spc.registry.yml + 运行 spc。 -->

docs/zh/develop/registry.md

@@ -12,7 +12,7 @@ StaticPHP 本身携带一个内置的核心注册表（`core`），其中包含
 外部 Registry 只能定义 `core` 中尚不存在的新包，不能覆盖或修改核心注册表中已有的定义。根据你的需求，有以下三种方式来扩展或修改 StaticPHP 的构建能力：
 
 - **修改 `core` 注册表**：直接修改 `src/Package` 和 `config/pkg/` 下的文件，适用于希望将改动合并回 StaticPHP 主线的情况。请先阅读 [贡献指南](../contributing/) 中关于贡献新包的部分，再提交 PR。
-- **Vendor 模式**：将自定义包封装为一个独立的子注册表，以 Composer 包的形式分发，适用于需要私有包或希望以库的形式复用构建逻辑的场景。详见 [Vendor 模式](./vendor-mode/)。
+- **Vendor 模式**：将自定义包封装为一个独立的子注册表，以 Composer 包的形式分发，适用于需要私有包或希望以库的形式复用构建逻辑的场景。详见 [扩展 StaticPHP](./extending/)。
 - **外部注册表（`SPC_REGISTRIES`）**：通过环境变量 `SPC_REGISTRIES` 指定一个或多个外部注册表文件的路径，StaticPHP 会在启动时加载它们。适用于临时扩展或不便打包为 Composer 包的场景，与其他包管理器的外部源机制类似。
 
 ## Registry 定义文件

docs/zh/develop/source-module.md

@@ -1,5 +0,0 @@
-# 资源模块
-
-<!-- TODO: 从 v2 source-module.md 迁移并更新。
-  记录 v3 source 类型：url、ghrel、ghtar、ghtagtar、git、pecl（新增）、filelist、custom。
-  per-package YAML source 块格式。并行下载（--parallel N）。 -->

docs/zh/develop/vendor-mode/index.md

@@ -1,6 +0,0 @@
-# Vendor 模式
-
-<!-- TODO: Vendor 模式是什么，适用场景。
-  安装：`composer require crazywhalecc/static-php-cli`。
-  注册指向自定义包类的外部 Registry。
-  最小工作示例：一个 Library 类 + 一个配置 YAML + 运行 spc。 -->

docs/zh/guide/cli-reference.md

@@ -22,32 +22,32 @@ spc download [artifacts] [options]
 
 ### 选项
 
-| 选项 | 缩写 | 说明 |
-|---|---|---|
-| `--for-extensions=<list>` | `-e` | 按扩展名下载其所需的制品 |
-| `--for-libs=<list>` | `-l` | 按库名下载其所需的制品 |
-| `--for-packages=<list>` | | 按包名下载其所需的制品 |
-| `--without-suggests` | | 使用 `--for-extensions` 时跳过建议包 |
-| `--clean` | | 下载前删除旧的下载缓存 |
-| `--with-php=<ver>` | | PHP 版本，格式为 `major.minor`（默认 `8.4`）|
-| `--prefer-binary` | `-p` | 优先使用预编译二进制 |
-| `--prefer-source` | | 优先使用源码包 |
-| `--source-only` | | 仅下载源码制品 |
-| `--binary-only` | | 仅下载二进制制品 |
-| `--parallel=<n>` | `-P` | 并行下载数（默认 `1`）|
-| `--retry=<n>` | `-R` | 失败重试次数（默认 `0`）|
-| `--ignore-cache=<list>` | | 强制重新下载指定制品 |
-| `--no-alt` | | 不使用镜像站 |
-| `--no-shallow-clone` | | 不使用浅层克隆 |
-| `--custom-url=<src:url>` | `-U` | 覆盖指定源的下载地址 |
-| `--custom-git=<src:branch:url>` | `-G` | 覆盖为自定义 git 仓库 |
-| `--custom-local=<src:path>` | `-L` | 使用本地路径作为制品来源 |
+| 选项 | 缩写   | 说明                                 |
+|---|------|------------------------------------|
+| `--for-extensions=<list>` | `-e` | 按扩展名下载其所需的制品                       |
+| `--for-libs=<list>` | `-l` | 按库名下载其所需的制品                        |
+| `--for-packages=<list>` |      | 按包名下载其所需的制品                        |
+| `--without-suggests` |      | 使用 `--for-extensions` 时跳过建议包       |
+| `--clean` |      | 下载前删除旧的下载缓存                        |
+| `--with-php=<ver>` |      | PHP 版本，格式为 `major.minor`（默认 `8.5`） |
+| `--prefer-binary` | `-p` | 优先使用预编译二进制                         |
+| `--prefer-source` |      | 优先使用源码包                            |
+| `--source-only` |      | 仅下载源码制品                            |
+| `--binary-only` |      | 仅下载二进制制品                           |
+| `--parallel=<n>` | `-P` | 并行下载数（默认 `1`）                      |
+| `--retry=<n>` | `-R` | 失败重试次数（默认 `0`）                     |
+| `--ignore-cache=<list>` | `-i` | 强制重新下载指定制品                         |
+| `--no-alt` |      | 不使用镜像站                             |
+| `--no-shallow-clone` |      | 不使用浅层克隆                            |
+| `--custom-url=<src:url>` | `-U` | 覆盖指定源的下载地址                         |
+| `--custom-git=<src:branch:url>` | `-G` | 覆盖为自定义 git 仓库                      |
+| `--custom-local=<src:path>` | `-L` | 使用本地路径作为制品来源                       |
 
 ### 示例
 
 ```bash
 # 按扩展名下载（推荐）
-spc download --for-extensions="bcmath,openssl,curl" --with-php=8.4
+spc download --for-extensions="bcmath,openssl,curl" --with-php=8.5
 
 # 下载指定制品
 spc download "php-src,openssl"
@@ -128,19 +128,20 @@ spc build:php <extensions> [options]
 | 选项 | 说明 |
 |---|---|
 | `--build-shared=<list>` | 将指定扩展编译为共享库（需要 embed SAPI）|
+| `--maintainer-skip-build` | （仅维护者）若 buildroot 中已存在 `libphp.a` / `libphp.so`，则跳过 PHP embed 的编译构建 |
 
 ### 下载透传选项 {#download-options}
 
 所有下载器选项均可加 `--dl-` 前缀使用：
 
-| 选项 | 说明 |
-|---|---|
-| `--dl-with-php=<ver>` | 指定下载的 PHP 版本（默认 `8.4`）|
-| `--dl-prefer-binary` | 优先使用预编译二进制依赖 |
-| `--dl-parallel=<n>` | 并行下载数 |
-| `--dl-retry=<n>` | 失败重试次数 |
-| `--dl-custom-url=<src:url>` | 覆盖指定源的下载地址 |
-| `--dl-custom-git=<src:branch:url>` | 覆盖为自定义 git 仓库 |
+| 选项 | 说明                     |
+|---|------------------------|
+| `--dl-with-php=<ver>` | 指定下载的 PHP 版本（默认 `8.5`） |
+| `--dl-prefer-binary` | 优先使用预编译二进制依赖           |
+| `--dl-parallel=<n>` | 并行下载数                  |
+| `--dl-retry=<n>` | 失败重试次数                 |
+| `--dl-custom-url=<src:url>` | 覆盖指定源的下载地址             |
+| `--dl-custom-git=<src:branch:url>` | 覆盖为自定义 git 仓库          |
 
 Downloader 选项传递给 `build:php` 命令时，会被自动下载器在构建前使用。
 这样你就可以直接通过构建命令控制下载行为，无需单独执行 `spc download` 命令。
@@ -264,12 +265,12 @@ spc check-update [artifact] [options]
 
 ### 选项
 
-| 选项 | 缩写 | 说明 |
-|---|---|---|
-| `--json` | | 以 JSON 格式输出结果 |
-| `--bare` | | 检查时不要求制品已下载（旧版本显示为 null）|
-| `--parallel=<n>` | `-p` | 并行检查数（默认 `10`）|
-| `--with-php=<ver>` | | PHP 版本上下文，格式为 `major.minor`（默认 `8.4`）|
+| 选项 | 缩写 | 说明                                    |
+|---|---|---------------------------------------|
+| `--json` | | 以 JSON 格式输出结果                         |
+| `--bare` | | 检查时不要求制品已下载（旧版本显示为 null）              |
+| `--parallel=<n>` | `-p` | 并行检查数（默认 `10`）                        |
+| `--with-php=<ver>` | | PHP 版本上下文，格式为 `major.minor`（默认 `8.5`） |
 
 ### 示例
 
@@ -405,9 +406,6 @@ spc install-pkg <package> [options]
 ```bash
 # 安装 UPX 压缩工具
 spc install-pkg upx
-
-# 安装时优先使用预编译二进制（默认行为）
-spc install-pkg upx
 ```
 
 ## micro:combine

docs/zh/guide/deps-map.md

@@ -8,7 +8,7 @@ aside: false
 
 - **必需依赖**：构建该包时会强制一同构建的包。
 - **可选依赖**：默认不构建，使用 `--with-suggests` 参数可启用，或在构建命令中手动指定。
-- **被依赖**：其他哪些包需要当前包。
+- **被依赖 / 被建议**：其他哪些包将当前包作为必需或可选依赖。
 
 运行以下命令生成依赖数据（需要在源码模式下）：
 

docs/zh/guide/env-vars.md

@@ -46,6 +46,6 @@ SPC_CONCURRENCY=4 spc build:php "mbstring,pcntl" --build-cli
 SPC_CONCURRENCY=4
 
 [linux]
-SPC_DEFAULT_C_FLAGS="-O3"
+SPC_DEFAULT_CFLAGS="-O3"
 ```
 

docs/zh/guide/extension-notes.md

@@ -90,7 +90,7 @@ bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
 
 ## xml
 
-1. xml 包括 xmlreader、xmlwriter、dom、simplexml 等，添加 xml 扩展时最好同时启用这些扩展。
+1. xml 包括 xmlreader、xmlwriter、xsl、dom、simplexml 等，添加 xml 扩展时最好同时启用这些扩展。
 2. libxml 包含在 xml 扩展中。启用 xml 相当于启用 libxml。
 
 ## glfw

docs/zh/guide/first-build.md

@@ -26,7 +26,7 @@ StaticPHP 提供两种构建方式，根据使用场景选择：
 在当前目录创建 `craft.yml`，声明要编译的 PHP 版本、扩展和目标 SAPI：
 
 ```yaml
-php-version: 8.4
+php-version: 8.5
 extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
 sapi:
   - cli
@@ -80,10 +80,10 @@ v3 版本中，你可以省略这一步骤，直接构建想要的内容，Stati
 
 ```bash
 # 按扩展列表下载（推荐，只下载实际需要的内容）
-spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.4
+spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.5
 
 # 按依赖包列表下载
-spc download "curl,openssl" --with-php=8.4
+spc download "curl,openssl" --with-php=8.5
 ```
 
 下载内容缓存在 `downloads/` 目录，重复构建时会直接复用。

docs/zh/guide/index.md

@@ -53,6 +53,10 @@ micro.sfx + your-app.phar = your-app  （可直接运行，无任何依赖）
 StaticPHP 支持将 FrankenPHP 连同所需扩展一起静态编译，
 最终产物是一个包含完整 Web 服务器的单一可执行文件，无需 Nginx、PHP-FPM，直接部署即可运行。
 
+## 社区
+
+加入我们的 [Discord 服务器](https://discord.gg/xf6Rd4pEAk)，提问、分享构建成果，与其他 StaticPHP 用户交流。
+
 ## 接下来
 
 - [安装 StaticPHP](./installation) — 安装 StaticPHP 构建工具

docs/zh/guide/installation.md

@@ -27,18 +27,23 @@ spc 无须任何依赖，下载即可运行，支持 Linux、macOS 和 Windows
 
 > spc 本身是由 StaticPHP 构建的静态 PHP 二进制，幽默地说：我们用 StaticPHP 构建了 StaticPHP 的构建工具。
 
-```shell
-# Linux x86_64
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-x86_64 -o spc
-# Linux arm64
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-linux-aarch64 -o spc
-# macOS x86_64 (Intel)
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-x86_64 -o spc
-# macOS arm64 (Apple Silicon)
-curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-macos-aarch64 -o spc
-# Windows x86_64 (PowerShell)
-curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe -o spc.exe
+::: code-group
+```shell [Linux x86_64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64 -o spc
 ```
+```shell [Linux arm64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64 -o spc
+```
+```shell [macOS x86_64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64 -o spc
+```
+```shell [macOS arm64]
+curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64 -o spc
+```
+```powershell [Windows x86_64]
+curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe -o spc.exe
+```
+:::
 
 *nix 系统下载完成后需要赋予可执行权限：
 
@@ -51,7 +56,7 @@ chmod +x spc && ./spc --version
 适合想参与开发、或需要修改核心注册表和构建脚本的开发者。需要系统已安装 PHP >= 8.4、Composer，以及 `mbstring,posix,pcntl,iconv,phar,zlib` 扩展。
 
 ```bash
-git clone https://github.com/static-php/static-php.git --branch v3
+git clone https://github.com/crazywhalecc/static-php-cli.git --branch v3
 cd static-php-cli
 composer install
 ```
@@ -90,7 +95,7 @@ bin/setup-runtime
 composer require crazywhalecc/static-php-cli
 ```
 
-Vendor 模式的详细用法见 [Vendor 模式指南](../develop/vendor-mode/)。
+Vendor 模式的详细用法见 [扩展 StaticPHP](../develop/extending/)。
 
 ## 验证构建环境
 
@@ -100,9 +105,15 @@ Vendor 模式的详细用法见 [Vendor 模式指南](../develop/vendor-mode/)
 
 ```bash
 # 使用 spc 二进制
-./spc doctor --auto-fix
+./spc doctor
 # 使用源码安装
-bin/spc doctor --auto-fix
+bin/spc doctor
+```
+
+如有缺失，`--auto-fix` 会尝试自动安装修复：
+
+```bash
+./spc doctor --auto-fix
 ```
 
 检查通过后，继续阅读[第一次构建](./first-build)。

docs/zh/guide/migrate-from-v2.md

@@ -0,0 +1,210 @@
+# 从 v2 迁移
+
+StaticPHP v3 是一次完整的重写。核心构建流程（`download → build → combine`）保持不变，但部分命令、选项和配置字段已发生变化。本页列出了切换前所有需要更新的内容。
+
+::: info 范围说明
+本指南仅涵盖面向用户的 CLI 命令、选项、`craft.yml` 字段和 `env.ini` 变量名称。不涵盖内部 PHP API。
+:::
+
+## 文档地址变更
+
+官方文档站点已迁移：
+
+- **v3 文档（当前）**：[https://static-php.dev](https://static-php.dev) — 主站现在托管 v3 文档。
+- **v2 文档（归档）**：[https://static-php.github.io/v2-docs/](https://static-php.github.io/v2-docs/) — v2 文档已归档保留，供参考。
+
+请更新你保存的书签或内部链接。
+
+## `spc` 二进制下载地址变更
+
+nightly `spc` 自包含二进制文件已迁移到新路径：
+
+| | 地址 |
+|---|---|
+| **v2** | `https://dl.static-php.dev/static-php-cli/spc-bin/nightly/` |
+| **v3** | `https://dl.static-php.dev/v3/spc-bin/nightly/` |
+
+请更新所有直接下载 `spc` 二进制的 CI 脚本或初始化命令，例如：
+
+```bash
+# v2
+curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+
+# v3
+curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
+```
+
+## 已移除的命令
+
+| v2 命令 | v3 替代方案 | 说明 |
+|---|---|---|
+| `del-download` | `spc reset` | `reset` 支持 `--with-pkgroot` 和 `--with-download` 以进行更细粒度的控制 |
+| `del-download --all` | `spc reset --with-download` | 删除下载缓存目录 |
+
+## 已移除的选项
+
+### `--with-added-patch` / `-P`（build 命令）
+
+该选项允许在特定构建阶段注入外部 PHP patch 脚本。**v3 已完全移除此功能。**
+
+目前没有直接的替代方案。如果你依赖此功能，请考虑以下方式：
+
+- 将你的 patch 贡献到 StaticPHP 的上游仓库。
+- 对于项目专用的 patch，可以使用自定义 registry 并编写 Package 类。详情参见[编写 Package 类](/zh/develop/extending/package-classes)。
+
+::: tip 未来计划
+未来版本可能会提供用于轻量级 patch 的单文件 hook API。
+:::
+
+### Windows 专有：`--with-sdk-binary-dir` 和 `--vs-ver`
+
+这两个选项已不再被命令行接受。请改为设置 `PHP_SDK_PATH` 环境变量，指向你的 PHP SDK binary tools 目录。Visual Studio 版本现在由工具链配置统一管理。
+
+## 已重命名 / 已弃用的选项
+
+以下选项已重命名。部分旧名称仍作为弃用别名被接受，但建议尽快更新脚本。
+
+| v2 选项 | v3 选项 | 状态 |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | 旧名称保留为弃用别名 |
+| `--with-libs=<list>` | `--with-packages=<list>` | — |
+| `--with-suggested-libs` / `-L` | `--with-suggests` | 旧 `-L` / `-E` 已移除 |
+| `--with-suggested-exts` / `-E` | `--with-suggests` | 已合并为单一标志 |
+
+### 示例
+
+```bash
+# v2
+spc build curl,gd --build-cli --with-libs="openssl" -L -E
+
+# v3
+spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
+```
+
+## `build` 命令行为变化
+
+`build` 命令（别名：`build:php`）仍然可用。但 v3 新增了**专用的单目标构建命令**，无需再传入 SAPI 选择标志：
+
+| v2 | v3 等价命令 |
+|---|---|
+| `spc build exts --build-cli` | `spc build:php-cli exts` |
+| `spc build exts --build-fpm` | `spc build:php-fpm exts` |
+| `spc build exts --build-cgi` | `spc build:php-cgi exts` |
+| `spc build exts --build-micro` | `spc build:php-micro exts` |
+| `spc build exts --build-embed` | `spc build:php-embed exts` |
+| `spc build exts --build-frankenphp` | `spc build:frankenphp exts` |
+
+如果需要在一次构建中同时编译多个 SAPI，请继续使用 `build:php`（`--build-*` 标志在该命令下仍然有效）。
+
+### 构建命令自动下载依赖
+
+v3 中，所有 `build:*` 命令在构建前会自动下载缺失的依赖包，不再需要单独执行 `spc download`：
+
+```bash
+# v2 — 需要两步
+spc download --for-extensions=curl,gd
+spc build curl,gd --build-cli
+
+# v3 — 一步即可
+spc build:php-cli curl,gd
+```
+
+如需跳过自动下载（例如在 CI 中源码已预先缓存），可传入 `--no-download`：
+
+```bash
+spc build:php-cli curl,gd --no-download
+```
+
+## `download` 命令选项变化
+
+| v2 | v3 | 说明 |
+|---|---|---|
+| `--prefer-pre-built` | `--prefer-binary` / `-p` | 弃用别名保留 |
+| `--with-libs` | `--for-libs` | 与包过滤分开 |
+| *（无等价）* | `--for-packages` | 统一包过滤器 |
+| *（无等价）* | `--parallel` / `-P` | 并行下载 |
+| *（无等价）* | `--retry` / `-R` | 失败重试 |
+
+## 已移除的 dev 命令
+
+以下开发辅助命令已被移除或合并：
+
+| v2 命令 | v3 替代方案 |
+|---|---|
+| `dev:extensions` / `list-ext` | `spc dev:info <package>` |
+| `dev:ext-version` / `dev:ext-ver` | `spc dev:info <package>` |
+| `dev:lib-version` / `dev:lib-ver` | `spc dev:info <package>` |
+| `dev:php-version` / `dev:php-ver` | `spc dev:info php-src` |
+| `dev:gen-ext-dep-docs` + `dev:gen-lib-dep-docs` | `spc dev:gen-deps-data` |
+
+## 已重命名的 dev 命令
+
+| v2 | v3 | 说明 |
+|---|---|---|
+| `dev:sort-config` / `sort-config` | `dev:lint-config` | 旧别名仍可用 |
+
+## v3 新增命令
+
+以下命令为 v3 新增，v2 中没有对应命令：
+
+| 命令 | 说明 |
+|---|---|
+| `spc reset` | 清理 `buildroot/` 和 `source/` 目录 |
+| `spc check-update` | 检查 artifact 的最新版本 |
+| `spc build:php-cli` | 构建 CLI SAPI（无需标志） |
+| `spc build:php-fpm` | 构建 PHP-FPM（无需标志） |
+| `spc build:php-cgi` | 构建 PHP CGI（无需标志） |
+| `spc build:php-micro` | 构建 phpmicro（无需标志） |
+| `spc build:php-embed` | 构建 embed SAPI（无需标志） |
+| `spc build:frankenphp` | 构建 FrankenPHP（无需标志） |
+| `spc dev:shell` | 进入带构建环境的交互式 shell |
+| `spc dev:is-installed` | 检查某个包是否已正确安装 |
+| `spc dev:dump-stages` | 将所有包的构建阶段导出为 JSON |
+| `spc dev:dump-capabilities` | 导出包的可构建/可安装能力 |
+| `spc dev:info` | 显示某个包的配置信息 |
+
+## `craft.yml` 变化
+
+### 已移除：`build-options.with-added-patch`
+
+`build-options` 下的 `with-added-patch` 键不再被解析，将被静默忽略。请从你的 `craft.yml` 中移除它：
+
+```yaml
+# v2 — 请删除此块
+build-options:
+  with-added-patch:
+    - my-patch.php
+```
+
+### `libs` → `packages`（两者均可用）
+
+顶层 `libs` 字段仍然有效。v3 中推荐使用 `packages`，它是 `libs` 的超集，还涵盖其他工具类包：
+
+```yaml
+# v2
+libs: nghttp2,liblz4
+
+# v3（推荐）
+packages: nghttp2,liblz4
+```
+
+## `env.ini` 变量重命名
+
+如果你在 `config/env.ini` 中进行了自定义，或在 CI 中导出了环境变量，请更新以下变量名：
+
+| v2 变量名 | v3 变量名 |
+|---|---|
+| `SPC_LINUX_DEFAULT_CC` | `SPC_DEFAULT_CC` |
+| `SPC_LINUX_DEFAULT_CXX` | `SPC_DEFAULT_CXX` |
+| `SPC_LINUX_DEFAULT_AR` | `SPC_DEFAULT_AR` |
+| `SPC_LINUX_DEFAULT_LD` | `SPC_DEFAULT_LD` |
+| `SPC_LIBC` | `SPC_TARGET` |
+
+`SPC_TARGET` 使用新的格式，将架构与 libc 编码在一个字符串中，例如：
+
+| v2 | v3 |
+|---|---|
+| `SPC_LIBC=musl` | `SPC_TARGET=x86_64-linux-musl` |
+| `SPC_LIBC=gnu` | `SPC_TARGET=x86_64-linux-gnu.2.17` |
+
+v3 还新增了若干日志相关变量（`SPC_ENABLE_LOG_FILE`、`SPC_LOGS_DIR`、`SPC_PRESERVE_LOGS`）。详情参见[环境变量](/zh/guide/env-vars)。

package.json

@@ -1,6 +1,6 @@
 {
   "scripts": {
-    "docs:dev": "vitepress dev docs",
+    "docs:dev": "node docs/.vitepress/gen-meta.js && vitepress dev docs",
     "docs:gen-meta": "node docs/.vitepress/gen-meta.js",
     "docs:build": "npm run docs:gen-meta && vitepress build docs",
     "docs:preview": "vitepress preview docs"

src/Package/Artifact/go_win.php

@@ -15,21 +15,36 @@ use StaticPHP\Util\GlobalEnvManager;
 
 class go_win
 {
+    /** GOROOT for the Windows Go toolchain. */
+    public static function path(): string
+    {
+        return PKG_ROOT_PATH . '/go-win';
+    }
+
+    /** Path to a binary inside go-win's bin/ (go.exe, gofmt.exe, …). */
+    public static function binary(string $name = 'go.exe'): string
+    {
+        return self::path() . '/bin/' . $name;
+    }
+
+    public static function isInstalled(): bool
+    {
+        return is_file(self::binary());
+    }
+
     #[CustomBinary('go-win', [
         'windows-x86_64',
     ])]
     public function downBinary(ArtifactDownloader $downloader): DownloadResult
     {
-        $pkgroot = PKG_ROOT_PATH;
-
         // get version
-        [$version] = explode("\n", default_shell()->executeCurl('https://go.dev/VERSION?m=text') ?: '');
+        [$version] = explode("\n", default_shell()->executeCurl('https://go.dev/VERSION?m=text', retries: $downloader->getRetry()) ?: '');
         if ($version === '') {
             throw new DownloaderException('Failed to get latest Go version from https://go.dev/VERSION?m=text');
         }
 
         // find SHA256 hash from download page
-        $page = default_shell()->executeCurl('https://go.dev/dl/');
+        $page = default_shell()->executeCurl('https://go.dev/dl/', retries: $downloader->getRetry());
         if ($page === '' || $page === false) {
             throw new DownloaderException('Failed to get Go download page from https://go.dev/dl/');
         }
@@ -52,7 +67,7 @@ class go_win
             throw new DownloaderException("Hash mismatch for downloaded go-win binary. Expected {$hash}, got {$file_hash}");
         }
 
-        return DownloadResult::archive(basename($path), ['url' => $url, 'version' => $version], extract: "{$pkgroot}/go-win", verified: true, version: $version);
+        return DownloadResult::archive(basename($path), ['url' => $url, 'version' => $version], extract: '{pkg_root_path}/go-win', verified: true, version: $version);
     }
 
     #[CustomBinaryCheckUpdate('go-win', ['windows-x86_64'])]

src/Package/Artifact/go_xcaddy.php

@@ -17,6 +17,23 @@ use StaticPHP\Util\System\LinuxUtil;
 
 class go_xcaddy
 {
+    /** GOROOT for the bundled Go toolchain used to build xcaddy. */
+    public static function path(): string
+    {
+        return PKG_ROOT_PATH . '/go-xcaddy';
+    }
+
+    /** Path to a binary inside go-xcaddy's bin/ (xcaddy, go, …). */
+    public static function binary(string $name = 'xcaddy'): string
+    {
+        return self::path() . '/bin/' . $name;
+    }
+
+    public static function isInstalled(): bool
+    {
+        return is_file(self::binary());
+    }
+
     #[CustomBinary('go-xcaddy', [
         'linux-x86_64',
         'linux-aarch64',
@@ -39,11 +56,11 @@ class go_xcaddy
         };
 
         // get version and hash
-        [$version] = explode("\n", default_shell()->executeCurl('https://go.dev/VERSION?m=text') ?: '');
+        [$version] = explode("\n", default_shell()->executeCurl('https://go.dev/VERSION?m=text', retries: $downloader->getRetry()) ?: '');
         if ($version === '') {
             throw new DownloaderException('Failed to get latest Go version from https://go.dev/VERSION?m=text');
         }
-        $page = default_shell()->executeCurl('https://go.dev/dl/');
+        $page = default_shell()->executeCurl('https://go.dev/dl/', retries: $downloader->getRetry());
         if ($page === '' || $page === false) {
             throw new DownloaderException('Failed to get Go download page from https://go.dev/dl/');
         }

src/Package/Artifact/rust.php

@@ -16,6 +16,23 @@ use StaticPHP\Util\System\LinuxUtil;
 
 class rust
 {
+    /** Install prefix the rust tarball's install.sh writes into. */
+    public static function path(): string
+    {
+        return PKG_ROOT_PATH . '/rust';
+    }
+
+    /** Path to a binary inside the rust install dir (cargo, rustc, rustup, …). */
+    public static function binary(string $name = 'cargo'): string
+    {
+        return self::path() . '/bin/' . $name;
+    }
+
+    public static function isInstalled(): bool
+    {
+        return is_file(self::binary());
+    }
+
     #[CustomBinary('rust', [
         'linux-x86_64',
         'linux-aarch64',
@@ -46,7 +63,7 @@ class rust
         $download_url = "https://static.rust-lang.org/dist/rust-{$latest_version}-{$arch}-unknown-linux-{$distro}.tar.xz";
         $path = DOWNLOAD_PATH . DIRECTORY_SEPARATOR . basename($download_url);
         default_shell()->executeCurlDownload($download_url, $path, retries: $downloader->getRetry());
-        return DownloadResult::archive(basename($path), ['url' => $download_url, 'version' => $latest_version], extract: PKG_ROOT_PATH . '/rust-install', verified: false, version: $latest_version);
+        return DownloadResult::archive(basename($path), ['url' => $download_url, 'version' => $latest_version], extract: '{pkg_root_path}/rust-install', verified: false, version: $latest_version);
     }
 
     #[CustomBinaryCheckUpdate('rust', [

src/Package/Artifact/zig.php

@@ -15,6 +15,23 @@ use StaticPHP\Runtime\SystemTarget;
 
 class zig
 {
+    /** Directory zig extracts into. */
+    public static function path(): string
+    {
+        return PKG_ROOT_PATH . '/zig';
+    }
+
+    /** Path to a binary inside the zig install dir (zig, zig-cc, zig-c++, zig-ar, …). */
+    public static function binary(string $name = 'zig'): string
+    {
+        return self::path() . '/' . $name;
+    }
+
+    public static function isInstalled(): bool
+    {
+        return is_file(self::binary());
+    }
+
     #[CustomBinary('zig', [
         'linux-x86_64',
         'linux-aarch64',

src/Package/Extension/clickhouse.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Package\Extension;
+
+use StaticPHP\Attribute\Package\CustomPhpConfigureArg;
+use StaticPHP\Attribute\Package\Extension;
+use StaticPHP\Package\PackageInstaller;
+use StaticPHP\Package\PhpExtensionPackage;
+
+#[Extension('clickhouse')]
+class clickhouse extends PhpExtensionPackage
+{
+    #[CustomPhpConfigureArg('Darwin')]
+    #[CustomPhpConfigureArg('Linux')]
+    public function getUnixConfigureArg(bool $shared, PackageInstaller $installer): string
+    {
+        $arg = '--enable-clickhouse' . ($shared ? '=shared' : '');
+        if ($installer->getLibraryPackage('openssl')) {
+            $arg .= ' --enable-clickhouse-openssl';
+        }
+        return $arg;
+    }
+}

src/Package/Extension/decimal.php

@@ -22,8 +22,14 @@ class decimal extends PhpExtensionPackage
     {
         FileSystem::replaceFileStr(
             $this->getSourceDir() . '/php_decimal.c',
-            'zend_module_entry decimal_module_entry',
-            'zend_module_entry php_decimal_module_entry'
+            [
+                'zend_module_entry decimal_module_entry',
+                'ZEND_GET_MODULE(decimal)',
+            ],
+            [
+                'zend_module_entry php_decimal_module_entry',
+                'ZEND_GET_MODULE(php_decimal)',
+            ]
         );
     }
 

src/Package/Extension/imap.php

@@ -9,6 +9,7 @@ use StaticPHP\Attribute\Package\BeforeStage;
 use StaticPHP\Attribute\Package\CustomPhpConfigureArg;
 use StaticPHP\Attribute\Package\Extension;
 use StaticPHP\Attribute\Package\Validate;
+use StaticPHP\Attribute\PatchDescription;
 use StaticPHP\Exception\WrongUsageException;
 use StaticPHP\Package\PackageBuilder;
 use StaticPHP\Package\PackageInstaller;
@@ -26,6 +27,19 @@ class imap extends PhpExtensionPackage
         }
     }
 
+    #[BeforeStage('php', [php::class, 'makeCliForUnix'], 'ext-imap')]
+    #[PatchDescription('Fix imap zend_zval_value_name() call for PHP 8.2 compatibility')]
+    public function patchBeforeMake(): void
+    {
+        // zend_zval_value_name() was introduced in PHP 8.3; PHP 8.2 imap backported the call but not the declaration
+        // replace with the equivalent PHP 8.2-compatible function
+        FileSystem::replaceFileStr(
+            "{$this->getSourceDir()}/php_imap.c",
+            'zend_zval_value_name(data)',
+            'zend_zval_type_name(data)'
+        );
+    }
+
     #[BeforeStage('php', [php::class, 'buildconfForUnix'], 'ext-imap')]
     public function patchBeforeBuildconf(PackageInstaller $installer): void
     {

src/Package/Extension/intl.php

@@ -16,7 +16,7 @@ use StaticPHP\Util\FileSystem;
 class intl extends PhpExtensionPackage
 {
     #[BeforeStage('php', [php::class, 'buildconfForWindows'], 'ext-intl')]
-    #[PatchDescription('Fix intl config.w32: replace hardcoded true with PHP_INTL_SHARED for static build support')]
+    #[PatchDescription('Fix intl config.w32: replace hardcoded true with PHP_INTL_SHARED for static build support; add /std:c++17 required by ICU 73+')]
     public function patchBeforeBuildconfForWindows(PackageInstaller $installer): void
     {
         $php_src = $installer->getTargetPackage('php')->getSourceDir();
@@ -25,5 +25,11 @@ class intl extends PhpExtensionPackage
             'EXTENSION("intl", "php_intl.c intl_convert.c intl_convertcpp.cpp intl_error.c ", true,',
             'EXTENSION("intl", "php_intl.c intl_convert.c intl_convertcpp.cpp intl_error.c ", PHP_INTL_SHARED,'
         );
+        // ICU 73+ headers (char16ptr.h etc.) unconditionally include <string_view> which requires C++17.
+        FileSystem::replaceFileStr(
+            "{$php_src}/ext/intl/config.w32",
+            'ADD_FLAG("CFLAGS_INTL", "/EHsc',
+            'ADD_FLAG("CFLAGS_INTL", "/std:c++17 /EHsc'
+        );
     }
 }

src/Package/Extension/memcache.php

@@ -17,6 +17,20 @@ class memcache extends PhpExtensionPackage
     #[BeforeStage('php', [php::class, 'buildconfForUnix'], 'ext-memcache')]
     public function patchBeforeBuildconf(): bool
     {
+        // PHP 8.5 moved php_smart_string*.h from ext/standard/ to Zend/
+        foreach (['src/memcache_pool.h', 'src/memcache_pool.c', 'src/memcache_session.c', 'src/memcache_ascii_protocol.c', 'src/memcache_binary_protocol.c'] as $file) {
+            FileSystem::replaceFileStr(
+                "{$this->getSourceDir()}/{$file}",
+                '#include "ext/standard/php_smart_string_public.h"',
+                '#include "Zend/zend_smart_string_public.h"',
+            );
+            FileSystem::replaceFileStr(
+                "{$this->getSourceDir()}/{$file}",
+                '#include "ext/standard/php_smart_string.h"',
+                '#include "Zend/zend_smart_string.h"',
+            );
+        }
+
         if (!$this->isBuildStatic()) {
             return false;
         }

src/Package/Extension/mongodb.php

@@ -8,6 +8,7 @@ use Package\Target\php;
 use StaticPHP\Attribute\Package\BeforeStage;
 use StaticPHP\Attribute\Package\CustomPhpConfigureArg;
 use StaticPHP\Attribute\Package\Extension;
+use StaticPHP\Attribute\PatchDescription;
 use StaticPHP\Package\PackageInstaller;
 use StaticPHP\Package\PhpExtensionPackage;
 use StaticPHP\Util\FileSystem;
@@ -15,7 +16,16 @@ use StaticPHP\Util\FileSystem;
 #[Extension('mongodb')]
 class mongodb extends PhpExtensionPackage
 {
+    #[BeforeStage('php', [php::class, 'configureForUnix'], 'ext-mongodb')]
+    #[PatchDescription('Export PHP_VERSION_ID so mongo-php-driver >= 2.3.3 skips its php-config lookup (in-tree builds have no php-config).')]
+    public function exportPhpVersionIdForUnix(): void
+    {
+        $id = php::getPHPVersionID();
+        f_putenv("PHP_VERSION_ID={$id}");
+    }
+
     #[BeforeStage('php', [php::class, 'buildconfForWindows'], 'ext-mongodb')]
+    #[PatchDescription('Add /utf-8 flag to CFLAGS_MONGODB for Windows build to fix compilation error on non-English Windows.')]
     public function patchBeforeBuild(): void
     {
         FileSystem::replaceFileStr(
@@ -25,6 +35,17 @@ class mongodb extends PhpExtensionPackage
         );
     }
 
+    #[BeforeStage('php', [php::class, 'buildconfForUnix'], 'ext-mongodb')]
+    #[PatchDescription('Replace src/libmongoc/ with ${ac_config_dir}/src/libmongoc/ in config.m4 to fix the build on Unix-like systems.')]
+    public function patchBeforeBuildconfUnix(): void
+    {
+        FileSystem::replaceFileRegex(
+            $this->getSourceDir() . '/config.m4',
+            '/^(\s+)(src\/libmongoc\/)/m',
+            '$1${ac_config_dir}/$2'
+        );
+    }
+
     #[CustomPhpConfigureArg('Darwin')]
     #[CustomPhpConfigureArg('Linux')]
     public function getUnixConfigureArg(bool $shared, PackageInstaller $installer): string

src/Package/Extension/opcache.php

@@ -72,6 +72,10 @@ class opcache extends PhpExtensionPackage
         ) {
             $opcache_jit = ' --disable-opcache-jit';
         }
-        return '--enable-opcache' . ($shared ? '=shared' : '') . $opcache_jit;
+        // PHP 8.5+ has opcache built-in
+        if ($phpVersionID < 80500) {
+            return '--enable-opcache' . ($shared ? '=shared' : '') . $opcache_jit;
+        }
+        return trim($opcache_jit);
     }
 }

src/Package/Extension/opentelemetry.php

@@ -7,15 +7,21 @@ namespace Package\Extension;
 use Package\Target\php;
 use StaticPHP\Attribute\Package\BeforeStage;
 use StaticPHP\Attribute\Package\Extension;
+use StaticPHP\Toolchain\Interface\ToolchainInterface;
+use StaticPHP\Toolchain\ZigToolchain;
 use StaticPHP\Util\GlobalEnvManager;
 
 #[Extension('opentelemetry')]
 class opentelemetry
 {
     #[BeforeStage('php', [php::class, 'makeForUnix'], 'ext-opentelemetry')]
-    public function patchBeforeMake(): void
+    public function patchBeforeMake(ToolchainInterface $toolchain): void
     {
-        // add -Wno-strict-prototypes
-        GlobalEnvManager::putenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS=' . getenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS') . ' -Wno-strict-prototypes');
+        $extra_cflags = getenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS') ?: '';
+        $extra_cflags .= ' -Wno-strict-prototypes';
+        if ($toolchain instanceof ZigToolchain) {
+            $extra_cflags .= ' -Wno-unknown-warning-option';
+        }
+        GlobalEnvManager::putenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS=' . trim($extra_cflags));
     }
 }

src/Package/Extension/password_argon2.php

@@ -27,7 +27,7 @@ class password_argon2 extends PhpExtensionPackage
     #[CustomPhpConfigureArg('Darwin')]
     public function getConfigureArg(PackageInstaller $installer, PackageBuilder $builder): string
     {
-        if ($installer->getLibraryPackage('openssl') !== null) {
+        if ($installer->getPhpExtensionPackage('openssl')?->isBuildStatic()) {
             if (php::getPHPVersionID() >= 80500 || (php::getPHPVersionID() >= 80400 && !$builder->getOption('enable-zts'))) {
                 return '--without-password-argon2'; // use --with-openssl-argon2 in openssl extension instead
             }

src/Package/Extension/pgsql.php

@@ -20,7 +20,7 @@ class pgsql extends PhpExtensionPackage
     public function getUnixConfigureArg(bool $shared, PackageBuilder $builder, PackageInstaller $installer): string
     {
         if (php::getPHPVersionID() >= 80400) {
-            $libfiles = new SPCConfigUtil(['libs_only_deps' => true, 'absolute_libs' => true])->getPackageDepsConfig('postgresql', array_keys($installer->getResolvedPackages()), $builder->getOption('with-suggests'))['libs'];
+            $libfiles = new SPCConfigUtil(['libs_only_deps' => true, 'absolute_libs' => true])->getPackageDepsConfig('postgresql', array_keys($installer->getResolvedPackages()))['libs'];
             $libfiles = str_replace("{$builder->getLibDir()}/lib", '-l', $libfiles);
             $libfiles = str_replace('.a', '', $libfiles);
             return '--with-pgsql' . ($shared ? '=shared' : '') .

src/Package/Extension/spx.php

@@ -6,14 +6,27 @@ namespace Package\Extension;
 
 use Package\Target\php;
 use StaticPHP\Attribute\Package\BeforeStage;
+use StaticPHP\Attribute\Package\CustomPhpConfigureArg;
 use StaticPHP\Attribute\Package\Extension;
 use StaticPHP\Attribute\PatchDescription;
+use StaticPHP\Package\PackageInstaller;
 use StaticPHP\Package\PhpExtensionPackage;
 use StaticPHP\Util\FileSystem;
 
 #[Extension('spx')]
 class spx extends PhpExtensionPackage
 {
+    #[CustomPhpConfigureArg('Linux')]
+    #[CustomPhpConfigureArg('Darwin')]
+    public function getUnixConfigureArg(bool $shared, PackageInstaller $installer): string
+    {
+        $arg = '--enable-SPX' . ($shared ? '=shared' : '');
+        if ($installer->getLibraryPackage('zlib') !== null) {
+            $arg .= ' --with-zlib-dir=' . BUILD_ROOT_PATH;
+        }
+        return $arg;
+    }
+
     #[BeforeStage('php', [php::class, 'buildconfForUnix'], 'ext-spx')]
     #[PatchDescription('Fix spx extension compile error when building as static')]
     public function patchBeforeBuildconf(): bool

src/Package/Extension/swow.php

@@ -20,7 +20,7 @@ class swow extends PhpExtensionPackage
     #[CustomPhpConfigureArg('Windows')]
     public function configureArg(PackageInstaller $installer): string
     {
-        $arg = '--enable-swow';
+        $arg = '--enable-swow --disable-swow-pdo-pgsql';
         $arg .= $installer->getLibraryPackage('openssl') ? ' --enable-swow-ssl' : ' --disable-swow-ssl';
         $arg .= $installer->getLibraryPackage('curl') ? ' --enable-swow-curl' : ' --disable-swow-curl';
         return $arg;

src/Package/Extension/xlswriter.php

@@ -11,7 +11,6 @@ use StaticPHP\Attribute\Package\Extension;
 use StaticPHP\Attribute\PatchDescription;
 use StaticPHP\Package\PackageInstaller;
 use StaticPHP\Package\PhpExtensionPackage;
-use StaticPHP\Util\GlobalEnvManager;
 use StaticPHP\Util\SourcePatcher;
 
 #[Extension('xlswriter')]
@@ -21,20 +20,14 @@ class xlswriter extends PhpExtensionPackage
     #[CustomPhpConfigureArg('Linux')]
     public function getUnixConfigureArg(bool $shared, PackageInstaller $installer): string
     {
-        $arg = '--with-xlswriter --enable-reader';
+        $shared = $shared ? '=shared' : '';
+        $arg = "--with-xlswriter{$shared} --enable-reader";
         if ($installer->getLibraryPackage('openssl')) {
             $arg .= ' --with-openssl=' . $installer->getLibraryPackage('openssl')->getBuildRootPath();
         }
         return $arg;
     }
 
-    #[BeforeStage('php', [php::class, 'makeForUnix'], 'ext-xlswriter')]
-    #[PatchDescription('Fix Unix build: add -std=gnu17 to CFLAGS to fix build errors on older GCC versions')]
-    public function patchBeforeUnixMake(): void
-    {
-        GlobalEnvManager::putenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS=' . getenv('SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS') . ' -std=gnu17');
-    }
-
     #[BeforeStage('php', [php::class, 'makeForWindows'], 'ext-xlswriter')]
     #[PatchDescription('Fix Windows build: apply win32 patch and add UTF-8 BOM to theme.c')]
     public function patchBeforeMakeForWindows(): void
@@ -47,11 +40,4 @@ class xlswriter extends PhpExtensionPackage
             file_put_contents($this->getSourceDir() . '/library/libxlsxwriter/src/theme.c', $bom . $content);
         }
     }
-
-    public function getSharedExtensionEnv(): array
-    {
-        $parent = parent::getSharedExtensionEnv();
-        $parent['CFLAGS'] .= ' -std=gnu17';
-        return $parent;
-    }
 }

src/Package/Extension/zlib.php

@@ -8,15 +8,16 @@ use Package\Target\php;
 use StaticPHP\Attribute\Package\CustomPhpConfigureArg;
 use StaticPHP\Attribute\Package\Extension;
 use StaticPHP\Package\PackageBuilder;
+use StaticPHP\Package\PackageInstaller;
 
 #[Extension('zlib')]
 class zlib
 {
     #[CustomPhpConfigureArg('Darwin')]
     #[CustomPhpConfigureArg('Linux')]
-    public function unixConfigureArg(PackageBuilder $builder): string
+    public function unixConfigureArg(PackageBuilder $builder, PackageInstaller $installer): string
     {
-        $zlib_dir = php::getPHPVersionID() >= 80400 ? '' : ' --with-zlib-dir=' . $builder->getBuildRootPath();
-        return '--with-zlib' . $zlib_dir;
+        $zlib_dir = (php::getPHPVersionID() >= 80400 && !$installer->getPhpExtensionPackage('spx')) ? '' : " --with-zlib-dir={$builder->getBuildRootPath()}";
+        return "--with-zlib{$zlib_dir}";
     }
 }

src/Package/Library/imagemagick.php

@@ -19,10 +19,10 @@ class imagemagick
     #[BuildFor('Linux')]
     public function buildUnix(LibraryPackage $lib, ToolchainInterface $toolchain): void
     {
-        $ldflags = $original_ldflags = getenv('SPC_DEFAULT_LD_FLAGS');
+        $ldflags = $original_ldflags = getenv('SPC_DEFAULT_LDFLAGS');
         if (str_contains($ldflags, '-Wl,--as-needed')) {
             $ldflags = str_replace('-Wl,--as-needed', '', $ldflags);
-            f_putenv("SPC_DEFAULT_LD_FLAGS={$ldflags}");
+            f_putenv("SPC_DEFAULT_LDFLAGS={$ldflags}");
         }
 
         $ac = UnixAutoconfExecutor::create($lib)
@@ -42,6 +42,9 @@ class imagemagick
             ->addConfigureArgs(
                 '--disable-openmp',
                 '--without-x',
+                // implicit --with-gcc-arch
+                // bleeds host cpu features into built binaries
+                '--without-gcc-arch',
             );
 
         // special: linux-static target needs `-static`
@@ -58,7 +61,7 @@ class imagemagick
 
         $ac->configure()->make();
 
-        f_putenv("SPC_DEFAULT_LD_FLAGS={$original_ldflags}");
+        f_putenv("SPC_DEFAULT_LDFLAGS={$original_ldflags}");
 
         $filelist = [
             'ImageMagick.pc',

src/Package/Library/krb5.php

@@ -10,6 +10,8 @@ use StaticPHP\Package\LibraryPackage;
 use StaticPHP\Package\PackageInstaller;
 use StaticPHP\Runtime\Executor\UnixAutoconfExecutor;
 use StaticPHP\Runtime\SystemTarget;
+use StaticPHP\Toolchain\Interface\ToolchainInterface;
+use StaticPHP\Toolchain\ZigToolchain;
 use StaticPHP\Util\SPCConfigUtil;
 
 #[Library('krb5')]
@@ -17,7 +19,7 @@ class krb5
 {
     #[BuildFor('Linux')]
     #[BuildFor('Darwin')]
-    public function build(LibraryPackage $lib, PackageInstaller $installer): void
+    public function build(LibraryPackage $lib, PackageInstaller $installer, ToolchainInterface $toolchain): void
     {
         if (!file_exists($lib->getSourceRoot() . '/configure')) {
             shell()->cd($lib->getSourceRoot())->exec('autoreconf -if');
@@ -45,12 +47,15 @@ class krb5
             $extraEnv['LDFLAGS'] = '-framework Kerberos';
             $args[] = 'ac_cv_func_secure_getenv=no';
         }
-        UnixAutoconfExecutor::create($lib)
+        $executor = UnixAutoconfExecutor::create($lib)
             ->appendEnv($extraEnv)
             ->optionalPackage('ldap', '--with-ldap', '--without-ldap')
             ->optionalPackage('libedit', '--with-libedit', '--without-libedit')
-            ->configure(...$args)
-            ->make();
+            ->configure(...$args);
+        if ($toolchain instanceof ZigToolchain) {
+            $executor->exec('find . -name Makefile -exec sed -i "s/-Werror=incompatible-pointer-types//g" {} +');
+        }
+        $executor->make();
         $lib->patchPkgconfPrefix([
             'krb5-gssapi.pc',
             'krb5.pc',

src/Package/Library/libde265.php

@@ -17,7 +17,11 @@ class libde265 extends LibraryPackage
     public function buildUnix(): void
     {
         UnixCMakeExecutor::create($this)
-            ->addConfigureArgs('-DENABLE_SDL=OFF')
+            ->addConfigureArgs(
+                '-DENABLE_SDL=OFF',
+                '-DENABLE_DECODER=OFF',
+                '-DHAVE_NEON=OFF',
+            )
             ->build();
         $this->patchPkgconfPrefix(['libde265.pc']);
     }

src/Package/Library/libevent.php

@@ -57,7 +57,6 @@ class libevent
             ->addConfigureArgs(
                 '-DEVENT__LIBRARY_TYPE=STATIC',
                 '-DEVENT__DISABLE_BENCHMARK=ON',
-                '-DEVENT__DISABLE_THREAD_SUPPORT=ON',
                 '-DEVENT__DISABLE_TESTS=ON',
                 '-DEVENT__DISABLE_SAMPLES=ON',
                 '-DEVENT__DISABLE_MBEDTLS=ON ',
@@ -67,7 +66,7 @@ class libevent
         }
         $cmake->build();
 
-        $lib->patchPkgconfPrefix(['libevent.pc', 'libevent_core.pc', 'libevent_extra.pc', 'libevent_openssl.pc']);
+        $lib->patchPkgconfPrefix(['libevent.pc', 'libevent_core.pc', 'libevent_extra.pc', 'libevent_openssl.pc', 'libevent_pthreads.pc']);
 
         $lib->patchPkgconfPrefix(
             ['libevent_openssl.pc'],