string interpolation

Co-authored-by: Hendrik Mennen <hmennen@gambio.ec1.de>

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2
+
+[*.{yml,yaml,vue,ts}]
+indent_size = 2

.github/FUNDING.yml

@@ -1,9 +1,9 @@
 # These are supported funding model platforms
 
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+github: [crazywhalecc]# Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
+# ko_fi: crazywhalecc # Replace with a single Ko-fi username
 tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
 community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
 liberapay: # Replace with a single Liberapay username
@@ -11,5 +11,5 @@ issuehunt: # Replace with a single IssueHunt username
 otechie: # Replace with a single Otechie username
 lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
 # noinspection YAMLSchemaValidation
-buy_me_a_coffee: crazywhalecc
+buy_me_a_coffee: # crazywhalecc
 custom: 'https://github.com/crazywhalecc/crazywhalecc/blob/master/FUNDING.md' # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: Build PHP or library failed, download failed, doesn't seem to work...
+title: ''
+labels: bug
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: |
+        Please tell us what you do, what you get and what you expected.
+        Provide with some step-by-step instructions to reproduce the issue.
+        If possible, attach a screenshot or log files in ./log directory.
+    validations:
+      required: true
+---

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,8 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: new feature
+assignees: crazywhalecc
+
+---

.github/ISSUE_TEMPLATE/something-want-to-know.md

@@ -0,0 +1,10 @@
+---
+name: Something want to know
+about: Describe your question about static-php, we will reply ASAP
+title: ''
+labels: question
+assignees: ''
+
+---
+
+

.github/pull_request_template.md

@@ -7,6 +7,11 @@
 > 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 it's a extension or dependency update, make sure adding related extensions in `src/global/test-extensions.php`.
-- [ ] If you changed the behavior of static-php-cli, add docs in [static-php/static-php-cli-docs](https://github.com/static-php/static-php-cli-docs) .
-- [ ] If you updated `config/xxxx.json` content, run `bin/spc dev:sort-config xxx`.
+- If you modified `*.php` or `*.json`, 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.

.github/workflows/build-linux-arm.yml

@@ -1,107 +0,0 @@
-name: CI on arm linux
-
-on:
-  workflow_dispatch:
-    inputs:
-      operating-system:
-        required: true
-        description: Compile target arch (Linux only)
-        type: choice
-        options:
-          - aarch64
-      version:
-        required: true
-        description: php version to compile
-        default: '8.2'
-        type: choice
-        options:
-          - '8.3'
-          - '8.2'
-          - '8.1'
-          - '8.0'
-          - '7.4'
-      build-cli:
-        description: build cli binary
-        default: true
-        type: boolean
-      build-micro:
-        description: build phpmicro binary
-        type: boolean
-      build-fpm:
-        description: build fpm binary
-        type: boolean
-      extensions:
-        description: extensions to compile (comma separated)
-        required: true
-        type: string
-      debug:
-        type: boolean
-
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-jobs:
-  build:
-    name: build ${{ inputs.version }} on ${{ inputs.operating-system }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      # Cache downloaded source
-      - id: cache-download
-        uses: actions/cache@v3
-        with:
-          path: downloads
-          key: php-${{ inputs.version }}-dependencies-${{ inputs.extensions }}
-
-      # With or without debug
-      - if: inputs.debug == true
-        run: echo "SPC_BUILD_DEBUG=--debug" >> $GITHUB_ENV
-
-      # With target select: cli, micro or both
-      - if: ${{ inputs.build-cli == true }}
-        run: echo "SPC_BUILD_CLI=--build-cli" >> $GITHUB_ENV
-      - if: ${{ inputs.build-micro == true }}
-        run: echo "SPC_BUILD_MICRO=--build-micro" >> $GITHUB_ENV
-      - if: ${{ inputs.build-fpm == true }}
-        run: echo "SPC_BUILD_FPM=--build-fpm" >> $GITHUB_ENV
-
-      # If there's no dependencies cache, fetch sources, with or without debug
-      - if: steps.cache-download.outputs.cache-hit != 'true'
-        run: SPC_USE_ARCH=${{ inputs.operating-system }} ./bin/spc-alpine-docker download --with-php=${{ inputs.version }} --for-extensions=${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }}
-
-      # Run build command
-      - run: SPC_USE_ARCH=${{ inputs.operating-system }} ./bin/spc-alpine-docker build ${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_BUILD_CLI }} ${{ env.SPC_BUILD_MICRO }} ${{ env.SPC_BUILD_FPM }}
-
-      # Upload cli executable
-      - if: ${{ inputs.build-cli == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-${{ inputs.version }}-linux-${{ inputs.operating-system }}
-          path: buildroot/bin/php
-
-      # Upload micro self-extracted executable
-      - if: ${{ inputs.build-micro == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: micro-${{ inputs.version }}-linux-${{ inputs.operating-system }}
-          path: buildroot/bin/micro.sfx
-
-      # Upload fpm executable
-      - if: ${{ inputs.build-fpm == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-fpm-${{ inputs.version }}-linux-${{ inputs.operating-system }}
-          path: buildroot/bin/php-fpm
-
-      # Upload extensions metadata
-      - uses: actions/upload-artifact@v3
-        with:
-          name: license-files
-          path: buildroot/license/
-      - uses: actions/upload-artifact@v3
-        with:
-          name: build-meta
-          path: |
-            buildroot/build-extensions.json
-            buildroot/build-libraries.json

.github/workflows/build-macos-aarch64.yml

@@ -1,127 +0,0 @@
-name: CI on arm64 macOS
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        required: true
-        description: php version to compile
-        default: '8.2'
-        type: choice
-        options:
-          - '8.3'
-          - '8.2'
-          - '8.1'
-          - '8.0'
-          - '7.4'
-      build-cli:
-        description: build cli binary
-        default: true
-        type: boolean
-      build-micro:
-        description: build phpmicro binary
-        type: boolean
-      build-fpm:
-        description: build fpm binary
-        type: boolean
-      extensions:
-        description: extensions to compile (comma separated)
-        required: true
-        type: string
-      debug:
-        type: boolean
-
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-jobs:
-  build:
-    name: build ${{ inputs.version }} on macOS arm64
-    runs-on: macos-14
-    steps:
-      - uses: actions/checkout@v3
-
-      # Install macOS missing packages and mark os suffix
-      - run: |
-          brew install automake gzip
-          echo "SPC_BUILD_OS=macos" >> $GITHUB_ENV
-
-      
-      - name: "Setup PHP"
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: 8.1
-          tools: pecl, composer
-          extensions: curl, openssl, mbstring, tokenizer
-          ini-values: memory_limit=-1
-
-
-      # Cache composer dependencies
-      - id: cache-composer-deps
-        uses: actions/cache@v3
-        with:
-          path: vendor
-          key: composer-dependencies
-
-      # If there's no Composer cache, install dependencies
-      - if: steps.cache-composer-deps.outputs.cache-hit != 'true'
-        run: composer update --no-dev --classmap-authoritative
-
-      # Cache downloaded source
-      - id: cache-download
-        uses: actions/cache@v3
-        with:
-          path: downloads
-          key: php-${{ inputs.version }}-dependencies-${{ inputs.extensions }}
-
-      # With or without debug
-      - if: inputs.debug == true
-        run: echo "SPC_BUILD_DEBUG=--debug" >> $GITHUB_ENV
-
-      # With target select: cli, micro or both
-      - if: ${{ inputs.build-cli == true }}
-        run: echo "SPC_BUILD_CLI=--build-cli" >> $GITHUB_ENV
-      - if: ${{ inputs.build-micro == true }}
-        run: echo "SPC_BUILD_MICRO=--build-micro" >> $GITHUB_ENV
-      - if: ${{ inputs.build-fpm == true }}
-        run: echo "SPC_BUILD_FPM=--build-fpm" >> $GITHUB_ENV
-
-      # If there's no dependencies cache, fetch sources, with or without debug
-      - if: steps.cache-download.outputs.cache-hit != 'true'
-        run: ./bin/spc download --with-php=${{ inputs.version }} --for-extensions=${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }}
-
-      # Run build command
-      - run: ./bin/spc build ${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_BUILD_CLI }} ${{ env.SPC_BUILD_MICRO }} ${{ env.SPC_BUILD_FPM }}
-
-      # Upload cli executable
-      - if: ${{ inputs.build-cli == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php
-
-      # Upload micro self-extracted executable
-      - if: ${{ inputs.build-micro == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: micro-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/micro.sfx
-
-      # Upload fpm executable
-      - if: ${{ inputs.build-fpm == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-fpm-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php-fpm
-
-      # Upload extensions metadata
-      - uses: actions/upload-artifact@v3
-        with:
-          name: license-files
-          path: buildroot/license/
-      - uses: actions/upload-artifact@v3
-        with:
-          name: build-meta
-          path: |
-            buildroot/build-extensions.json
-            buildroot/build-libraries.json

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

@@ -1,118 +0,0 @@
-name: CI on x86_64 macOS
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        required: true
-        description: php version to compile
-        default: '8.2'
-        type: choice
-        options:
-          - '8.3'
-          - '8.2'
-          - '8.1'
-          - '8.0'
-          - '7.4'
-      build-cli:
-        description: build cli binary
-        default: true
-        type: boolean
-      build-micro:
-        description: build phpmicro binary
-        type: boolean
-      build-fpm:
-        description: build fpm binary
-        type: boolean
-      extensions:
-        description: extensions to compile (comma separated)
-        required: true
-        type: string
-      debug:
-        type: boolean
-
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-jobs:
-  build:
-    name: build ${{ inputs.version }} on macOS x86_64
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      # Install macOS missing packages and mark os suffix
-      - run: |
-          brew install automake gzip
-          echo "SPC_BUILD_OS=macos" >> $GITHUB_ENV
-
-      # Cache composer dependencies
-      - id: cache-composer-deps
-        uses: actions/cache@v3
-        with:
-          path: vendor
-          key: composer-dependencies
-
-      # If there's no Composer cache, install dependencies
-      - if: steps.cache-composer-deps.outputs.cache-hit != 'true'
-        run: composer update --no-dev --classmap-authoritative
-
-      # Cache downloaded source
-      - id: cache-download
-        uses: actions/cache@v3
-        with:
-          path: downloads
-          key: php-${{ inputs.version }}-dependencies-${{ inputs.extensions }}
-
-      # With or without debug
-      - if: inputs.debug == true
-        run: echo "SPC_BUILD_DEBUG=--debug" >> $GITHUB_ENV
-
-      # With target select: cli, micro or both
-      - if: ${{ inputs.build-cli == true }}
-        run: echo "SPC_BUILD_CLI=--build-cli" >> $GITHUB_ENV
-      - if: ${{ inputs.build-micro == true }}
-        run: echo "SPC_BUILD_MICRO=--build-micro" >> $GITHUB_ENV
-      - if: ${{ inputs.build-fpm == true }}
-        run: echo "SPC_BUILD_FPM=--build-fpm" >> $GITHUB_ENV
-
-      # If there's no dependencies cache, fetch sources, with or without debug
-      - if: steps.cache-download.outputs.cache-hit != 'true'
-        run: ./bin/spc download --with-php=${{ inputs.version }} --for-extensions=${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }}
-
-      # Run build command
-      - run: ./bin/spc build ${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_BUILD_CLI }} ${{ env.SPC_BUILD_MICRO }} ${{ env.SPC_BUILD_FPM }}
-
-      # Upload cli executable
-      - if: ${{ inputs.build-cli == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php
-
-      # Upload micro self-extracted executable
-      - if: ${{ inputs.build-micro == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: micro-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/micro.sfx
-
-      # Upload fpm executable
-      - if: ${{ inputs.build-fpm == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-fpm-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php-fpm
-
-      # Upload extensions metadata
-      - uses: actions/upload-artifact@v3
-        with:
-          name: license-files
-          path: buildroot/license/
-      - uses: actions/upload-artifact@v3
-        with:
-          name: build-meta
-          path: |
-            buildroot/build-extensions.json
-            buildroot/build-libraries.json
-

.github/workflows/build-unix.yml

@@ -0,0 +1,335 @@
+name: "CI on Unix"
+
+on:
+  workflow_dispatch:
+    inputs:
+      os:
+        required: true
+        description: Build target OS
+        default: 'linux-x86_64'
+        type: choice
+        options:
+          - 'linux-x86_64'
+          - 'linux-aarch64'
+          - 'linux-x86_64-glibc'
+          - 'linux-aarch64-glibc'
+          - 'macos-x86_64'
+          - 'macos-aarch64'
+      php-version:
+        required: true
+        description: PHP version to compile
+        default: '8.4'
+        type: choice
+        options:
+          - '8.4'
+          - '8.3'
+          - '8.2'
+          - '8.1'
+      extensions:
+        description: Extensions to build (comma separated)
+        required: true
+        type: string
+      shared-extensions:
+        description: Shared extensions to build (optional, comma separated)
+        type: string
+      extra-libs:
+        description: Extra libraries to build (optional, comma separated)
+        type: string
+      build-cli:
+        description: Build cli binary
+        default: true
+        type: boolean
+      build-micro:
+        description: Build phpmicro binary
+        type: boolean
+      build-fpm:
+        description: Build fpm binary
+        type: boolean
+      build-frankenphp:
+        description: Build frankenphp binary (requires ZTS)
+        type: boolean
+        default: false
+      enable-zts:
+        description: Enable ZTS
+        type: boolean
+        default: false
+      prefer-pre-built:
+        description: Prefer pre-built binaries (reduce build time)
+        type: boolean
+        default: true
+      with-suggested-libs:
+        description: Build with suggested libs
+        type: boolean
+        default: false
+      debug:
+        description: Show full build logs
+        type: boolean
+      no-strip:
+        description: Keep debug symbols for debugging
+        type: boolean
+        default: false
+  workflow_call:
+    inputs:
+      os:
+        required: true
+        description: Build target OS
+        default: 'linux-x86_64'
+        type: string
+      php-version:
+        required: true
+        description: PHP version to compile
+        default: '8.4'
+        type: string
+      extensions:
+        description: Extensions to build (comma separated)
+        required: true
+        type: string
+      shared-extensions:
+        description: Shared extensions to build (optional, comma separated)
+        type: string
+      extra-libs:
+        description: Extra libraries to build (optional, comma separated)
+        type: string
+      build-cli:
+        description: Build cli binary
+        default: true
+        type: boolean
+      build-micro:
+        description: Build phpmicro binary
+        type: boolean
+      build-fpm:
+        description: Build fpm binary
+        type: boolean
+      build-frankenphp:
+        description: Build frankenphp binary (requires ZTS)
+        type: boolean
+        default: false
+      enable-zts:
+        description: Enable ZTS
+        type: boolean
+        default: false
+      prefer-pre-built:
+        description: Prefer pre-built binaries (reduce build time)
+        type: boolean
+        default: true
+      with-suggested-libs:
+        description: Include suggested libs
+        type: boolean
+        default: false
+      debug:
+        description: Show full build logs
+        type: boolean
+      no-strip:
+        description: Keep debug symbols for debugging
+        type: boolean
+        default: false
+
+env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  define-build:
+    name: "Define Build Scripts"
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ steps.gendef.outputs.run }}
+      download: ${{ steps.gendef.outputs.download }}
+      build: ${{ steps.gendef.outputs.build }}
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Define"
+        id: gendef
+        run: |
+          case "${{ inputs.os }}" in
+            linux-x86_64)
+              DOWN_CMD="./bin/spc-alpine-docker download"
+              BUILD_CMD="./bin/spc-alpine-docker build"
+              RUNS_ON="ubuntu-latest"
+              ;;
+            linux-aarch64)
+              DOWN_CMD="./bin/spc-alpine-docker download"
+              BUILD_CMD="./bin/spc-alpine-docker build"
+              RUNS_ON="ubuntu-24.04-arm"
+              ;;
+            linux-x86_64-glibc)
+              DOWN_CMD="./bin/spc-gnu-docker download"
+              BUILD_CMD="./bin/spc-gnu-docker build"
+              RUNS_ON="ubuntu-22.04"
+              ;;
+            linux-aarch64-glibc)
+              DOWN_CMD="./bin/spc-gnu-docker download"
+              BUILD_CMD="./bin/spc-gnu-docker build"
+              RUNS_ON="ubuntu-22.04-arm"
+              ;;
+            macos-x86_64)
+              DOWN_CMD="composer update --no-dev --classmap-authoritative && ./bin/spc doctor --auto-fix && ./bin/spc download"
+              BUILD_CMD="./bin/spc build"
+              RUNS_ON="macos-15-intel"
+              ;;
+            macos-aarch64)
+              DOWN_CMD="composer update --no-dev --classmap-authoritative && ./bin/spc doctor --auto-fix && ./bin/spc download"
+              BUILD_CMD="./bin/spc build"
+              RUNS_ON="macos-15"
+              ;;
+          esac
+          STATIC_EXTS="${{ inputs.extensions }}"
+          SHARED_EXTS="${{ inputs['shared-extensions'] }}"
+          BUILD_FRANKENPHP="${{ inputs['build-frankenphp'] }}"
+          ENABLE_ZTS="${{ inputs['enable-zts'] }}"
+          ALL_EXTS="$STATIC_EXTS"
+          if [ -n "$SHARED_EXTS" ]; then
+            ALL_EXTS="$ALL_EXTS,$SHARED_EXTS"
+          fi
+          DOWN_CMD="$DOWN_CMD --with-php=${{ inputs.php-version }} --for-extensions=$ALL_EXTS --ignore-cache-sources=php-src"
+          BUILD_CMD="$BUILD_CMD $STATIC_EXTS"
+          if [ -n "$SHARED_EXTS" ]; then
+            BUILD_CMD="$BUILD_CMD --build-shared=$SHARED_EXTS"
+          fi
+          if [ -n "${{ inputs.extra-libs }}" ]; then
+            DOWN_CMD="$DOWN_CMD --for-libs=${{ inputs.extra-libs }}"
+            BUILD_CMD="$BUILD_CMD --with-libs=${{ inputs.extra-libs }}"
+          fi
+          if [ ${{ inputs.debug }} == true ]; then
+            DOWN_CMD="$DOWN_CMD --debug"
+            BUILD_CMD="$BUILD_CMD --debug"
+          fi
+          if [ ${{ inputs.prefer-pre-built }} == true ]; then
+              DOWN_CMD="$DOWN_CMD --prefer-pre-built"
+          fi
+          if [ ${{ inputs.with-suggested-libs }} == true ]; then
+              BUILD_CMD="$BUILD_CMD --with-suggested-libs"
+          fi
+          if [ ${{ inputs.build-cli }} == true ]; then
+              BUILD_CMD="$BUILD_CMD --build-cli"
+          fi
+          if [ ${{ inputs.build-micro }} == true ]; then
+              BUILD_CMD="$BUILD_CMD --build-micro"
+          fi
+          if [ ${{ inputs.build-fpm }} == true ]; then
+              BUILD_CMD="$BUILD_CMD --build-fpm"
+          fi
+          if [ "$BUILD_FRANKENPHP" = "true" ]; then
+              BUILD_CMD="$BUILD_CMD --build-frankenphp"
+          fi
+          if [ "$ENABLE_ZTS" = "true" ]; then
+              BUILD_CMD="$BUILD_CMD --enable-zts"
+          fi
+          echo 'download='"$DOWN_CMD" >> "$GITHUB_OUTPUT"
+          echo 'build='"$BUILD_CMD" >> "$GITHUB_OUTPUT"
+          echo 'run='"$RUNS_ON" >> "$GITHUB_OUTPUT"
+  build:
+    name: "Build ${{ inputs.version }} on ${{ inputs.os }}"
+    runs-on: ${{ needs.define-build.outputs.run }}
+    needs: define-build
+    timeout-minutes: 240
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Setup PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.4
+          tools: pecl, composer
+          extensions: curl, openssl, mbstring
+          ini-values: memory_limit=-1
+        env:
+          phpts: nts
+
+      - if: ${{ inputs['build-frankenphp'] == true }}
+        name: "Install go-xcaddy for FrankenPHP"
+        run: |
+          case "${{ inputs.os }}" in
+            linux-x86_64|linux-aarch64)
+              ./bin/spc-alpine-docker install-pkg go-xcaddy
+              ;;
+            linux-x86_64-glibc|linux-aarch64-glibc)
+              ./bin/spc-gnu-docker install-pkg go-xcaddy
+              ;;
+            macos-x86_64|macos-aarch64)
+              composer update --no-dev --classmap-authoritative
+              ./bin/spc doctor --auto-fix
+              ./bin/spc install-pkg go-xcaddy
+              ;;
+            *)
+              echo "Unsupported OS for go-xcaddy install: ${{ inputs.os }}"
+              exit 1
+              ;;
+          esac
+
+      # Cache downloaded source
+      - id: cache-download
+        uses: actions/cache@v4
+        with:
+          path: downloads
+          key: php-dependencies-${{ inputs.os }}
+      - name: "Download sources"
+        run: ${{ needs.define-build.outputs.download }}
+      - name: "Build PHP"
+        run: ${{ needs.define-build.outputs.build }}
+#      - name: Setup tmate session
+#        if: ${{ failure() }}
+#        uses: mxschmitt/action-tmate@v3
+
+      # Upload debug logs
+      - if: ${{ inputs.debug && failure() }}
+        name: "Upload build logs on failure"
+        uses: actions/upload-artifact@v4
+        with:
+          name: spc-logs-${{ inputs.php-version }}-${{ inputs.os }}
+          path: log/*.log
+
+      # Upload cli executable
+      - if: ${{ inputs.build-cli == true }}
+        name: "Upload PHP cli SAPI"
+        uses: actions/upload-artifact@v4
+        with:
+          name: php-cli-${{ inputs.php-version }}-${{ inputs.os }}
+          path: buildroot/bin/php
+
+      # Upload micro self-extracted executable
+      - if: ${{ inputs.build-micro == true }}
+        name: "Upload PHP micro SAPI"
+        uses: actions/upload-artifact@v4
+        with:
+          name: php-micro-${{ inputs.php-version }}-${{ inputs.os }}
+          path: buildroot/bin/micro.sfx
+
+      # Upload fpm executable
+      - if: ${{ inputs.build-fpm == true }}
+        name: "Upload PHP fpm SAPI"
+        uses: actions/upload-artifact@v4
+        with:
+          name: php-fpm-${{ inputs.php-version }}-${{ inputs.os }}
+          path: buildroot/bin/php-fpm
+
+      # Upload frankenphp executable
+      - if: ${{ inputs['build-frankenphp'] == true }}
+        name: "Upload FrankenPHP SAPI"
+        uses: actions/upload-artifact@v4
+        with:
+          name: php-frankenphp-${{ inputs.php-version }}-${{ inputs.os }}
+          path: buildroot/bin/frankenphp
+
+      # Upload extensions metadata
+      - if: ${{ inputs['shared-extensions'] != '' }}
+        name: "Upload shared extensions"
+        uses: actions/upload-artifact@v4
+        with:
+          name: php-shared-ext-${{ inputs.php-version }}-${{ inputs.os }}
+          path: |
+            buildroot/modules/*.so
+      - uses: actions/upload-artifact@v4
+        name: "Upload License Files"
+        with:
+          name: license-files-${{ inputs.php-version }}-${{ inputs.os }}
+          path: buildroot/license/
+      - uses: actions/upload-artifact@v4
+        name: "Upload Build Metadata"
+        with:
+          name: build-meta-${{ inputs.php-version }}-${{ inputs.os }}
+          path: |
+            buildroot/build-extensions.json
+            buildroot/build-libraries.json

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

@@ -1,4 +1,4 @@
-name: CI on x86_64 linux
+name: CI on x86_64 Windows
 
 on:
   workflow_dispatch:
@@ -6,14 +6,14 @@ on:
       version:
         required: true
         description: php version to compile
-        default: '8.2'
+        default: '8.4'
         type: choice
         options:
+          - '8.4'
           - '8.3'
           - '8.2'
           - '8.1'
           - '8.0'
-          - '7.4'
       build-cli:
         description: build cli binary
         default: true
@@ -21,14 +21,16 @@ on:
       build-micro:
         description: build phpmicro binary
         type: boolean
-      build-fpm:
-        description: build fpm binary
-        type: boolean
       extensions:
         description: extensions to compile (comma separated)
         required: true
         type: string
+      prefer-pre-built:
+        description: prefer pre-built binaries (reduce build time)
+        type: boolean
+        default: true
       debug:
+        description: enable debug logs
         type: boolean
 
 env:
@@ -36,14 +38,14 @@ env:
 
 jobs:
   build:
-    name: build ${{ inputs.version }} on Linux x86_64
-    runs-on: ubuntu-latest
+    name: build ${{ inputs.version }} on Windows x86_64
+    runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       # Cache composer dependencies
       - id: cache-composer-deps
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: vendor
           key: composer-dependencies
@@ -52,62 +54,62 @@ jobs:
       - if: steps.cache-composer-deps.outputs.cache-hit != 'true'
         run: composer update --no-dev --classmap-authoritative
 
+      - name: Generate hashed key for download cache
+        shell: bash
+        run: |
+          INPUT_HASH=$(echo "${{ runner.os }}-${{ inputs.version }}-${{ inputs.extensions }}" | sha256sum | awk '{print $1}')
+          echo "INPUT_HASH=${INPUT_HASH}" >> "$GITHUB_ENV"
+
       # Cache downloaded source
       - id: cache-download
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: downloads
-          key: php-${{ inputs.version }}-dependencies-${{ inputs.extensions }}
+          key: php-${{ env.INPUT_HASH }}
 
       # With or without debug
       - if: inputs.debug == true
-        run: echo "SPC_BUILD_DEBUG=--debug" >> $GITHUB_ENV
+        run: echo "SPC_BUILD_DEBUG=--debug" >> $env:GITHUB_ENV
+      - if: inputs.prefer-pre-built == true
+        run: echo "SPC_PRE_BUILT=--prefer-pre-built" >> $env:GITHUB_ENV
 
       # With target select: cli, micro or both
       - if: ${{ inputs.build-cli == true }}
-        run: echo "SPC_BUILD_CLI=--build-cli" >> $GITHUB_ENV
+        run: echo "SPC_BUILD_CLI=--build-cli" >> $env:GITHUB_ENV
       - if: ${{ inputs.build-micro == true }}
-        run: echo "SPC_BUILD_MICRO=--build-micro" >> $GITHUB_ENV
-      - if: ${{ inputs.build-fpm == true }}
-        run: echo "SPC_BUILD_FPM=--build-fpm" >> $GITHUB_ENV
+        run: echo "SPC_BUILD_MICRO=--build-micro" >> $env:GITHUB_ENV
+
+      - run: ./bin/spc doctor
 
       # If there's no dependencies cache, fetch sources, with or without debug
       - if: steps.cache-download.outputs.cache-hit != 'true'
-        run: CACHE_API_EXEC=yes ./bin/spc-alpine-docker download --with-php=${{ inputs.version }} --for-extensions=${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }}
+        run: ./bin/spc download --with-php="${{ inputs.version }}" --for-extensions="${{ inputs.extensions }}" ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_PRE_BUILT }}
 
       # Run build command
-      - run: ./bin/spc-alpine-docker build ${{ inputs.extensions }} ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_BUILD_CLI }} ${{ env.SPC_BUILD_MICRO }} ${{ env.SPC_BUILD_FPM }}
+      - run: ./bin/spc build "${{ inputs.extensions }}" ${{ env.SPC_BUILD_DEBUG }} ${{ env.SPC_BUILD_CLI }} ${{ env.SPC_BUILD_MICRO }} ${{ env.SPC_BUILD_FPM }}
 
       # Upload cli executable
       - if: ${{ inputs.build-cli == true }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: php-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php
+          name: php-${{ inputs.version }}
+          path: buildroot/bin/php.exe
 
       # Upload micro self-extracted executable
       - if: ${{ inputs.build-micro == true }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: micro-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
+          name: micro-${{ inputs.version }}
           path: buildroot/bin/micro.sfx
 
-      # Upload fpm executable
-      - if: ${{ inputs.build-fpm == true }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: php-fpm-${{ inputs.version }}-${{ env.SPC_BUILD_OS }}
-          path: buildroot/bin/php-fpm
-
       # Upload extensions metadata
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: license-files
           path: buildroot/license/
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: build-meta
           path: |
             buildroot/build-extensions.json
             buildroot/build-libraries.json
-

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

@@ -0,0 +1,139 @@
+name: "Extension Matrix Tests"
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  test:
+    name: "${{ matrix.extension }} (PHP ${{ matrix.php-version }} on ${{ matrix.operating-system }})"
+    runs-on: ${{ matrix.operating-system }}
+    if: contains(github.event.head_commit.message, 'extension test') || contains(github.event.head_commit.message, 'test extensions')
+    strategy:
+      fail-fast: false
+      matrix:
+        extension:
+          - amqp
+          - apcu
+          - bcmath
+          - bz2
+          - calendar
+          - ctype
+          - curl
+          - dba
+          - dom
+          - ds
+          - event
+          - exif
+          - filter
+          - fileinfo
+          - ftp
+          - gd
+          - gettext
+          - gmp
+          - iconv
+          - igbinary
+          - imagick
+          - imap
+          - intl
+          - ldap
+          - mbstring,mbregex
+          - memcache
+          - mysqli,mysqlnd,pdo_mysql
+          - opcache
+          - openssl
+          - pcntl
+          - password-argon2
+          - pcntl
+          - pdo
+          - pgsql,pdo_pgsql
+          - phar
+          - posix
+          - rar
+          - protobuf
+          - readline
+          - redis
+          - session
+          - shmop
+          - simdjson
+          - simplexml,xml
+          - snappy
+          - soap
+          - sockets
+          - sodium
+          - sqlite3,pdo_sqlite
+          - sqlsrv
+          - ssh2
+          - swoole
+          - swoole,swoole-hook-pgsql,swoole-hook-mysql,swoole-hook-sqlite,swoole-hook-odbc
+          - swow
+          - sysvmsg,sysvsem,sysvshm
+          - tidy
+          - tokenizer
+          - uuid
+          - uv
+          - xhprof
+          - xlswriter
+          - xmlwriter,xmlreader
+          - xsl
+          - yac
+          - yaml
+          - zip
+          - zlib
+          - zstd
+        php-version:
+          - "8.4"
+        operating-system:
+          - "ubuntu-latest"
+          #- "macos-15-intel"
+          #- "debian-arm64-self-hosted"
+          - "macos-15"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+
+      - name: OS type
+        id: os-type
+        run: |
+          OS=""
+          if [ "${{ matrix.operating-system }}" = "ubuntu-latest" ]; then
+              OS="linux-x86_64"
+          elif [ "${{ matrix.operating-system }}" = "macos-15-intel" ]; then
+              OS="macos-x86_64"
+          elif [ "${{ matrix.operating-system }}" = "debian-arm64-self-hosted" ]; then
+              OS="linux-aarch64"
+          elif [ "${{ matrix.operating-system }}" = "macos-15" ]; then
+              OS="macos-aarch64"
+          fi
+          echo "OS=$OS" >> $GITHUB_ENV
+
+      - name: "Setup PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.4
+          tools: pecl, composer
+          extensions: curl, openssl, mbstring
+          ini-values: memory_limit=-1
+        env:
+          phpts: nts
+
+      - name: "Install Dependencies"
+        run: composer update -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - id: cache-download
+        uses: actions/cache@v4
+        with:
+          path: downloads
+          key: php-${{ matrix.php-version }}-dependencies-for-tests
+
+      # If there's no dependencies cache, fetch sources
+      - name: "Download sources"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ./bin/spc download --with-php=${{ matrix.php-version }} --for-extensions=${{ matrix.extension }} --debug --ignore-cache-sources=php-src
+
+      - name: "Build library: ${{ matrix.library }}"
+        run: |
+          SPC_USE_SUDO=yes ./bin/spc doctor --auto-fix
+          ./bin/spc build --build-cli --build-micro --build-fpm ${{ matrix.extension }} --debug --with-suggested-libs --with-suggested-exts

.github/workflows/release-build.yml

@@ -3,27 +3,41 @@ name: Build SPC Binary
 on:
   push:
     branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - '.github/workflows/release-build.yml'
   release:
     types:
       - published
   workflow_dispatch:
 
+env:
+  PHP_VERSION: 8.4
+  MICRO_VERSION: 8.4.11
+
 jobs:
   build-release-artifacts:
-    name: "Build SPC Binary"
-    runs-on: ubuntu-latest
+    name: "Build SPC Binary for ${{ matrix.operating-system.name }}"
+    runs-on: ${{ matrix.operating-system.os }}
     strategy:
       matrix:
-        php-version:
-          - "8.2"
-        micro-version:
-          - "8.2.16"
         operating-system:
-          - "linux-x86_64"
-          - "macos-x86_64"
-          - "linux-aarch64"
-          - "macos-aarch64"
-          - "windows-x64"
+          - name: "linux-x86_64"
+            os: "ubuntu-latest"
+            filename: "spc-linux-x86_64.tar.gz"
+          - name: "macos-x86_64"
+            os: "macos-15-intel"
+            filename: "spc-macos-x86_64.tar.gz"
+          - name: "linux-aarch64"
+            os: "ubuntu-latest"
+            filename: "spc-linux-aarch64.tar.gz"
+          - name: "macos-aarch64"
+            os: "macos-14"
+            filename: "spc-macos-aarch64.tar.gz"
+          - name: "windows-x64"
+            os: "ubuntu-latest"
+            filename: "spc-windows-x64.exe"
     steps:
       - name: "Checkout"
         uses: "actions/checkout@v4"
@@ -32,12 +46,13 @@ jobs:
         run: echo "SPC_BUILD_DEBUG=--debug" >> $GITHUB_ENV
 
       - name: "Install PHP for official runners"
-        uses: "shivammathur/setup-php@v2"
+        uses: shivammathur/setup-php@v2
         with:
           coverage: none
           tools: composer:v2
-          php-version: "${{ matrix.php-version }}"
+          php-version: "${{ env.PHP_VERSION }}"
           ini-values: memory_limit=-1
+          extensions: curl, openssl, mbstring
 
       - name: "Get Composer Cache Directory"
         id: composer-cache
@@ -45,12 +60,12 @@ jobs:
           echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: "Cache Composer dependencies"
-        uses: "actions/cache@v3"
+        uses: "actions/cache@v4"
         with:
           path: "${{ steps.composer-cache.outputs.dir }}"
-          key: "php-${{ matrix.php-version }}-locked-composer-${{ hashFiles('**/composer.lock') }}"
+          key: "php-${{ env.PHP_VERSION }}-locked-composer-${{ hashFiles('**/composer.lock') }}"
           restore-keys: |
-            php-${{ matrix.php-version }}-locked-composer
+            php-${{ env.PHP_VERSION }}-locked-composer
 
       - name: "Install Locked Dependencies"
         run: "composer install --no-interaction --no-progress"
@@ -58,68 +73,103 @@ jobs:
       - name: "Build PHAR File"
         run: "composer build:phar"
 
-      - name: "Download minimal combination"
+      - name: "Download Minimal Combination"
         run: |
-          if [ "${{ matrix.operating-system }}" = "windows-x64" ]; then
-            curl https://dl.static-php.dev/static-php-cli/windows/spc-min/php-${{ matrix.micro-version }}-micro-win.zip -o tmp.zip
+          if [ "${{ matrix.operating-system.name }}" = "windows-x64" ]; then
+            curl -fsSL https://dl.static-php.dev/static-php-cli/windows/spc-min/php-${{ env.MICRO_VERSION }}-micro-win.zip -o tmp.zip
             unzip tmp.zip
           else
-            curl https://dl.static-php.dev/static-php-cli/minimal/php-${{ matrix.micro-version }}-micro-${{ matrix.operating-system }}.tar.gz -o tmp.tgz
+            curl -fsSL https://dl.static-php.dev/static-php-cli/minimal/php-${{ env.MICRO_VERSION }}-micro-${{ matrix.operating-system.name }}.tar.gz -o tmp.tgz
             tar -zxvf tmp.tgz
           fi
-          
+
       - name: "Generate Executable"
         run: |
           bin/spc micro:combine spc.phar -M micro.sfx -O spc -I "memory_limit=2G"
-          if [ "${{ matrix.operating-system }}" = "windows-x64" ]; then
+          if [ "${{ matrix.operating-system.name }}" = "windows-x64" ]; then
             mv spc spc.exe
           else
             chmod +x spc
           fi
+          if [ "${{ matrix.operating-system.name }}" = "macos-aarch64" ] || [ "${{ matrix.operating-system.name }}" = "macos-x86_64" ]; then
+             sudo xattr -cr ./spc
+          fi
 
-      - name: "Archive Executable"
+      - name: "Archive Executable and Validate Binary"
         run: |
-          if [ "${{ matrix.operating-system }}" != "windows-x64" ]; then
-            tar -czf spc-${{ matrix.operating-system }}.tar.gz spc
-            echo "filename=spc-${{ matrix.operating-system }}.tar.gz" >> $GITHUB_ENV
-            echo "OS=${{ matrix.operating-system }}" >> $GITHUB_ENV
-            if [ "${{ matrix.operating-system }}" == "linux-x86_64" ]; then
+          if [ "${{ matrix.operating-system.name }}" != "windows-x64" ]; then
+            tar -czf ${{ matrix.operating-system.filename }} spc
+            # validate spc binary
+            if [ "${{ matrix.operating-system.name }}" == "linux-x86_64" ]; then
               ./spc dev:extensions
             fi
-          else
-            echo "filename=spc-${{ matrix.operating-system }}.exe" >> $GITHUB_ENV
-            echo "OS=${{ matrix.operating-system }}" >> $GITHUB_ENV
           fi
 
       - name: "Copy file"
         run: |
-          if [ "${{ matrix.operating-system }}" != "windows-x64" ]; then
-            mkdir dist/ && cp ${{ env.filename }} dist/ && cp spc dist/spc-$OS
+          if [ "${{ matrix.operating-system.name }}" != "windows-x64" ]; then
+            mkdir dist/ && cp ${{ matrix.operating-system.filename }} dist/ && cp spc dist/spc-${{ matrix.operating-system.name }}
           else
-            mkdir dist/ && cp spc.exe dist/${{ env.filename }}
+            mkdir dist/ && cp spc.exe dist/${{ matrix.operating-system.filename }}
             echo "SUFFIX=.exe" >> $GITHUB_ENV
           fi
 
-      - name: upload binaries to release
+      - name: "Upload Binaries to Release"
         uses: softprops/action-gh-release@v1
         if: ${{startsWith(github.ref, 'refs/tags/') }}
         with:
-          files: dist/${{ env.filename }}
+          files: dist/${{ matrix.operating-system.filename }}
 
-      - name: "Deploy to Self-Hosted Server"
-        if: github.repository == 'crazywhalecc/static-php-cli'
-        uses: easingthemes/ssh-deploy@main
-        env:
-          SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_SERVER_SECRET_KEY }}
-          ARGS: "-rltgoDzvO"
-          SOURCE: "dist/"
-          REMOTE_HOST: ${{ secrets.DEPLOY_SERVER_HOST }}
-          REMOTE_PORT: ${{ secrets.DEPLOY_SERVER_PORT }}
-          REMOTE_USER: ${{ secrets.DEPLOY_SERVER_USER }}
-          TARGET: ${{ secrets.DEPLOY_SERVER_TARGET_SPC_NIGHTLY }}
+      - name: "Deploy to self-hosted OSS"
+        # only run this step if the repository is static-php-cli and the branch is main
+        if: github.repository == 'crazywhalecc/static-php-cli' && github.ref == 'refs/heads/main'
+        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: static-php-cli/spc-bin/nightly/
+          endpoint: ${{ secrets.AWS_ENDPOINT }}
 
       - name: "Upload Artifact"
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           path: spc${{ env.SUFFIX }}
-          name: spc-${{ matrix.operating-system }}${{ env.SUFFIX }}
+          name: spc-${{ matrix.operating-system.name }}${{ env.SUFFIX }}
+  test-spc:
+    name: "Test SPC Binary for ${{ matrix.operating-system.name }}"
+    runs-on: ${{ matrix.operating-system.os }}
+    needs: [build-release-artifacts]
+    strategy:
+      matrix:
+        operating-system:
+          - name: "linux-x86_64"
+            os: "ubuntu-latest"
+          - name: "macos-x86_64"
+            os: "macos-15-intel"
+          - name: "linux-aarch64"
+            os: "ubuntu-24.04-arm"
+          - name: "macos-aarch64"
+            os: "macos-15"
+          - name: "windows-x64"
+            os: "windows-latest"
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Download Artifact"
+        uses: actions/download-artifact@v4
+        env:
+          SUFFIX: ${{ matrix.operating-system.name == 'windows-x64' && '.exe' || '' }}
+        with:
+          name: spc-${{ matrix.operating-system.name }}${{ env.SUFFIX }}
+
+      - name: "Chmod"
+        if: matrix.operating-system.name != 'windows-x64'
+        run: chmod +x spc
+
+      - name: "Run SPC Tests"
+        env:
+          SUFFIX: ${{ matrix.operating-system.name == 'windows-x64' && '.exe' || '' }}
+        run: ./spc${{ env.SUFFIX }} dev:extensions

.github/workflows/tests.yml

@@ -1,16 +1,22 @@
 name: Tests
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'src/globals/test-extensions.php'
   pull_request:
     branches: [ "main" ]
+    types: [ opened, synchronize, reopened ]
+    paths:
+      - 'src/**'
+      - 'config/**'
+      - '.github/workflows/tests.yml'
+      - 'bin/**'
+      - 'composer.json'
+      - 'box.json'
+      - '.php-cs-fixer.php'
 
-permissions:
-  contents: read
+permissions: read-all
+
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
   php-cs-fixer:
@@ -23,7 +29,7 @@ jobs:
       - name: "Setup PHP"
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.4'
           extensions: curl, openssl, mbstring
           ini-values: memory_limit=-1
           tools: pecl, composer, php-cs-fixer
@@ -41,14 +47,16 @@ jobs:
       - name: "Setup PHP"
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.1'
+          php-version: '8.4'
           extensions: curl, openssl, mbstring
           ini-values: memory_limit=-1
           tools: composer
+        env:
+          phpts: zts
 
       - name: "Cache Composer packages"
         id: composer-cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: vendor
           key: ${{ runner.os }}-phpstan-${{ hashFiles('**/composer.lock') }}
@@ -68,9 +76,7 @@ jobs:
     strategy:
       matrix:
         include:
-          - php: '8.1'
-          - php: '8.2'
-          - php: '8.3'
+          - php: '8.4'
 
     steps:
       - name: "Checkout"
@@ -86,37 +92,25 @@ jobs:
 
       - name: "Cache Composer packages"
         id: composer-cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: vendor
           key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
           restore-keys: |
-            ${{ runner.os }}-php-
+            ${{ runner.os }}-php
 
       - name: "Install Dependencies"
         run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
 
       - name: "Run PHPUnit Tests"
-        run: |
-          vendor/bin/phpunit tests/ --no-coverage
+        run: SPC_LIBC=glibc vendor/bin/phpunit tests/ --no-coverage
 
-  build:
-    name: "Build PHP Test (PHP ${{ matrix.php }} ${{ matrix.os }})"
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 120
-    strategy:
-      matrix:
-        php:
-          - "8.0"
-          - "8.1"
-          - "8.2"
-          - "8.3"
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-          - macos-14
-      fail-fast: false
+  define-matrix:
+    name: "Define Matrix"
+    runs-on: ubuntu-latest
+    outputs:
+      php: ${{ steps.gendef.outputs.php }}
+      os: ${{ steps.gendef.outputs.os }}
     steps:
       - name: "Checkout"
         uses: actions/checkout@v4
@@ -124,21 +118,49 @@ jobs:
       - name: "Setup PHP"
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.2
+          php-version: 8.4
+          extensions: curl, openssl, mbstring
+
+      - name: Define
+        id: gendef
+        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"
+
+
+  build:
+    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
+    steps:
+      - name: "Update runner packages"
+        if: ${{ startsWith(matrix.os, 'ubuntu-') }}
+        run: sudo apt-get update && sudo apt-get install -y ca-certificates
+
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Setup PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.4
           tools: pecl, composer
           extensions: curl, openssl, mbstring
           ini-values: memory_limit=-1
+        env:
+          phpts: nts
 
-      - name: "Use test token if exists"
-        if: matrix.os != 'windows-latest'
-        run: |
-          if [ "${{ secrets.TEST_GH_TOKEN }}" != "" ]; then
-            echo "GITHUB_TOKEN=${{ secrets.TEST_GH_TOKEN }}" >> $GITHUB_ENV
-          fi
-
-      - name: "Cache Composer packages"
+      - name: "Cache composer packages"
         id: composer-cache
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: vendor
           key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
@@ -147,25 +169,46 @@ jobs:
 
       # Cache downloaded source
       - id: cache-download
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: downloads
-          key: php-${{ matrix.php }}-dependencies
+          key: php-dependencies-${{ matrix.os }}
 
       - name: "Install Dependencies"
-        run: composer update -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+        run: composer update -vvv --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist --no-plugins
 
       - name: "Run Build Tests (doctor)"
-        run: bin/spc doctor --auto-fix
+        run: php src/globals/test-extensions.php doctor_cmd ${{ matrix.os }} ${{ matrix.php }}
+
+      - name: "Prepare UPX for Windows"
+        if: ${{ startsWith(matrix.os, 'windows-') }}
+        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
+
+      - 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)"
-        uses: nick-fields/retry@v3
-        with:
-          timeout_minutes: 10
-          max_attempts: 3
-          retry_on: error
-          command: |
-            bin/spc download --for-extensions="$(php src/globals/test-extensions.php extensions)" --for-libs="$(php src/globals/test-extensions.php libs)" --with-php=${{ matrix.php }} --ignore-cache-sources=php-src --debug
+        run: php src/globals/test-extensions.php download_cmd ${{ matrix.os }} ${{ matrix.php }}
 
       - name: "Run Build Tests (build)"
-        run: bin/spc build "$(php src/globals/test-extensions.php extensions)" --with-libs="$(php src/globals/test-extensions.php libs)" --build-cli --build-micro --build-fpm --debug
+        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@v4
+        with:
+          name: build-logs-${{ matrix.os }}-${{ matrix.php }}
+          path: log
+
+#      - name: Setup tmate session
+#        if: ${{ failure() }}
+#        uses: mxschmitt/action-tmate@v3

.github/workflows/update-docs-config.yml

@@ -1,43 +0,0 @@
-name: Update Docs Config
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - 'config/**.json'
-
-jobs:
-  update-docs-config:
-    name: "Update Docs Config"
-    runs-on: ubuntu-latest
-    if: github.repository == 'crazywhalecc/static-php-cli'
-    steps:
-      - name: "Checkout static-php-cli"
-        uses: actions/checkout@v4
-        with:
-          ref: main
-          path: static-php-cli
-
-      - name: "Checkout static-php-cli-docs"
-        uses: actions/checkout@v4
-        with:
-          repository: static-php/static-php-cli-docs
-          ref: master
-          token: ${{ secrets.DOCS_REPO_TOKEN }}
-          path: static-php-cli-docs
-
-      - name: "Set up Git"
-        run: |
-          git config --global user.email "actions@github.com"
-          git config --global user.name "GitHub Actions"
-
-      - name: "Copy Config Files"
-        run: cp -r static-php-cli/config/* static-php-cli-docs/docs/.vitepress/config/
-
-      - name: "Commit and Push Changes"
-        run: |
-          cd static-php-cli-docs
-          git add -A
-          git commit -m "Sync config files from main"
-          git push origin master

.github/workflows/vitepress-deploy.yml

@@ -0,0 +1,71 @@
+name: Docs Auto Deploy
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'config/**.json'
+      - 'docs/**'
+      - 'package.json'
+      - 'yarn.lock'
+      - '.github/workflows/vitepress-deploy.yml'
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    if: github.repository == 'crazywhalecc/static-php-cli'
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v3
+        with:
+          cache: yarn
+
+      - run: yarn install --frozen-lockfile
+
+      - name: "Copy Config Files"
+        run: |
+          mkdir -p docs/.vitepress/config
+          cp -r config/* docs/.vitepress/config/
+
+      - name: "Install PHP for official runners"
+        uses: shivammathur/setup-php@v2
+        with:
+          coverage: none
+          tools: composer:v2
+          php-version: 8.4
+          ini-values: memory_limit=-1
+          extensions: curl, openssl, mbstring
+
+      - name: "Get Composer Cache Directory"
+        id: composer-cache
+        run: |
+          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: "Cache Composer dependencies"
+        uses: "actions/cache@v4"
+        with:
+          path: "${{ steps.composer-cache.outputs.dir }}"
+          key: "php-8.2-locked-composer-${{ hashFiles('**/composer.lock') }}"
+          restore-keys: |
+            php-8.2-locked-composer
+
+      - name: "Install Locked Dependencies"
+        run: "composer install --no-interaction --no-progress"
+
+      - name: "Generate Extension Support List"
+        run: |
+          bin/spc dev:gen-ext-docs > docs/extensions.md
+          bin/spc dev:gen-ext-dep-docs > docs/deps-map-ext.md
+          bin/spc dev:gen-lib-dep-docs > docs/deps-map-lib.md
+
+      - name: Build
+        run: yarn docs:build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/.vitepress/dist

.gitignore

@@ -5,19 +5,29 @@ docker/extensions/
 docker/source/
 
 # Vendor files
-/vendor/
+/vendor/**
 
 # default source extract directory
-/source/
+/source/**
+
+# built by shared embed tests
+/locale/
 
 # default source download directory
-/downloads/
+/downloads/**
 
 # default source build root directory
-/buildroot/
+/buildroot/**
 
 # default package root directory
-/pkgroot/
+/pkgroot/**
+
+# Windows PHP SDK binary tools
+/php-sdk-binary-tools/**
+
+# default pack:lib and release directory
+/dist/**
+packlib_files.txt
 
 # tools cache files
 .php-cs-fixer.cache
@@ -27,10 +37,27 @@ docker/source/
 /bin/*
 !/bin/spc*
 !/bin/setup-runtime*
-!/bin/spc-alpine-docker
+!/bin/docker-entrypoint.sh
 
 # exclude windows build tools
 /php-sdk-binary-tools/
 
 # default test directory
 /tests/var/
+
+# VitePress
+/node_modules/
+/docs/.vitepress/dist/
+/docs/.vitepress/cache/
+package-lock.json
+pnpm-lock.yaml
+
+# craft
+craft.yml
+
+# SPC logs
+log/
+
+# spc.phar
+spc.phar
+spc.exe

.php-cs-fixer.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 return (new PhpCsFixer\Config())
     ->setRiskyAllowed(true)
+    ->setUnsupportedPhpVersionAllowed(true)
     ->setRules([
         '@PSR12' => true,
         '@Symfony' => true,
@@ -64,7 +65,10 @@ return (new PhpCsFixer\Config())
         'php_unit_test_class_requires_covers' => false,
         'phpdoc_var_without_name' => false,
         'fully_qualified_strict_types' => false,
+        'operator_linebreak' => false,
+        'php_unit_data_provider_method_order' => false,
     ])
     ->setFinder(
         PhpCsFixer\Finder::create()->in([__DIR__ . '/src', __DIR__ . '/tests/SPC'])
-    );
+    )
+    ->setParallelConfig(PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect());

README-zh.md

@@ -5,287 +5,168 @@
 [![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)
-[![Extensions](https://img.shields.io/badge/Extension%20Counter-75+-yellow.svg?style=flat-square)](https://static-php.dev/zh/guide/extensions.html)
 
-**static-php-cli**是一个用于静态编译、构建 PHP 解释器的工具，支持众多流行扩展。
-
-目前 static-php-cli 支持 `cli`、`fpm`、`embed` 和 `micro` SAPI。
-
-**static-php-cli**也支持将 PHP 代码和 PHP 运行时打包为一个文件并运行。
+**static-php-cli** 是一个用于构建静态、独立 PHP 运行时的强大工具，支持众多流行扩展。
 
 ## 特性
 
-static-php-cli（简称 `spc`）有许多特性：
+- :elephant: **支持多 PHP 版本** - 支持 PHP 8.1, 8.2, 8.3, 8.4, 8.5
+- :handbag: **单文件 PHP 可执行文件** - 构建零依赖的独立 PHP
+- :hamburger: **phpmicro 集成** - 构建 **[phpmicro](https://github.com/dixyes/phpmicro)** 自解压可执行文件（将 PHP 二进制文件和源代码合并为一个文件）
+- :pill: **智能环境检查器** - 自动构建环境检查器，具备自动修复功能
+- :zap: **跨平台支持** - 支持 Linux、macOS、FreeBSD 和 Windows
+- :wrench: **可配置补丁** - 可自定义的源代码补丁系统
+- :books: **智能依赖管理** - 自动处理构建依赖
+- 📦 **自包含工具** - 提供使用 [box](https://github.com/box-project/box) 构建的 `spc` 可执行文件
+- :fire: **广泛的扩展支持** - 支持 75+ 流行 [扩展](https://static-php.dev/zh/guide/extensions.html)
+- :floppy_disk: **UPX 压缩** - 减小二进制文件大小 30-50%（仅 Linux/Windows）
 
-- :handbag: 构建独立的单文件 PHP 解释器，无需任何依赖
-- :hamburger: 构建 **[phpmicro](https://github.com/dixyes/phpmicro)** 自执行二进制（将 PHP 代码和 PHP 解释器打包为一个文件）
-- :pill: 提供一键检查和修复编译环境的 Doctor 模块
-- :zap: 支持多个系统：`Linux`、`macOS`、`FreeBSD`、`Windows`
-- :wrench: 高度自定义的代码 patch 功能
-- :books: 自带编译依赖管理
-- 📦 提供由自身编译的独立 `spc` 二进制（使用 spc 和 [box](https://github.com/box-project/box) 构建）
-- :fire: 支持大量 [扩展](https://static-php.dev/zh/guide/extensions.html)
-- :floppy_disk: 整合 UPX 工具（减小二进制文件体积）
-
-**静态 php-cli:**
+**单文件独立 php-cli：**
 
 <img width="700" alt="out1" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/01a2e60f-13b0-4242-a645-f7afa4936396">
 
-**使用 phpmicro 打包 PHP 代码:**
+**使用 phpmicro 将 PHP 代码与 PHP 解释器结合：**
 
 <img width="700" alt="out2" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/46b7128d-fb72-4169-957e-48564c3ff3e2">
 
+## 快速开始
+
+### 1. 下载 spc 二进制文件
+
+```bash
+# Linux x86_64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+# Linux aarch64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
+# macOS x86_64 (Intel)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
+# macOS aarch64 (Apple)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
+# Windows (x86_64, win10 build 17063 或更高版本，请先安装 VS2022)
+curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
+```
+
+对于 macOS 和 Linux，请先添加执行权限：
+
+```bash
+chmod +x ./spc
+```
+
+### 2. 构建静态 PHP
+
+首先，创建一个 `craft.yml` 文件，并从 [扩展列表](https://static-php.dev/zh/guide/extensions.html) 或 [命令生成器](https://static-php.dev/zh/guide/cli-generator.html) 中指定要包含的扩展：
+
+```yml
+# PHP 版本支持：8.1, 8.2, 8.3, 8.4, 8.5
+php-version: 8.4
+# 在此处放置您的扩展列表
+extensions: "apcu,bcmath,calendar,ctype,curl,dba,dom,exif,fileinfo,filter,gd,iconv,mbregex,mbstring,mysqli,mysqlnd,opcache,openssl,pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,readline,redis,session,simplexml,sockets,sodium,sqlite3,tokenizer,xml,xmlreader,xmlwriter,xsl,zip,zlib"
+sapi:
+  - cli
+  - micro
+  - fpm
+download-options:
+  prefer-pre-built: true
+```
+
+运行命令：
+
+```bash
+./spc craft
+
+# 输出完整控制台日志
+./spc craft --debug
+```
+
+### 3. 静态 PHP 使用
+
+现在您可以将 static-php-cli 构建的二进制文件复制到另一台机器上，无需依赖即可运行：
+
+```
+# php-cli
+buildroot/bin/php -v
+
+# phpmicro
+echo '<?php echo "Hello world!\n";' > a.php
+./spc micro:combine a.php -O my-app
+./my-app
+
+# php-fpm
+buildroot/bin/php-fpm -v
+```
+
 ## 文档
 
-目前 README 编写了基本用法。有关 static-php-cli 所有的功能，请点击这里查看文档：<https://static-php.dev>。
+当前 README 包含基本用法。有关 static-php-cli 的所有功能，
+请访问 <https://static-php.dev>。
 
 ## 直接下载
 
-如果你不想自行编译 PHP，可以从本项目现有的示例 Action 下载 Artifact，也可以从自托管的服务器下载。
+如果您不想构建或想先测试，可以从 [Actions](https://github.com/static-php/static-php-cli-hosted/actions/workflows/build-php-bulk.yml) 下载示例预编译工件，或从自托管服务器下载。
 
-- [扩展组合 - common](https://dl.static-php.dev/static-php-cli/common/)：common 组合包含了约 [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) 个常用扩展，体积为 22MB 左右。
-- [扩展组合 - bulk](https://dl.static-php.dev/static-php-cli/bulk/)：bulk 组合包含了 [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) 个扩展，体积为 70MB 左右。
-- [扩展组合 - minimal](https://dl.static-php.dev/static-php-cli/minimal/)：minimal 组合包含了 [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) 个扩展，体积为 6MB 左右。
+以下是几个具有不同扩展组合的预编译静态 PHP 二进制文件，
+您可以根据需要直接下载。
 
-对于 Windows 系统，目前支持的扩展较少，故仅提供 SPC 自身运行的最小扩展组合的 `cli` 和 `micro`：[扩展组合 - spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/)。
+| 组合名称                                                                 | 扩展数量                                                            | 系统           | 备注                 |
+|----------------------------------------------------------------------|----------------------------------------------------------------------------|--------------|--------------------|
+| [common](https://dl.static-php.dev/static-php-cli/common/)           | [30+](https://dl.static-php.dev/static-php-cli/common/README.txt)          | Linux, macOS | 二进制文件大小约为 7.5MB    |
+| [bulk](https://dl.static-php.dev/static-php-cli/bulk/)               | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt)            | Linux, macOS | 二进制文件大小约为 25MB     |
+| [gnu-bulk](https://dl.static-php.dev/static-php-cli/gnu-bulk/)       | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt)            | Linux, macOS | 使用 glibc 的 bulk 组合 |
+| [minimal](https://dl.static-php.dev/static-php-cli/minimal/)         | [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt)           | Linux, macOS | 二进制文件大小约为 3MB      |
+| [spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/) | [5](https://dl.static-php.dev/static-php-cli/windows/spc-min/README.txt)   | Windows      | 二进制文件大小约为 3MB      |
+| [spc-max](https://dl.static-php.dev/static-php-cli/windows/spc-max/) | [40+](https://dl.static-php.dev/static-php-cli/windows/spc-max/README.txt) | Windows      | 二进制文件大小约为 8.5MB    |
 
-## 使用 static-php-cli 构建 PHP
-
-### 编译环境需求
-
-- PHP >= 8.1（这是 spc 自身需要的版本，不是支持的构建版本）
-- 扩展：`mbstring,tokenizer,phar`
-- 系统安装了 `curl` 和 `git`
-
-是的，本项目采用 PHP 编写，编译前需要一个 PHP 环境，比较滑稽。
-但本项目默认可通过自身构建的 micro 和 static-php 二进制运行，其他只需要包含上面提到的扩展和 PHP 版本大于等于 8.1 即可。
-
-下面是架构支持情况，:octocat: 代表支持 GitHub Action 构建，:computer: 代表支持本地构建，空 代表暂不支持。
-
-|         | x86_64               | aarch64              |
-|---------|----------------------|----------------------|
-| macOS   | :octocat: :computer: | :octocat: :computer: |
-| Linux   | :octocat: :computer: | :octocat: :computer: |
-| Windows | :computer:           |                      |
-| FreeBSD | :computer:           | :computer:           |
-
-当前支持编译的 PHP 版本：
-
-> :warning: 支持，但可能不再提供修复
-> 
-> :heavy_check_mark: 支持
-> 
-> :x: 不支持
-
-| PHP Version | Status             | Comment                      |
-|-------------|--------------------|------------------------------|
-| 7.2         | :x:                |                              |
-| 7.3         | :warning:          | phpmicro 和许多扩展不支持 7.3、7.4 版本 |
-| 7.4         | :warning:          | phpmicro 和许多扩展不支持 7.3、7.4 版本 |
-| 8.0         | :heavy_check_mark: | PHP 官方已停止 8.0 的维护            |
-| 8.1         | :heavy_check_mark: |                              |
-| 8.2         | :heavy_check_mark: |                              |
-| 8.3         | :heavy_check_mark: |                              |
-
-### 支持的扩展
-
-请先根据下方扩展列表选择你要编译的扩展。
-
-- [扩展支持列表](https://static-php.dev/zh/guide/extensions.html)
-- [编译命令生成器](https://static-php.dev/zh/guide/cli-generator.html)
-
-> 如果这里没有你需要的扩展，可以提交 Issue。
+> Linux 和 Windows 支持对二进制文件进行 UPX 压缩，可以将二进制文件大小减少 30% 到 50%。
+> macOS 不支持 UPX 压缩，因此 mac 的预构建二进制文件大小较大。
 
 ### 在线构建（使用 GitHub Actions）
 
-使用 GitHub Action 可以方便地构建一个静态编译的 PHP，同时可以自行定义要编译的扩展。
+上方直接下载的二进制不能满足需求时，可使用 GitHub Action 可以轻松构建静态编译的 PHP，
+同时自行定义要编译的扩展。
 
 1. Fork 本项目。
-2. 进入项目的 Actions，选择 CI。
-3. 选择 `Run workflow`，填入你要编译的 PHP 版本、目标类型、扩展列表。（扩展列表使用英文逗号分割，例如 `bcmath,curl,mbstring`）
-4. 等待大约一段时间后，进入对应的任务中，获取 `Artifacts`。
+2. 进入项目的 Actions 并选择 `CI`。
+3. 选择 `Run workflow`，填入您要编译的 PHP 版本、目标类型和扩展列表。（扩展用逗号分隔，例如 `bcmath,curl,mbstring`）
+4. 等待一段时间后，进入相应的任务并获取 `Artifacts`。
 
-如果你选择了 `debug`，则会在构建时输出所有日志，包括编译的日志，以供排查错误。
-
-### 本地构建（使用 spc 二进制）
-
-该项目提供了 static-php-cli 的二进制文件：`spc`。
-您可以使用 `spc` 二进制文件，无需安装任何运行时（用起来就像 golang 程序）。
-目前，`spc` 二进制文件提供的平台有 Linux 和 macOS。
-
-使用以下命令从自托管服务器下载：
-
-```bash
-# Download from self-hosted nightly builds (sync with main branch)
-# For Linux x86_64
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
-# For Linux aarch64
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
-# macOS x86_64 (Intel)
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
-# macOS aarch64 (Apple)
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
-# Windows (x86_64, win10 build 17063 or later)
-curl.exe -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
-
-# Add execute perm (Linux and macOS only)
-chmod +x ./spc
-
-# Run (Linux and macOS)
-./spc --version
-# Run (Windows powershell)
-.\spc.exe --version
-```
-
-自托管 `spc` 由 GitHub Actions 构建，你也可以从 Actions 直接下载：[此处](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml)。
-
-### 本地构建（使用 git 源码）
-
-```bash
-# clone 仓库即可
-git clone https://github.com/crazywhalecc/static-php-cli.git
-```
-
-如果您的系统上尚未安装 php，我们建议你使用内置的 setup-runtime 自动安装 PHP 和 Composer。
-
-```bash
-cd static-php-cli
-chmod +x bin/setup-runtime
-# it will download static php (from self-hosted server) and composer (from getcomposer)
-bin/setup-runtime
-# initialize composer deps
-bin/composer install
-# chmod
-chmod +x bin/spc
-bin/spc --version
-```
-
-### 开始构建 PHP
-
-下面是使用 static-php-cli 的基础用法：
-
-> 如果你使用的是打包好的 `spc` 二进制，你需要将下列命令的 `./bin/spc` 替换为 `./spc`。
-
-```bash
-# 检查环境依赖，并根据尝试自动安装缺失的编译工具
-./bin/spc doctor --auto-fix
-
-# 拉取所有依赖库
-./bin/spc download --all
-# 只拉取编译指定扩展需要的所有依赖（推荐）
-./bin/spc download --for-extensions="openssl,pcntl,mbstring,pdo_sqlite"
-# 下载编译不同版本的 PHP (--with-php=x.y，推荐 7.3 ~ 8.3)
-./bin/spc download --for-extensions="openssl,curl,mbstring" --with-php=8.1
-
-# 构建包含 bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl 扩展的 php-cli 和 micro.sfx
-./bin/spc build "bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl" --build-cli --build-micro
-# 编译线程安全版本 (--enable-zts)
-./bin/spc build "curl,phar" --enable-zts --build-cli
-# 编译后使用 UPX 减小可执行文件体积 (--with-upx-pack) (至少压缩至原来的 30~50%)
-./bin/spc build "curl,phar" --enable-zts --build-cli --with-upx-pack
-```
-
-其中，目前支持构建 cli，micro，fpm 和 embed，使用以下参数的一个或多个来指定编译的 SAPI：
-
-- `--build-cli`：构建 cli 二进制
-- `--build-micro`：构建 phpmicro 自执行二进制
-- `--build-fpm`：构建 fpm
-- `--build-embed`：构建 embed（libphp）
-- `--build-all`：构建所有
-
-如果出现了任何错误，可以使用 `--debug` 参数来展示完整的输出日志，以供排查错误：
-
-```bash
-./bin/spc build "openssl,pcntl,mbstring" --debug --build-all
-./bin/spc download --all --debug
-```
-
-## 不同 SAPI 的使用
-
-### 使用 cli
-
-> php-cli 是一个静态的二进制文件，类似 Go、Rust 语言编译后的单个可移植的二进制文件。
-
-采用参数 `--build-cli` 或`--build-all` 参数时，最后编译结果会输出一个 `./php` 的二进制文件，此文件可分发、可直接使用。
-该文件编译后会存放在 `buildroot/bin/` 目录中，名称为 `php`，拷贝出来即可。
-
-```bash
-cd buildroot/bin/
-./php -v                # 检查版本
-./php -m                # 检查编译的扩展
-./php your_code.php     # 运行代码
-./php your_project.phar # 运行打包为 phar 单文件的项目
-```
-
-### 使用 micro
-
-> phpmicro 是一个提供自执行二进制 PHP 的项目，本项目依赖 phpmicro 进行编译自执行二进制。详见 [dixyes/phpmicro](https://github.com/dixyes/phpmicro)。
-
-采用项目参数 `--build-micro` 或 `--build-all` 时，最后编译结果会输出一个 `./micro.sfx` 的文件，此文件需要配合你的 PHP 源码使用。
-该文件编译后会存放在 `buildroot/bin/` 目录中，拷贝出来即可。
-
-使用时应准备好你的项目源码文件，可以是单个 PHP 文件，也可以是 Phar 文件。
-
-```bash
-echo "<?php echo 'Hello world' . PHP_EOL;" > code.php
-cat micro.sfx code.php > single-app && chmod +x single-app
-./single-app
-```
-
-如果打包 PHAR 文件，仅需把 code.php 更换为 phar 文件路径即可。
-你可以使用 [box-project/box](https://github.com/box-project/box) 将你的 CLI 项目打包为 Phar，
-然后将它与 phpmicro 结合，生成独立可执行的二进制文件。
-
-```bash
-# 使用 static-php-cli 生成的 micro.sfx 结合，也可以直接使用 cat 命令结合它们
-bin/spc micro:combine my-app.phar
-cat buildroot/bin/micro.sfx my-app.phar > my-app && chmod +x my-app
-
-# 使用 micro:combine 结合可以将 INI 选项注入到二进制中
-bin/spc micro:combine my-app.phar -I "memory_limit=4G" -I "disable_functions=system" --output my-app-2
-```
-
-> 有些情况下的 phar 文件或 PHP 项目可能无法在 micro 环境下运行。
-
-### 使用 fpm
-
-采用项目参数 `--build-fpm` 或 `--build-all` 时，最后编译结果会输出一个 `./php-fpm` 的文件。
-该文件存放在 `buildroot/bin/` 目录，拷贝出来即可使用。
-
-在正常的 Linux 发行版和 macOS 系统中，安装 php-fpm 后包管理会自动生成默认的 fpm 配置文件。
-因为 php-fpm 必须指定配置文件才可启动，本项目编译的 php-fpm 不会带任何配置文件，所以需自行编写 `php-fpm.conf` 和 `pool.conf` 配置文件。
-
-指定 `php-fpm.conf` 可以使用命令参数 `-y`，例如：`./php-fpm -y php-fpm.conf`。
-
-### 使用 embed
-
-采用项目参数 `--build-embed` 或 `--build-all` 时，最后编译结果会输出一个 `libphp.a`、`php-config` 以及一系列头文件，存放在 `buildroot/`，你可以在你的其他代码中引入它们。
-
-如果你知道 [embed SAPI](https://github.com/php/php-src/tree/master/sapi/embed)，你应该知道如何使用它。对于有可能编译用到引入其他库的问题，你可以使用 `buildroot/bin/php-config` 来获取编译时的配置。
-
-另外，有关如何使用此功能的高级示例，请查看[如何使用它构建 FrankenPHP 的静态版本](https://github.com/dunglas/frankenphp/blob/main/docs/static.md)。
+如果您启用 `debug`，构建时将输出所有日志，包括编译日志，以便故障排除。
 
 ## 贡献
 
-如果缺少你需要的扩展，可发起 Issue。如果你对本项目较熟悉，也欢迎为本项目发起 Pull Request。
+如果您需要的扩展缺失，可以创建 issue。
+如果您熟悉本项目，也欢迎发起 pull request。
 
-另外，添加新扩展的贡献方式，可以参考下方 `进阶`。
+如果您想贡献文档，请直接编辑 `docs/` 目录。
 
-如果你想贡献文档内容，请到项目仓库 [static-php/static-php-cli-docs](https://github.com/static-php/static-php-cli-docs) 贡献。
+现在有一个 [static-php](https://github.com/static-php) 组织，用于存储与项目相关的仓库。
 
 ## 赞助本项目
 
-你可以在 [我的个人赞助页](https://github.com/crazywhalecc/crazywhalecc/blob/master/FUNDING.md) 支持我和我的项目。你捐赠的一部分将会被用于维护 **static-php.dev** 服务器。
+您可以从 [GitHub Sponsor](https://github.com/crazywhalecc) 赞助我或我的项目。您捐赠的一部分将用于维护 **static-php.dev** 服务器。
 
-## 开源协议
+**特别感谢以下赞助商**：
 
-本项目采用 MIT License 许可开源，下面是类似的项目：
+<a href="https://beyondco.de/"><img src="/docs/public/images/beyondcode-seeklogo.png" width="300" alt="Beyond Code Logo" /></a>
+
+<a href="https://nativephp.com/"><img src="/docs/public/images/nativephp-logo.svg" width="300" alt="NativePHP Logo" /></a>
+
+## 开源许可证
+
+本项目本身基于 MIT 许可证，
+一些新添加的扩展和依赖可能来自其他项目，
+这些代码文件的头部也会给出额外的许可证和作者说明。
+
+这些是类似的项目：
 
 - [dixyes/lwmbs](https://github.com/dixyes/lwmbs)
 - [swoole/swoole-cli](https://github.com/swoole/swoole-cli)
 
-该项目使用了 [dixyes/lwmbs](https://github.com/dixyes/lwmbs) 中的一些代码，例如 Windows 静态构建目标和 libiconv 库支持。
-lwmbs 使用 [Mulan PSL 2](http://license.coscl.org.cn/MulanPSL2) 许可进行分发。对应文件有关于作者和许可的特殊说明，除此之外，均使用 MIT 授权许可。
+本项目使用了 [dixyes/lwmbs](https://github.com/dixyes/lwmbs) 的一些代码，例如 Windows 静态构建目标和 libiconv 支持。
+lwmbs 基于 [Mulan PSL 2](http://license.coscl.org.cn/MulanPSL2) 许可证。
 
-因本项目的特殊性，使用项目编译过程中会使用很多其他开源项目，例如 curl、protobuf 等，它们都有各自的开源协议。
-请在编译完成后，使用命令 `bin/spc dump-license` 导出项目使用项目的开源协议，并遵守对应项目的 LICENSE。
+由于本项目的特殊性，
+项目编译过程中会使用许多其他开源项目，如 curl 和 protobuf，
+它们都有自己的开源许可证。
+
+请在编译后使用 `bin/spc dump-license` 命令导出项目中使用的开源许可证，
+并遵守相应项目的 LICENSE。

README.md

@@ -5,29 +5,22 @@
 [![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)
-[![Extensions](https://img.shields.io/badge/Extension%20Counter-75+-yellow.svg?style=flat-square)](https://static-php.dev/en/guide/extensions.html)
 
 **static-php-cli** is a powerful tool designed for building static, standalone PHP runtime
 with popular extensions.
 
-Static PHP built by **static-php-cli** supports `cli`, `fpm`, `embed` and `micro` SAPI.
-
-**static-php-cli** also has the ability to package PHP projects
-along with the PHP interpreter into one single executable file.
-
 ## Features
 
-static-php-cli (you can call it `spc`) has a lot of features:
-
-- :handbag: Build single-file php executable, without any dependencies
-- :hamburger: Build **[phpmicro](https://github.com/dixyes/phpmicro)** self-extracted executable (glue php binary and php source code into one file)
-- :pill: Automatic build environment checker (Doctor module)
+- :elephant: Support multiple PHP versions - PHP 8.1, 8.2, 8.3, 8.4, 8.5
+- :handbag: Build single-file PHP executable with zero dependencies
+- :hamburger:Build **[phpmicro](https://github.com/dixyes/phpmicro)** self-extracting executables (combines PHP binary and source code into one file)
+- :pill: Automatic build environment checker with auto-fix capabilities
 - :zap: `Linux`, `macOS`, `FreeBSD`, `Windows` support
-- :wrench: Configurable source code patches
-- :books: Build dependency management
-- 📦 Provide `spc` own standalone executable (built by spc and [box](https://github.com/box-project/box))
-- :fire: Support many popular [extensions](https://static-php.dev/en/guide/extensions.html)
-- :floppy_disk: UPX integration (significantly reduces binary size)
+- :wrench: Configurable source code patching
+- :books: Intelligent dependency management
+- 📦 Self-contained `spc` executable (built with [box](https://github.com/box-project/box))
+- :fire: Support 100+ popular [extensions](https://static-php.dev/en/guide/extensions.html)
+- :floppy_disk: UPX compression support (reduces binary size by 30-50%)
 
 **Single-file standalone php-cli:**
 
@@ -37,6 +30,72 @@ static-php-cli (you can call it `spc`) has a lot of features:
 
 <img width="700" alt="out2" src="https://github.com/crazywhalecc/static-php-cli/assets/20330940/46b7128d-fb72-4169-957e-48564c3ff3e2">
 
+## Quickstart
+
+### 1. Download spc binary
+
+```bash
+# For Linux x86_64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+# For Linux aarch64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
+# macOS x86_64 (Intel)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
+# macOS aarch64 (Apple)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/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/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
+```
+
+For macOS and Linux, add execute permission first:
+
+```bash
+chmod +x ./spc
+```
+
+### 2. Build Static PHP
+
+First, create a `craft.yml` file and specify which extensions you want to include from [extension list](https://static-php.dev/en/guide/extensions.html) or [command generator](https://static-php.dev/en/guide/cli-generator.html):
+
+```yml
+# PHP version support: 8.1, 8.2, 8.3, 8.4, 8.5
+php-version: 8.4
+# Put your extension list here
+extensions: "apcu,bcmath,calendar,ctype,curl,dba,dom,exif,fileinfo,filter,gd,iconv,mbregex,mbstring,mysqli,mysqlnd,opcache,openssl,pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,readline,redis,session,simplexml,sockets,sodium,sqlite3,tokenizer,xml,xmlreader,xmlwriter,xsl,zip,zlib"
+sapi:
+  - cli
+  - micro
+  - fpm
+download-options:
+  prefer-pre-built: true
+```
+
+Run command:
+
+```bash
+./spc craft
+
+# Output full console log
+./spc craft --debug
+```
+
+### 3. Static PHP usage
+
+Now you can copy binaries built by static-php-cli to another machine and run with no dependencies:
+
+```
+# php-cli
+buildroot/bin/php -v
+
+# phpmicro
+echo '<?php echo "Hello world!\n";' > a.php
+./spc micro:combine a.php -O my-app
+./my-app
+
+# php-fpm
+buildroot/bin/php-fpm -v
+```
+
 ## Documentation
 
 The current README contains basic usage. For all the features of static-php-cli,
@@ -49,66 +108,22 @@ If you don't want to build or want to test first, you can download example pre-c
 Below are several precompiled static-php binaries with different extension combinations,
 which can be downloaded directly according to your needs.
 
-- [Extension-Combination - common](https://dl.static-php.dev/static-php-cli/common/): `common` contains about [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) commonly used extensions, and the size is about 22MB.
-- [Extension-Combination - bulk](https://dl.static-php.dev/static-php-cli/bulk/): `bulk` contains [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) extensions and is about 70MB in size.
-- [Extension-Combination - minimal](https://dl.static-php.dev/static-php-cli/minimal/): `minimal` contains [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) extensions and is about 6MB in size.
+| Combination                                                          | Extension Count                                                            | OS           | Comment                        |
+|----------------------------------------------------------------------|----------------------------------------------------------------------------|--------------|--------------------------------|
+| [common](https://dl.static-php.dev/static-php-cli/common/)           | [30+](https://dl.static-php.dev/static-php-cli/common/README.txt)          | Linux, macOS | The binary size is about 7.5MB |
+| [bulk](https://dl.static-php.dev/static-php-cli/bulk/)               | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt)            | Linux, macOS | The binary size is about 25MB  |
+| [gnu-bulk](https://dl.static-php.dev/static-php-cli/gnu-bulk/)       | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt)            | Linux, macOS | Using shared glibc             |
+| [minimal](https://dl.static-php.dev/static-php-cli/minimal/)         | [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt)           | Linux, macOS | The binary size is about 3MB   |
+| [spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/) | [5](https://dl.static-php.dev/static-php-cli/windows/spc-min/README.txt)   | Windows      | The binary size is about 3MB   |
+| [spc-max](https://dl.static-php.dev/static-php-cli/windows/spc-max/) | [40+](https://dl.static-php.dev/static-php-cli/windows/spc-max/README.txt) | Windows      | The binary size is about 8.5MB |
 
-For Windows systems, there are currently fewer extensions supported, 
-so only `cli` and `micro` that run the minimum extension combination of SPC itself are provided: [Extension-Combination - spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/).
-
-## Build
-
-### Compilation Requirements
-
-You can say I made a PHP builder written in PHP, pretty funny.
-But static-php-cli runtime only requires an environment above PHP 8.1 and extensions mentioned below.
-
-- PHP >= 8.1 (This is the version required by spc itself, not the build version)
-- Extension: `mbstring,tokenizer,phar`
-- Supported OS with `curl` and `git` installed
-
-Here is the supported OS and arch, where :octocat: represents support for GitHub Action builds,
-:computer: represents support for local manual builds, and blank represents not currently supported.
-
-|         | x86_64               | aarch64              |
-|---------|----------------------|----------------------|
-| macOS   | :octocat: :computer: | :octocat: :computer: |
-| Linux   | :octocat: :computer: | :octocat: :computer: |
-| Windows | :computer:           |                      |
-| FreeBSD | :computer:           | :computer:           |
-
-Currently supported PHP versions for compilation: 
-
-> :warning: supported but not maintained
-> 
-> :heavy_check_mark: supported
-> 
-> :x: not supported
-
-| PHP Version | Status             | Comment                                           |
-|-------------|--------------------|---------------------------------------------------|
-| 7.2         | :x:                |                                                   |
-| 7.3         | :warning:          | phpmicro and some extensions not supported on 7.x |
-| 7.4         | :warning:          | phpmicro and some extensions not supported on 7.x |
-| 8.0         | :heavy_check_mark: | PHP official has stopped maintenance of 8.0       |
-| 8.1         | :heavy_check_mark: |                                                   |
-| 8.2         | :heavy_check_mark: |                                                   |
-| 8.3         | :heavy_check_mark: |                                                   |
-
-### Supported Extensions
-
-Please first select the extension you want to compile based on the extension list below.
-
-- [Supported Extension List](https://static-php.dev/en/guide/extensions.html)
-- [Command Generator](https://static-php.dev/en/guide/cli-generator.html)
-
-> If an extension you need is missing, you can submit an issue.
-
-Here is the current planned roadmap for extension support: [#152](https://github.com/crazywhalecc/static-php-cli/issues/152) .
+> Linux and Windows supports UPX compression for binaries, which can reduce the size of the binary by 30% to 50%.
+> macOS does not support UPX compression, so the size of the pre-built binaries for mac is larger.
 
 ### Build Online (using GitHub Actions)
 
-Use GitHub Action to easily build a statically compiled PHP,
+When the above direct download binaries cannot meet your needs,
+you can use GitHub Action to easily build a statically compiled PHP,
 and at the same time define the extensions to be compiled by yourself.
 
 1. Fork me.
@@ -118,189 +133,24 @@ and at the same time define the extensions to be compiled by yourself.
 
 If you enable `debug`, all logs will be output at build time, including compiled logs, for troubleshooting.
 
-### Build Locally (using SPC binary)
-
-This project provides a binary file of static-php-cli: `spc`.
-You can use `spc` binary instead of installing any runtime like golang app.
-Currently, the platforms supported by `spc` binary are Linux and macOS.
-
-Download from self-hosted nightly builds using commands below:
-
-```bash
-# Download from self-hosted nightly builds (sync with main branch)
-# For Linux x86_64
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
-# For Linux aarch64
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
-# macOS x86_64 (Intel)
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
-# macOS aarch64 (Apple)
-curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
-# Windows (x86_64, win10 build 17063 or later)
-curl.exe -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
-
-# Add execute perm (Linux and macOS only)
-chmod +x ./spc
-
-# Run (Linux and macOS)
-./spc --version
-# Run (Windows powershell)
-.\spc.exe --version
-```
-
-Self-hosted `spc` is built by GitHub Actions, you can also download from Actions artifacts [here](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml).
-
-### Build Locally (using git source)
-
-```bash
-# just clone me!
-git clone https://github.com/crazywhalecc/static-php-cli.git
-```
-
-If you have not installed php on your system, we recommend that you use the built-in setup-runtime to install PHP and Composer automatically.
-
-```bash
-cd static-php-cli
-chmod +x bin/setup-runtime
-# it will download static php (from self-hosted server) and composer (from getcomposer)
-bin/setup-runtime
-# initialize composer deps
-bin/composer install
-# chmod
-chmod +x bin/spc
-bin/spc --version
-```
-
-### Start Building PHP
-
-Basic usage for building php with some extensions:
-
-> If you are using the packaged standalone `spc` binary, you need to replace `bin/spc` with `./spc` or `.\spc.exe` in the following commands.
-
-```bash
-# Check system tool dependencies, auto-fix them if possible
-./bin/spc doctor --auto-fix
-
-# fetch all libraries
-./bin/spc download --all
-# only fetch necessary sources by needed extensions (recommended)
-./bin/spc download --for-extensions="openssl,pcntl,mbstring,pdo_sqlite"
-# download different PHP version (--with-php=x.y, recommend 7.3 ~ 8.3)
-./bin/spc download --for-extensions="openssl,curl,mbstring" --with-php=8.1
-
-# with bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl extension, build both CLI and phpmicro SAPI
-./bin/spc build "bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl" --build-cli --build-micro
-# build thread-safe (ZTS) version (--enable-zts)
-./bin/spc build "curl,phar" --enable-zts --build-cli
-# build, pack executable with UPX (--with-upx-pack) (reduce binary size for 30~50%)
-./bin/spc build "curl,phar" --enable-zts --build-cli --with-upx-pack
-```
-
-Now we support `cli`, `micro`, `fpm` and `embed` SAPI. You can use one or more of the following parameters to specify the compiled SAPI:
-
-- `--build-cli`: build static cli executable
-- `--build-micro`: build static phpmicro self-extracted executable
-- `--build-fpm`: build static fpm binary
-- `--build-embed`: build embed (libphp)
-- `--build-all`: build all
-
-If anything goes wrong, use `--debug` option to display full terminal output:
-
-```bash
-./bin/spc build "openssl,pcntl,mbstring" --debug --build-all
-./bin/spc download --all --debug
-```
-
-## Different SAPI Usage
-
-### Use cli
-
-> php-cli is a single static binary, you can use it like normal php installed on your system.
-
-When using the parameter `--build-cli` or `--build-all`,
-the final compilation result will output a binary file named `./php`,
-which can be distributed and used directly.
-This file will be located in the directory `buildroot/bin/`, copy it out for use.
-
-```bash
-cd buildroot/bin/
-./php -v                # check version
-./php -m                # check extensions
-./php your_code.php     # run your php code
-./php your_project.phar # run your phar (project archive)
-```
-
-### Use micro
-
-> phpmicro is a SelF-extracted eXecutable SAPI module,
-> provided by [phpmicro](https://github.com/dixyes/phpmicro) project.
-> But this project is using a [fork](https://github.com/static-php/phpmicro) of phpmicro, because we need to add some features to it.
-> It can put php runtime and your source code together.
-
-When using the parameter `--build-all` or `--build-micro`,
-the final compilation result will output a file named `./micro.sfx`,
-which needs to be used with your PHP source code like `code.php`.
-This file will be located in the path `buildroot/bin/micro.sfx`, simply copy it out for use.
-
-Prepare your project source code, which can be a single PHP file or a Phar file, for use.
-
-```bash
-echo "<?php echo 'Hello world' . PHP_EOL;" > code.php
-cat micro.sfx code.php > single-app && chmod +x single-app
-./single-app
-```
-
-If you package a PHAR file, just replace `code.php` with the phar file path.
-You can use [box-project/box](https://github.com/box-project/box) to package your CLI project as Phar,
-It is then combined with phpmicro to produce a standalone executable binary.
-
-```bash
-# Use the micro.sfx generated by static-php-cli to combine,
-bin/spc micro:combine my-app.phar
-# or you can directly use the cat command to combine them.
-cat buildroot/bin/micro.sfx my-app.phar > my-app && chmod +x my-app
-
-# Use micro:combine combination to inject INI options into the binary.
-bin/spc micro:combine my-app.phar -I "memory_limit=4G" -I "disable_functions=system" --output my-app-2
-```
-
-> In some cases, PHAR files may not run in a micro environment. Overall, micro is not production ready.
-
-### Use fpm
-
-When using the parameter `--build-all` or `--build-fpm`,
-the final compilation result will output a file named `./php-fpm`,
-This file will be located in the path `buildroot/bin/`, simply copy it out for use.
-
-In common Linux distributions and macOS systems, the package manager will automatically generate a default fpm configuration file after installing php-fpm.
-Because php-fpm must specify a configuration file before running, the php-fpm compiled by this project will not have any configuration files, so you need to write `php-fpm.conf` and `pool.conf` configuration files yourself.
-
-Specifying `php-fpm.conf` can use the command parameter `-y`, for example: `./php-fpm -y php-fpm.conf`.
-
-### Use embed
-
-When using the project parameters `--build-embed` or `--build-all`,
-the final compilation result will output a `libphp.a`, `php-config` and a series of header files,
-stored in `buildroot/`. You can introduce them in your other projects.
-
-If you know [embed SAPI](https://github.com/php/php-src/tree/master/sapi/embed), you should know how to use it.
-You may require the introduction of other libraries during compilation,
-you can use `buildroot/bin/php-config` to obtain the compile-time configuration.
-
-For an advanced example of how to use this feature, take a look at [how to use it to build a static version of FrankenPHP](https://github.com/dunglas/frankenphp/blob/main/docs/static.md).
-
 ## Contribution
 
 If the extension you need is missing, you can create an issue.
 If you are familiar with this project, you are also welcome to initiate a pull request.
 
-If you want to contribute documentation, please go to [static-php/static-php-cli-docs](https://github.com/static-php/static-php-cli-docs).
+If you want to contribute documentation, please just edit in `docs/`.
 
 Now there is a [static-php](https://github.com/static-php) organization, which is used to store the repo related to the project.
 
 ## Sponsor this project
 
-You can sponsor my project on [this page](https://github.com/crazywhalecc/crazywhalecc/blob/master/FUNDING.md). A portion of your donation will be used to maintain the **static-php.dev** server.
+You can sponsor me or my project from [GitHub Sponsor](https://github.com/crazywhalecc). A portion of your donation will be used to maintain the **static-php.dev** server.
+
+**Special thanks to sponsors below**:
+
+<a href="https://beyondco.de/"><img src="/docs/public/images/beyondcode-seeklogo.png" width="300" alt="Beyond Code Logo" /></a>
+
+<a href="https://nativephp.com/"><img src="/docs/public/images/nativephp-logo.svg" width="300" alt="NativePHP Logo" /></a>
 
 ## Open-Source License
 

bin/docker-entrypoint.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+TARGET_DIR="/app/pkgroot/$(uname -m)-linux"
+BACKUP_DIR="/app/pkgroot-private"
+# copy private pkgroot to pkgroot if pkgroot is empty
+if [ ! -d "$TARGET_DIR" ] || [ -z "$(ls -A "$TARGET_DIR")" ]; then
+    echo "* Copying private pkgroot to pkgroot ..."
+    rm -rf "$TARGET_DIR"
+    cp -r "$BACKUP_DIR" "$TARGET_DIR"
+fi
+exec "$@"

bin/setup-runtime

@@ -25,7 +25,7 @@ __DIR__=$(cd "$(dirname "$0")" && pwd)
 __PROJECT__=$(cd "${__DIR__}"/../ && pwd)
 
 # set download dir
-__PHP_RUNTIME_URL__="https://dl.static-php.dev/static-php-cli/bulk/php-8.2.13-cli-${__OS_FIXED__}-${__ARCH__}.tar.gz"
+__PHP_RUNTIME_URL__="https://dl.static-php.dev/static-php-cli/bulk/php-8.4.12-cli-${__OS_FIXED__}-${__ARCH__}.tar.gz"
 __COMPOSER_URL__="https://getcomposer.org/download/latest-stable/composer.phar"
 
 # use china mirror
@@ -45,7 +45,7 @@ done
 
 case "$mirror" in
 china)
-  __PHP_RUNTIME_URL__="https://dl.static-php.dev/static-php-cli/bulk/php-8.2.13-cli-${__OS_FIXED__}-${__ARCH__}.tar.gz"
+  __PHP_RUNTIME_URL__="https://dl.static-php.dev/static-php-cli/bulk/php-8.4.12-cli-${__OS_FIXED__}-${__ARCH__}.tar.gz"
   __COMPOSER_URL__="https://mirrors.tencent.com/composer/composer.phar"
   ;;
 
@@ -61,7 +61,7 @@ test -f "${__PROJECT__}"/downloads/runtime.tar.gz || { echo "Downloading $__PHP_
 test -f "${__DIR__}"/php || { tar -xf "${__PROJECT__}"/downloads/runtime.tar.gz -C "${__DIR__}"/ ; }
 chmod +x "${__DIR__}"/php
 # download composer
-test -f "${__DIR__}"/composer || curl -#fSL -o "${__DIR__}"/composer "$__COMPOSER_URL__"
+test -f "${__DIR__}"/composer || { echo "Downloading Composer from $__COMPOSER_URL__" && curl -#fSL -o "${__DIR__}"/composer "$__COMPOSER_URL__" ; }
 chmod +x "${__DIR__}"/composer
 # sanity check for php and composer
 "${__DIR__}"/php -v >/dev/null || { echo "Failed to run php" && exit 1; }

bin/setup-runtime.ps1

@@ -51,10 +51,11 @@ if ($action -eq 'add-path') {
 }
 
 # get php 8.1 specific version
-$API = (Invoke-WebRequest -Uri "https://www.php.net/releases/index.php?json&version=8.1") | ConvertFrom-Json
 
 # php windows download
-$PHPRuntimeUrl = "https://windows.php.net/downloads/releases/php-" + $API.version + "-Win32-vs16-x64.zip"
+$PHPRuntimeUrl = "https://windows.php.net/downloads/releases/archives/php-8.4.4-nts-Win32-vs17-x64.zip"
+Write-Host "Downloading PHP from: " -NoNewline
+Write-Host $PHPRuntimeUrl -ForegroundColor Cyan
 $ComposerUrl = "https://getcomposer.org/download/latest-stable/composer.phar"
 
 # create dir

bin/spc

@@ -4,6 +4,11 @@
 use SPC\ConsoleApplication;
 use SPC\exception\ExceptionHandler;
 
+// Load custom php if exists
+if (PHP_OS_FAMILY !== 'Windows' && PHP_BINARY !== (__DIR__ . '/php') && file_exists(__DIR__ . '/php') && is_executable(__DIR__ . '/php')) {
+    pcntl_exec(__DIR__ . '/php', $argv);
+}
+
 if (file_exists(dirname(__DIR__) . '/vendor/autoload.php')) {
     // Current: ./bin (git/project mode)
     require_once dirname(__DIR__) . '/vendor/autoload.php';
@@ -17,6 +22,11 @@ if (PHP_OS_FAMILY === 'Windows' && Phar::running()) {
     exec('CHCP 65001');
 }
 
+// Print deprecation notice on PHP < 8.4, use red and highlight background
+if (PHP_VERSION_ID < 80400) {
+    echo "\e[43mDeprecation Notice: PHP < 8.4 is deprecated, please upgrade your PHP version.\e[0m\n";
+}
+
 try {
     (new ConsoleApplication())->run();
 } catch (Exception $e) {

bin/spc-alpine-docker

@@ -1,11 +1,14 @@
-#!/usr/bin/env sh
+#!/usr/bin/env bash
+
+set -e
 
 # This file is using docker to run commands
+SPC_DOCKER_VERSION=v6
 
 # Detect docker can run
 if ! which docker >/dev/null; then
-  echo "Docker is not installed, please install docker first !"
-  exit 1
+    echo "Docker is not installed, please install docker first !"
+    exit 1
 fi
 DOCKER_EXECUTABLE="docker"
 # shellcheck disable=SC2046
@@ -21,27 +24,48 @@ if [ $(id -u) -ne 0 ]; then
     fi
 fi
 
-
-
-# to check if qemu-docker run
-if [ "$SPC_USE_ARCH" = "" ]; then
-    SPC_USE_ARCH=x86_64
+# Convert uname to gnu arch
+CURRENT_ARCH=$(uname -m)
+if [ "$CURRENT_ARCH" = "arm64" ]; then
+    CURRENT_ARCH=aarch64
 fi
+if [ -z "$SPC_USE_ARCH" ]; then
+    SPC_USE_ARCH=$CURRENT_ARCH
+fi
+# parse SPC_USE_ARCH
 case $SPC_USE_ARCH in
-x86_64)
-    ALPINE_FROM=alpine:edge
+x86_64|amd64)
+    SPC_USE_ARCH=x86_64
+    if [ "$CURRENT_ARCH" != "x86_64" ]; then
+        PLATFORM_ARG="--platform linux/amd64"
+        ALPINE_FROM=multiarch/alpine:x86_64-edge
+    fi
     ;;
-aarch64)
-    ALPINE_FROM=multiarch/alpine:aarch64-edge
-    # shellcheck disable=SC2039
-    echo -e "\e[033m* Using different arch needs to setup qemu-static for docker !\e[0m"
-    $DOCKER_EXECUTABLE run --rm --privileged multiarch/qemu-user-static:register --reset > /dev/null
+aarch64|arm64)
+    SPC_USE_ARCH=aarch64
+    if [ "$CURRENT_ARCH" != "aarch64" ]; then
+        PLATFORM_ARG="--platform linux/arm64"
+        ALPINE_FROM=multiarch/alpine:aarch64-edge
+    fi
     ;;
 *)
     echo "Current arch is not supported to run in docker: $SPC_USE_ARCH"
     exit 1
     ;;
 esac
+# if ALPINE_FROM is not set, use alpine:3.21
+if [ -z "$ALPINE_FROM" ]; then
+    ALPINE_FROM=alpine:3.21
+fi
+if [ "$SPC_USE_ARCH" != "$CURRENT_ARCH" ]; then
+    echo "* Using different arch needs to setup qemu-static for docker !"
+    ALPINE_FROM=multiarch/alpine:$SPC_USE_ARCH-edge
+    if [ "$(uname -s)" = "Linux" ]; then
+        $DOCKER_EXECUTABLE run --rm --privileged multiarch/qemu-user-static:register --reset > /dev/null
+    fi
+else
+    ALPINE_FROM=alpine:3.21
+fi
 
 if [ "$SPC_USE_MIRROR" = "yes" ]; then
     SPC_USE_MIRROR="RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories"
@@ -50,12 +74,13 @@ else
 fi
 
 # Detect docker env is setup
-if ! $DOCKER_EXECUTABLE images | grep -q cwcc-spc-$SPC_USE_ARCH; then
+if ! $DOCKER_EXECUTABLE images | grep -q cwcc-spc-$SPC_USE_ARCH-$SPC_DOCKER_VERSION; then
     echo "Docker container does not exist. Building docker image ..."
-    $DOCKER_EXECUTABLE build -t cwcc-spc-$SPC_USE_ARCH -f- . <<EOF
+    $DOCKER_EXECUTABLE build $PLATFORM_ARG -t cwcc-spc-$SPC_USE_ARCH-$SPC_DOCKER_VERSION -f- . <<EOF
 FROM $ALPINE_FROM
 $SPC_USE_MIRROR
 RUN apk update; \
+    apk upgrade -a; \
     apk add --no-cache \
         autoconf \
         automake \
@@ -78,26 +103,32 @@ RUN apk update; \
         linux-headers \
         m4 \
         make \
-        php82 \
-        php82-common \
-        php82-pcntl \
-        php82-phar \
-        php82-posix \
-        php82-sodium \
-        php82-tokenizer \
-        php82-dom \
-        php82-xml \
-        php82-xmlwriter \
-        composer \
         pkgconfig \
+        re2c \
         wget \
-        xz
+        xz \
+        gettext-dev \
+        binutils-gold
+
+RUN curl -#fSL https://dl.static-php.dev/static-php-cli/bulk/php-8.4.4-cli-linux-\$(uname -m).tar.gz | tar -xz -C /usr/local/bin && \
+    chmod +x /usr/local/bin/php
+
+RUN curl -#fSL https://getcomposer.org/download/latest-stable/composer.phar -o /usr/local/bin/composer && \
+    chmod +x /usr/local/bin/composer
 
 WORKDIR /app
 ADD ./src /app/src
 COPY ./composer.* /app/
 ADD ./bin /app/bin
-RUN composer install --no-dev --classmap-authoritative
+RUN composer install --no-dev
+ADD ./config /app/config
+RUN bin/spc doctor --auto-fix
+RUN bin/spc install-pkg upx
+
+RUN mv /app/pkgroot/\$(uname -m)-linux /app/pkgroot-private
+ADD bin/docker-entrypoint.sh /bin/docker-entrypoint.sh
+RUN chmod +x /bin/docker-entrypoint.sh
+ENTRYPOINT ["/bin/docker-entrypoint.sh"]
 EOF
 fi
 
@@ -108,6 +139,89 @@ else
     INTERACT=''
 fi
 
+# Mounting volumes
+MOUNT_LIST=""
+# shellcheck disable=SC2089
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/config:/app/config"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/src:/app/src"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/buildroot:/app/buildroot"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/source:/app/source"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/dist:/app/dist"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/downloads:/app/downloads"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/pkgroot:/app/pkgroot"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/log:/app/log"
+if [ -f "$(pwd)/craft.yml" ]; then
+    MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/craft.yml:/app/craft.yml"
+fi
+
+# Environment variable passthrough
+ENV_LIST=""
+ENV_LIST="$ENV_LIST -e SPC_FIX_DEPLOY_ROOT="$(pwd)""
+if [ ! -z "$GITHUB_TOKEN" ]; then
+    ENV_LIST="$ENV_LIST -e GITHUB_TOKEN=$GITHUB_TOKEN"
+fi
+
+# Intercept and rewrite --with-frankenphp-app option, and mount host path to /app/app
+FRANKENPHP_APP_PATH=""
+NEW_ARGS=()
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --with-frankenphp-app=*)
+            FRANKENPHP_APP_PATH="${1#*=}"
+            NEW_ARGS+=("--with-frankenphp-app=/app/app")
+            shift
+            ;;
+        --with-frankenphp-app)
+            if [ -n "${2:-}" ]; then
+                FRANKENPHP_APP_PATH="$2"
+                NEW_ARGS+=("--with-frankenphp-app=/app/app")
+                shift 2
+            else
+                NEW_ARGS+=("$1")
+                shift
+            fi
+            ;;
+        *)
+            NEW_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Normalize the path and add mount if provided
+if [ -n "$FRANKENPHP_APP_PATH" ]; then
+    # expand ~ to $HOME
+    if [ "${FRANKENPHP_APP_PATH#~}" != "$FRANKENPHP_APP_PATH" ]; then
+        FRANKENPHP_APP_PATH="$HOME${FRANKENPHP_APP_PATH#~}"
+    fi
+    # make absolute if relative
+    case "$FRANKENPHP_APP_PATH" in
+        /*) ABS_APP_PATH="$FRANKENPHP_APP_PATH" ;;
+        *) ABS_APP_PATH="$(pwd)/$FRANKENPHP_APP_PATH" ;;
+    esac
+    MOUNT_LIST="$MOUNT_LIST -v $ABS_APP_PATH:/app/app"
+fi
+
 # Run docker
 # shellcheck disable=SC2068
-$DOCKER_EXECUTABLE run --rm $INTERACT -e SPC_FIX_DEPLOY_ROOT="$(pwd)" -v "$(pwd)"/config:/app/config -v "$(pwd)"/src:/app/src -v "$(pwd)"/buildroot:/app/buildroot -v "$(pwd)"/source:/app/source -v "$(pwd)"/downloads:/app/downloads cwcc-spc-$SPC_USE_ARCH bin/spc $@
+# shellcheck disable=SC2086
+# shellcheck disable=SC2090
+if [ "$SPC_DOCKER_DEBUG" = "yes" ]; then
+    echo "* Debug mode enabled, run docker in interactive mode."
+    echo "* You can use 'exit' to exit the docker container."
+    echo "* You can use 'bin/spc' like normal builds."
+    echo "*"
+    echo "*    Mounted directories:"
+    echo "*    ./config:    $(pwd)/config"
+    echo "*    ./src:       $(pwd)/src"
+    echo "*    ./buildroot: $(pwd)/buildroot"
+    echo "*    ./source:    $(pwd)/source"
+    echo "*    ./dist:      $(pwd)/dist"
+    echo "*    ./downloads: $(pwd)/downloads"
+    echo "*    ./pkgroot:   $(pwd)/pkgroot"
+    echo "*"
+    set -ex
+    $DOCKER_EXECUTABLE run $PLATFORM_ARG --rm $INTERACT $ENV_LIST $MOUNT_LIST cwcc-spc-$SPC_USE_ARCH-$SPC_DOCKER_VERSION /bin/bash
+else
+    $DOCKER_EXECUTABLE run $PLATFORM_ARG --rm $INTERACT $ENV_LIST $MOUNT_LIST cwcc-spc-$SPC_USE_ARCH-$SPC_DOCKER_VERSION bin/spc "${NEW_ARGS[@]}"
+fi

bin/spc-gnu-docker

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+
+set -e
+
+# This file is using docker to run commands
+SPC_DOCKER_VERSION=v6
+
+# Detect docker can run
+if ! which docker >/dev/null; then
+  echo "Docker is not installed, please install docker first !"
+  exit 1
+fi
+DOCKER_EXECUTABLE="docker"
+# shellcheck disable=SC2046
+if [ $(id -u) -ne 0 ]; then
+    if ! docker info > /dev/null 2>&1; then
+        if [ "$SPC_USE_SUDO" != "yes" ] && [ "$SPC_DOCKER_DEBUG" != "yes" ]; then
+            echo "Docker command requires sudo"
+            # shellcheck disable=SC2039
+            echo -n 'To use sudo to run docker, run "export SPC_USE_SUDO=yes" and run command again'
+            exit 1
+        fi
+        DOCKER_EXECUTABLE="sudo docker"
+    fi
+fi
+
+# Convert uname to gnu arch
+CURRENT_ARCH=$(uname -m)
+if [ "$CURRENT_ARCH" = "arm64" ]; then
+    CURRENT_ARCH=aarch64
+fi
+if [ -z "$SPC_USE_ARCH" ]; then
+    SPC_USE_ARCH=$CURRENT_ARCH
+fi
+# parse SPC_USE_ARCH
+case $SPC_USE_ARCH in
+x86_64|amd64)
+    SPC_USE_ARCH=x86_64
+    SPC_USE_ARCH_DOCKER=amd64
+    if [ "$CURRENT_ARCH" != "x86_64" ]; then
+        PLATFORM_ARG="--platform linux/amd64"
+    fi
+    ;;
+aarch64|arm64)
+    SPC_USE_ARCH=aarch64
+    SPC_USE_ARCH_DOCKER=arm64
+    if [ "$CURRENT_ARCH" != "aarch64" ]; then
+        PLATFORM_ARG="--platform linux/arm64"
+    fi
+    ;;
+*)
+    echo "Current arch is not supported to run in docker: $SPC_USE_ARCH"
+    exit 1
+    ;;
+esac
+# detect if we need to use qemu-static
+if [ "$SPC_USE_ARCH" != "$CURRENT_ARCH" ]; then
+    if [ "$(uname -s)" = "Linux" ]; then
+        echo "* Using different arch needs to setup qemu-static for docker !"
+        $DOCKER_EXECUTABLE run --rm --privileged multiarch/qemu-user-static --reset -p yes > /dev/null
+    fi
+fi
+
+# Detect docker env is setup
+if ! $DOCKER_EXECUTABLE images | grep -q cwcc-spc-gnu-$SPC_USE_ARCH-$SPC_DOCKER_VERSION; then
+    echo "Docker container does not exist. Building docker image ..."
+    $DOCKER_EXECUTABLE buildx build $PLATFORM_ARG -t cwcc-spc-gnu-$SPC_USE_ARCH-$SPC_DOCKER_VERSION -f- . <<EOF
+FROM centos:7
+RUN sed -i 's/mirror.centos.org/vault.centos.org/g' /etc/yum.repos.d/*.repo && \
+    sed -i 's/^#.*baseurl=http/baseurl=http/g' /etc/yum.repos.d/*.repo && \
+    sed -i 's/^mirrorlist=http/#mirrorlist=http/g' /etc/yum.repos.d/*.repo
+RUN yum clean all && \
+    yum makecache && \
+    yum update -y && \
+    localedef -c -i en_US -f UTF-8 en_US.UTF-8
+
+RUN yum install -y centos-release-scl
+
+RUN if [ "$SPC_USE_ARCH" = "aarch64" ]; then \
+        sed -i 's|mirror.centos.org/centos|vault.centos.org/altarch|g' /etc/yum.repos.d/CentOS-SCLo-scl-rh.repo ; \
+        sed -i 's|mirror.centos.org/centos|vault.centos.org/altarch|g' /etc/yum.repos.d/CentOS-SCLo-scl.repo ; \
+    else \
+        sed -i 's/mirror.centos.org/vault.centos.org/g' /etc/yum.repos.d/*.repo ; \
+    fi
+RUN sed -i 's/^#.*baseurl=http/baseurl=http/g' /etc/yum.repos.d/*.repo && \
+    sed -i 's/^mirrorlist=http/#mirrorlist=http/g' /etc/yum.repos.d/*.repo && \
+    sed -i 's|http://|https://|g' /etc/yum.repos.d/*.repo
+
+RUN yum update -y && \
+    yum install -y devtoolset-10-gcc-* devtoolset-10-libatomic-devel
+RUN echo "source scl_source enable devtoolset-10" >> /etc/bashrc
+RUN source /etc/bashrc
+RUN yum install -y which
+
+RUN curl -o cmake.tgz -#fSL https://github.com/Kitware/CMake/releases/download/v3.31.4/cmake-3.31.4-linux-$SPC_USE_ARCH.tar.gz && \
+    mkdir /cmake && \
+    tar -xzf cmake.tgz -C /cmake --strip-components 1
+
+WORKDIR /app
+COPY ./composer.* /app/
+ADD ./bin/setup-runtime /app/bin/setup-runtime
+ADD ./bin/spc /app/bin/spc
+RUN /app/bin/setup-runtime
+ADD ./src /app/src
+RUN /app/bin/php /app/bin/composer install --no-dev
+ENV SPC_LIBC=glibc
+ENV PATH="/app/bin:/cmake/bin:/opt/rh/devtoolset-10/root/usr/bin:\$PATH"
+
+ADD ./config /app/config
+RUN CC=gcc bin/spc doctor --auto-fix --debug
+RUN bin/spc install-pkg upx
+RUN if [ -f /app/buildroot/bin/re2c ]; then \
+        cp /app/buildroot/bin/re2c /usr/local/bin/re2c ;\
+    fi
+
+RUN curl -o make.tgz -fsSL https://ftp.gnu.org/gnu/make/make-4.4.tar.gz && \
+    tar -zxvf make.tgz && \
+    cd make-4.4 && \
+    ./configure && \
+    make && \
+    make install && \
+    ln -sf /usr/local/bin/make /usr/bin/make
+
+RUN curl -o automake.tgz -fsSL https://ftp.gnu.org/gnu/automake/automake-1.17.tar.xz && \
+    tar -xvf automake.tgz && \
+    cd automake-1.17 && \
+    ./configure && \
+    make && \
+    make install && \
+    ln -sf /usr/local/bin/automake /usr/bin/automake
+
+RUN mv /app/pkgroot/\$(uname -m)-linux /app/pkgroot-private
+ADD bin/docker-entrypoint.sh /bin/docker-entrypoint.sh
+RUN chmod +x /bin/docker-entrypoint.sh
+ENTRYPOINT ["/bin/docker-entrypoint.sh"]
+EOF
+fi
+
+# Check if in ci (local terminal can execute with -it)
+if [ -t 0 ]; then
+    INTERACT=-it
+else
+    INTERACT=''
+fi
+
+# Mounting volumes
+MOUNT_LIST=""
+# shellcheck disable=SC2089
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/config:/app/config"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/src:/app/src"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/buildroot:/app/buildroot"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/source:/app/source"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/dist:/app/dist"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/downloads:/app/downloads"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/pkgroot:/app/pkgroot"
+MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/log:/app/log"
+if [ -f "$(pwd)/craft.yml" ]; then
+    MOUNT_LIST="$MOUNT_LIST -v ""$(pwd)""/craft.yml:/app/craft.yml"
+fi
+
+# Apply env in temp env file
+echo 'SPC_DEFAULT_C_FLAGS=-fPIC' > /tmp/spc-gnu-docker.env
+echo 'SPC_LIBC=glibc' >> /tmp/spc-gnu-docker.env
+
+# Environment variable passthrough
+ENV_LIST=""
+ENV_LIST="$ENV_LIST -e SPC_FIX_DEPLOY_ROOT="$(pwd)""
+if [ ! -z "$GITHUB_TOKEN" ]; then
+    ENV_LIST="$ENV_LIST -e GITHUB_TOKEN=$GITHUB_TOKEN"
+fi
+
+# Intercept and rewrite --with-frankenphp-app option, and mount host path to /app/app
+FRANKENPHP_APP_PATH=""
+NEW_ARGS=()
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --with-frankenphp-app=*)
+            FRANKENPHP_APP_PATH="${1#*=}"
+            NEW_ARGS+=("--with-frankenphp-app=/app/app")
+            shift
+            ;;
+        --with-frankenphp-app)
+            if [ -n "${2:-}" ]; then
+                FRANKENPHP_APP_PATH="$2"
+                NEW_ARGS+=("--with-frankenphp-app=/app/app")
+                shift 2
+            else
+                NEW_ARGS+=("$1")
+                shift
+            fi
+            ;;
+        *)
+            NEW_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+
+# Normalize the path and add mount if provided
+if [ -n "$FRANKENPHP_APP_PATH" ]; then
+    # expand ~ to $HOME
+    if [ "${FRANKENPHP_APP_PATH#~}" != "$FRANKENPHP_APP_PATH" ]; then
+        FRANKENPHP_APP_PATH="$HOME${FRANKENPHP_APP_PATH#~}"
+    fi
+    # make absolute if relative
+    case "$FRANKENPHP_APP_PATH" in
+        /*) ABS_APP_PATH="$FRANKENPHP_APP_PATH" ;;
+        *) ABS_APP_PATH="$(pwd)/$FRANKENPHP_APP_PATH" ;;
+    esac
+    MOUNT_LIST="$MOUNT_LIST -v $ABS_APP_PATH:/app/app"
+fi
+
+# Run docker
+# shellcheck disable=SC2068
+# shellcheck disable=SC2086
+# shellcheck disable=SC2090
+
+if [ "$SPC_DOCKER_DEBUG" = "yes" ]; then
+    echo "* Debug mode enabled, run docker in interactive mode."
+    echo "* You can use 'exit' to exit the docker container."
+    echo "* You can use 'bin/spc' like normal builds."
+    echo "*"
+    echo "*    Mounted directories:"
+    echo "*    ./config:    $(pwd)/config"
+    echo "*    ./src:       $(pwd)/src"
+    echo "*    ./buildroot: $(pwd)/buildroot"
+    echo "*    ./source:    $(pwd)/source"
+    echo "*    ./dist:      $(pwd)/dist"
+    echo "*    ./downloads: $(pwd)/downloads"
+    echo "*    ./pkgroot:   $(pwd)/pkgroot"
+    echo "*"
+    set -ex
+    $DOCKER_EXECUTABLE run $PLATFORM_ARG --privileged --rm -it $INTERACT $ENV_LIST --env-file /tmp/spc-gnu-docker.env $MOUNT_LIST cwcc-spc-gnu-$SPC_USE_ARCH-$SPC_DOCKER_VERSION /bin/bash
+else
+    $DOCKER_EXECUTABLE run $PLATFORM_ARG --rm $INTERACT $ENV_LIST --env-file /tmp/spc-gnu-docker.env $MOUNT_LIST cwcc-spc-gnu-$SPC_USE_ARCH-$SPC_DOCKER_VERSION bin/spc "${NEW_ARGS[@]}"
+fi

box.json

@@ -4,6 +4,7 @@
   "blacklist": [
     ".github"
   ],
+  "compression": "GZ",
   "directories": [
     "config",
     "src",

composer.json

@@ -9,20 +9,23 @@
         }
     ],
     "require": {
-        "php": ">= 8.1",
+        "php": ">= 8.3",
         "ext-mbstring": "*",
+        "ext-simplexml": "*",
+        "ext-zlib": "*",
         "laravel/prompts": "^0.1.12",
         "symfony/console": "^5.4 || ^6 || ^7",
-        "zhamao/logger": "^1.0"
+        "symfony/process": "^7.2",
+        "symfony/yaml": "^7.2",
+        "zhamao/logger": "^1.1.3"
     },
     "require-dev": {
-        "captainhook/captainhook": "^5.10",
-        "captainhook/plugin-composer": "^5.3",
-        "friendsofphp/php-cs-fixer": "^3.25",
-        "humbug/box": "^4.5",
-        "nunomaduro/collision": "^7.8",
+        "captainhook/captainhook-phar": "^5.23",
+        "captainhook/hook-installer": "^1.0",
+        "friendsofphp/php-cs-fixer": "^3.60",
+        "humbug/box": "^4.5.0 || ^4.6.0",
         "phpstan/phpstan": "^1.10",
-        "phpunit/phpunit": "^10.3 || ^9"
+        "phpunit/phpunit": "^10.3 || ^9.5"
     },
     "autoload": {
         "psr-4": {
@@ -50,7 +53,9 @@
     "config": {
         "allow-plugins": {
             "phpstan/extension-installer": true,
-            "captainhook/plugin-composer": true
+            "captainhook/hook-installer": true,
+            "captainhook/plugin-composer": true,
+            "captainhook/captainhook-phar": true
         },
         "optimize-autoloader": true,
         "sort-packages": true

config/env.ini

@@ -0,0 +1,159 @@
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; static-php-cli (spc) env configuration
+;
+; This file is used to set default env vars for static-php-cli build.
+; As dynamic build process, some of these vars can be overwritten by CLI options.
+; And you can also overwrite these vars by setting them in your shell environment.
+; The value should be changed only if you know what you are doing. Otherwise, please leave them as default.
+;
+; We need to use some pre-defined internal env vars, like `BUILD_ROOT_PATH`, `DOWNLOAD_PATH`, etc.
+; Please note that these vars cannot be defined in this file, they should only be defined before static-php-cli running.
+;
+; Here's a list of env vars, these variables will be defined if not defined:
+;
+;   BUILD_ROOT_PATH:    the root path of the build process. (default: `$(pwd)/buildroot`)
+;   BUILD_INCLUDE_PATH: the path of the include files. (default: `$BUILD_ROOT_PATH/include`)
+;   BUILD_LIB_PATH:     the path of the lib files. (default: `$BUILD_ROOT_PATH/lib`)
+;   BUILD_BIN_PATH:     the path of the bin files. (default: `$BUILD_ROOT_PATH/bin`)
+;   BUILD_MODULES_PATH: the path of the php modules (shared extensions) files. (default: `$BUILD_ROOT_PATH/modules`)
+;   PKG_ROOT_PATH:      the root path of the package files. (default: `$(pwd)/pkgroot/$GNU_ARCH-{darwin|linux|windows}`)
+;   SOURCE_PATH:        the path of the source files. (default: `$(pwd)/source`)
+;   DOWNLOAD_PATH:      the path of the download files. (default: `$(pwd)/downloads`)
+;   PATH:               (*nix only) static-php-cli will add `$BUILD_BIN_PATH` to PATH.
+;   PKG_CONFIG_PATH:    (*nix only) static-php-cli will set `$BUILD_LIB_PATH/pkgconfig` to PKG_CONFIG_PATH.
+;
+; Here's a list of env vars, these variables is defined in SPC and cannot be changed anywhere:
+;
+;   SPC_VERSION:            the version of static-php-cli.
+;   WORKING_DIR:            the working directory of the build process. (default: `$(pwd)`)
+;   ROOT_DIR:               the root directory of static-php-cli. (default: `/path/to/static-php-cli`, when running in phar or micro mode: `phar://path/to/spc.phar`)
+;   CPU_COUNT:              the count of the CPU cores. (default: `$(nproc)`)
+;   SPC_ARCH:               the arch of the current system, for some libraries needed `--host=XXX` args. (default: `$(uname -m)`, e.g. `x86_64`, `aarch64`, `arm64`)
+;   GNU_ARCH:               the GNU arch of the current system. (default: `$(uname -m)`, e.g. `x86_64`, `aarch64`)
+;   MAC_ARCH:               the MAC arch of the current system. (default: `$(uname -m)`, e.g. `x86_64`, `arm64`)
+;   PKG_CONFIG:             (*nix only) static-php-cli will set `$BUILD_BIN_PATH/pkg-config` to PKG_CONFIG.
+;   SPC_LINUX_DEFAULT_CC:   (linux only) the default compiler for linux. (For alpine linux: `gcc`, default: `$GNU_ARCH-linux-musl-gcc`)
+;   SPC_LINUX_DEFAULT_CXX:  (linux only) the default c++ compiler for linux. (For alpine linux: `g++`, default: `$GNU_ARCH-linux-musl-g++`)
+;   SPC_LINUX_DEFAULT_AR:   (linux only) the default archiver for linux. (For alpine linux: `ar`, default: `$GNU_ARCH-linux-musl-ar`)
+;   SPC_EXTRA_PHP_VARS:     (linux only) the extra vars for building php, used in `configure` and `make` command.
+
+[global]
+; Build concurrency for make -jN, default is CPU_COUNT, this value are used in every libs.
+SPC_CONCURRENCY=${CPU_COUNT}
+; Ignore PHP version check before building some extensions
+SPC_SKIP_PHP_VERSION_CHECK="no"
+; Ignore some check item for bin/spc doctor command, comma separated (e.g. SPC_SKIP_DOCTOR_CHECK_ITEMS="if homebrew has installed")
+SPC_SKIP_DOCTOR_CHECK_ITEMS=""
+; extra modules that xcaddy will include in the FrankenPHP build
+SPC_CMD_VAR_FRANKENPHP_XCADDY_MODULES="--with github.com/dunglas/mercure/caddy --with github.com/dunglas/vulcain/caddy --with github.com/dunglas/caddy-cbrotli"
+; The display message for php version output (PHP >= 8.4 available)
+PHP_BUILD_PROVIDER="static-php-cli ${SPC_VERSION}"
+
+; EXTENSION_DIR where the built php will look for extension when a .ini instructs to load them
+; only useful for builds targeting not pure-static linking
+; default paths
+; Ubuntu/Debian: /usr/lib/php/{PHP_VERSION}/
+; RHEL: /usr/lib64/php/modules
+; Alpine: /usr/lib/php{PHP_VERSION}/modules
+; where {PHP_VERSION} is 84 for php 8.4
+; EXTENSION_DIR=
+
+[windows]
+; build target: win7-static
+SPC_TARGET=native-windows
+; php-sdk-binary-tools path
+PHP_SDK_PATH="${WORKING_DIR}\php-sdk-binary-tools"
+; upx executable path
+UPX_EXEC="${PKG_ROOT_PATH}\bin\upx.exe"
+; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
+SPC_MICRO_PATCHES=static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream,cli_static,win32_api
+
+[linux]
+; Linux can use different build toolchains.
+; - musl (default, when SPC_LIBC=musl): used for general linux distros, can build `musl` (statically linked) only.
+; - zig (will become default): usable on all Linux distros, can build `-musl`, `arch-linux-musl -dynamic` and `arch-linux-gnu` targets. Can specify version such as `x86_64-linux-gnu.2.17`.
+; - musl-native: used for alpine linux, can build `musl` and `musl -dynamic` target.
+; - gnu-native: used for general linux distros, can build gnu target for the installed glibc version only.
+
+; option to specify the target, superceded by SPC_TARGET if set
+SPC_LIBC=musl
+; uncomment to link libc dynamically on musl
+; SPC_MUSL_DYNAMIC=true
+
+; Recommended: specify your target here. Zig toolchain will be used.
+; examples:
+; `native-native-gnu`           - links against glibc, current OS version
+; `native-native-gnu.2.17`      - links against glibc, version 2.17
+; `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=
+
+; compiler environments
+CC=${SPC_LINUX_DEFAULT_CC}
+CXX=${SPC_LINUX_DEFAULT_CXX}
+AR=${SPC_LINUX_DEFAULT_AR}
+LD=${SPC_LINUX_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=""
+; upx executable path
+UPX_EXEC=${PKG_ROOT_PATH}/bin/upx
+; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
+SPC_MICRO_PATCHES=cli_checks,disable_huge_page
+
+; *** default build command for building php ***
+; 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"
+
+; *** 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}"
+; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.so
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
+
+; optional, path to openssl conf. This affects where openssl will look for the default CA.
+; default on Debian/Alpine: /etc/ssl, default on RHEL: /etc/pki/tls
+OPENSSLDIR=""
+
+[macos]
+; build target: macho or macho (possibly we could support macho-universal in the future)
+; Currently we do not support universal and cross-compilation for macOS.
+SPC_TARGET=native-macos
+; compiler environments
+CC=clang
+CXX=clang++
+AR=ar
+LD=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=""
+; phpmicro patches, for more info, see: https://github.com/easysoft/phpmicro/tree/master/patches
+SPC_MICRO_PATCHES=cli_checks,macos_iconv
+
+; *** default build command for building php ***
+; 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"
+
+; *** 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}"
+; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.so
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
+; minimum compatible macOS version (LLVM vars, availability not guaranteed)
+MACOSX_DEPLOYMENT_TARGET=12.0
+
+[freebsd]
+; compiler environments
+CC=clang
+CXX=clang++

config/lib.json

@@ -1,10 +1,58 @@
 {
+    "lib-base": {
+        "type": "root"
+    },
+    "php": {
+        "type": "root",
+        "source": "php-src",
+        "lib-depends": [
+            "lib-base",
+            "micro",
+            "frankenphp"
+        ],
+        "lib-depends-macos": [
+            "lib-base",
+            "micro",
+            "libxml2",
+            "frankenphp"
+        ],
+        "lib-suggests-linux": [
+            "libacl",
+            "brotli",
+            "watcher"
+        ],
+        "lib-suggests-macos": [
+            "brotli",
+            "watcher"
+        ]
+    },
+    "frankenphp": {
+        "source": "frankenphp",
+        "type": "target"
+    },
+    "micro": {
+        "type": "target",
+        "source": "micro"
+    },
+    "pkg-config": {
+        "type": "package",
+        "source": "pkg-config",
+        "bin-unix": [
+            "pkg-config"
+        ]
+    },
+    "attr": {
+        "source": "attr",
+        "static-libs-unix": [
+            "libattr.a"
+        ]
+    },
     "brotli": {
         "source": "brotli",
-        "static-libs-unix": [
-            "libbrotlidec.a",
-            "libbrotlienc.a",
-            "libbrotlicommon.a"
+        "pkg-configs": [
+            "libbrotlicommon",
+            "libbrotlidec",
+            "libbrotlienc"
         ],
         "static-libs-windows": [
             "brotlicommon.lib",
@@ -21,10 +69,8 @@
             "libbz2.a"
         ],
         "static-libs-windows": [
-            [
-                "libbz2.lib",
-                "libbz2_a.lib"
-            ]
+            "libbz2.lib",
+            "libbz2_a.lib"
         ],
         "headers": [
             "bzlib.h"
@@ -46,7 +92,6 @@
             "zlib"
         ],
         "lib-depends-windows": [
-            "openssl",
             "zlib",
             "libssh2",
             "nghttp2"
@@ -55,7 +100,13 @@
             "libssh2",
             "brotli",
             "nghttp2",
-            "zstd"
+            "nghttp3",
+            "ngtcp2",
+            "zstd",
+            "libcares",
+            "ldap",
+            "idn2",
+            "krb5"
         ],
         "lib-suggests-windows": [
             "brotli",
@@ -67,11 +118,23 @@
             "SystemConfiguration"
         ]
     },
+    "fastlz": {
+        "source": "fastlz",
+        "static-libs-unix": [
+            "libfastlz.a"
+        ],
+        "headers": [
+            "fastlz/fastlz.h"
+        ]
+    },
     "freetype": {
         "source": "freetype",
         "static-libs-unix": [
             "libfreetype.a"
         ],
+        "static-libs-windows": [
+            "libfreetype_a.lib"
+        ],
         "headers-unix": [
             "freetype2/freetype/freetype.h",
             "freetype2/ft2build.h"
@@ -80,9 +143,7 @@
             "zlib"
         ],
         "lib-suggests": [
-            "libpng",
-            "bzip2",
-            "brotli"
+            "libpng"
         ]
     },
     "gettext": {
@@ -125,35 +186,94 @@
             "gmp.h"
         ]
     },
+    "gmssl": {
+        "source": "gmssl",
+        "static-libs-unix": [
+            "libgmssl.a"
+        ],
+        "static-libs-windows": [
+            "gmssl.lib"
+        ],
+        "frameworks": [
+            "Security"
+        ]
+    },
+    "grpc": {
+        "source": "grpc",
+        "pkg-configs": [
+            "grpc"
+        ],
+        "lib-depends": [
+            "zlib",
+            "openssl",
+            "libcares"
+        ],
+        "cpp-library": true,
+        "frameworks": [
+            "CoreFoundation"
+        ]
+    },
     "icu": {
         "source": "icu",
         "cpp-library": true,
-        "static-libs-unix": [
-            "libicui18n.a",
-            "libicuio.a",
-            "libicuuc.a",
-            "libicudata.a"
+        "pkg-configs": [
+            "icu-uc",
+            "icu-i18n",
+            "icu-io"
+        ]
+    },
+    "icu-static-win": {
+        "source": "icu-static-win",
+        "static-libs-windows": [
+            "icudt.lib",
+            "icuin.lib",
+            "icuio.lib",
+            "icuuc.lib"
+        ],
+        "headers-windows": [
+            "unicode"
+        ]
+    },
+    "idn2": {
+        "source": "libidn2",
+        "pkg-configs": [
+            "libidn2"
+        ],
+        "headers": [
+            "idn2.h"
+        ],
+        "lib-suggests-unix": [
+            "libiconv",
+            "gettext",
+            "libunistring"
+        ],
+        "lib-depends-macos": [
+            "libiconv",
+            "gettext"
         ]
     },
     "imagemagick": {
         "source": "imagemagick",
-        "static-libs-unix": [
-            "libMagick++-7.Q16HDRI.a",
-            "libMagickWand-7.Q16HDRI.a",
-            "libMagickCore-7.Q16HDRI.a"
+        "cpp-library": true,
+        "pkg-configs": [
+            "Magick++-7.Q16HDRI",
+            "MagickCore-7.Q16HDRI",
+            "MagickWand-7.Q16HDRI"
         ],
         "lib-depends": [
             "zlib",
-            "libpng",
             "libjpeg",
+            "libjxl",
+            "libpng",
             "libwebp",
             "freetype",
-            "libtiff"
+            "libtiff",
+            "libheif",
+            "bzip2"
         ],
         "lib-suggests": [
             "zstd",
             "xz",
-            "bzip2",
             "libzip",
             "libxml2"
         ]
@@ -167,11 +287,43 @@
             "openssl"
         ]
     },
+    "jbig": {
+        "source": "jbig",
+        "static-libs-unix": [
+            "libjbig.a",
+            "libjbig85.a"
+        ],
+        "headers": [
+            "jbig.h",
+            "jbig85.h",
+            "jbig_ar.h"
+        ]
+    },
+    "krb5": {
+        "source": "krb5",
+        "pkg-configs": [
+            "krb5-gssapi"
+        ],
+        "headers": [
+            "krb5.h",
+            "gssapi/gssapi.h"
+        ],
+        "lib-depends": [
+            "openssl"
+        ],
+        "lib-suggests": [
+            "ldap",
+            "libedit"
+        ],
+        "frameworks": [
+            "Kerberos"
+        ]
+    },
     "ldap": {
         "source": "ldap",
-        "static-libs-unix": [
-            "liblber.a",
-            "libldap.a"
+        "pkg-configs": [
+            "ldap",
+            "lber"
         ],
         "lib-depends": [
             "openssl",
@@ -180,16 +332,57 @@
             "libsodium"
         ]
     },
+    "lerc": {
+        "source": "lerc",
+        "static-libs-unix": [
+            "libLerc.a"
+        ],
+        "cpp-library": true
+    },
+    "libacl": {
+        "source": "libacl",
+        "static-libs-unix": [
+            "libacl.a"
+        ],
+        "lib-depends": [
+            "attr"
+        ]
+    },
+    "libaom": {
+        "source": "libaom",
+        "static-libs-unix": [
+            "libaom.a"
+        ],
+        "static-libs-windows": [
+            "aom.lib"
+        ],
+        "cpp-library": true
+    },
     "libargon2": {
         "source": "libargon2",
         "static-libs-unix": [
             "libargon2.a"
+        ],
+        "lib-suggests": [
+            "libsodium"
         ]
     },
     "libavif": {
         "source": "libavif",
         "static-libs-unix": [
             "libavif.a"
+        ],
+        "static-libs-windows": [
+            "avif.lib"
+        ],
+        "lib-depends": [
+            "libaom"
+        ],
+        "lib-suggests": [
+            "libwebp",
+            "libjpeg",
+            "libxml2",
+            "libpng"
         ]
     },
     "libcares": {
@@ -200,8 +393,23 @@
         "headers-unix": [
             "ares.h",
             "ares_dns.h",
-            "ares_nameser.h",
-            "ares_rules.h"
+            "ares_nameser.h"
+        ]
+    },
+    "libde265": {
+        "source": "libde265",
+        "static-libs-unix": [
+            "libde265.a"
+        ],
+        "cpp-library": true
+    },
+    "libedit": {
+        "source": "libedit",
+        "static-libs-unix": [
+            "libedit.a"
+        ],
+        "lib-depends": [
+            "ncurses"
         ]
     },
     "libevent": {
@@ -245,6 +453,19 @@
             "fficonfig.h"
         ]
     },
+    "libheif": {
+        "source": "libheif",
+        "static-libs-unix": [
+            "libheif.a"
+        ],
+        "lib-depends": [
+            "libde265",
+            "libwebp",
+            "libaom",
+            "zlib",
+            "brotli"
+        ]
+    },
     "libiconv": {
         "source": "libiconv",
         "static-libs-unix": [
@@ -269,6 +490,27 @@
         "static-libs-unix": [
             "libjpeg.a",
             "libturbojpeg.a"
+        ],
+        "static-libs-windows": [
+            "libjpeg_a.lib"
+        ],
+        "lib-suggests-windows": [
+            "zlib"
+        ]
+    },
+    "libjxl": {
+        "source": "libjxl",
+        "pkg-configs": [
+            "libjxl",
+            "libjxl_cms",
+            "libjxl_threads",
+            "libhwy"
+        ],
+        "lib-depends": [
+            "brotli",
+            "libjpeg",
+            "libpng",
+            "libwebp"
         ]
     },
     "liblz4": {
@@ -277,11 +519,24 @@
             "liblz4.a"
         ]
     },
+    "libmaxminddb": {
+        "source": "libmaxminddb",
+        "static-libs-unix": [
+            "libmaxminddb.a"
+        ],
+        "headers": [
+            "maxminddb.h",
+            "maxminddb_config.h"
+        ]
+    },
     "libmemcached": {
         "source": "libmemcached",
+        "cpp-library": true,
         "static-libs-unix": [
             "libmemcached.a",
-            "libmemcachedutil.a"
+            "libmemcachedprotocol.a",
+            "libmemcachedutil.a",
+            "libhashkit.a"
         ]
     },
     "libpng": {
@@ -290,7 +545,8 @@
             "libpng16.a"
         ],
         "static-libs-windows": [
-            "libpng16_static.lib"
+            "libpng16_static.lib",
+            "libpng_a.lib"
         ],
         "headers-unix": [
             "png.h",
@@ -317,10 +573,28 @@
             "openssl"
         ]
     },
+    "librdkafka": {
+        "source": "librdkafka",
+        "pkg-configs": [
+            "rdkafka++-static",
+            "rdkafka-static"
+        ],
+        "cpp-library": true,
+        "lib-suggests": [
+            "curl",
+            "liblz4",
+            "openssl",
+            "zlib",
+            "zstd"
+        ]
+    },
     "libsodium": {
         "source": "libsodium",
         "static-libs-unix": [
             "libsodium.a"
+        ],
+        "static-libs-windows": [
+            "libsodium.lib"
         ]
     },
     "libssh2": {
@@ -338,15 +612,48 @@
         ],
         "lib-depends": [
             "openssl"
-        ],
-        "lib-suggests": [
-            "zlib"
         ]
     },
     "libtiff": {
         "source": "libtiff",
         "static-libs-unix": [
             "libtiff.a"
+        ],
+        "lib-depends": [
+            "zlib",
+            "libjpeg"
+        ],
+        "lib-suggests-unix": [
+            "lerc",
+            "libwebp",
+            "jbig",
+            "xz",
+            "zstd"
+        ]
+    },
+    "libunistring": {
+        "source": "libunistring",
+        "static-libs-unix": [
+            "libunistring.a"
+        ],
+        "headers": [
+            "unistr.h",
+            "unistring/"
+        ]
+    },
+    "liburing": {
+        "source": "liburing",
+        "pkg-configs": [
+            "liburing",
+            "liburing-ffi"
+        ],
+        "static-libs-linux": [
+            "liburing.a",
+            "liburing-ffi.a"
+        ],
+        "headers-linux": [
+            "liburing/",
+            "liburing.h"
         ]
     },
     "libuuid": {
@@ -366,18 +673,24 @@
     },
     "libwebp": {
         "source": "libwebp",
-        "static-libs-unix": [
-            "libwebp.a",
-            "libwebpdecoder.a",
-            "libwebpdemux.a",
-            "libwebpmux.a",
-            "libsharpyuv.a"
+        "pkg-configs": [
+            "libwebp",
+            "libwebpdecoder",
+            "libwebpdemux",
+            "libwebpmux",
+            "libsharpyuv"
+        ],
+        "static-libs-windows": [
+            "libwebp.lib",
+            "libwebpdecoder.lib",
+            "libwebpdemux.lib",
+            "libsharpyuv.lib"
         ]
     },
     "libxml2": {
         "source": "libxml2",
-        "static-libs-unix": [
-            "libxml2.a"
+        "pkg-configs": [
+            "libxml-2.0"
         ],
         "static-libs-windows": [
             "libxml2s.lib",
@@ -391,7 +704,6 @@
         ],
         "lib-suggests-unix": [
             "xz",
-            "icu",
             "zlib"
         ],
         "lib-depends-windows": [
@@ -429,23 +741,36 @@
             "libzip.a"
         ],
         "static-libs-windows": [
-            [
-                "zip.lib",
-                "libzip_a.lib"
-            ]
+            "zip.lib",
+            "libzip_a.lib"
         ],
         "headers": [
             "zip.h",
             "zipconf.h"
         ],
-        "lib-depends": [
+        "lib-depends-unix": [
             "zlib"
         ],
-        "lib-suggests": [
+        "lib-suggests-unix": [
             "bzip2",
             "xz",
             "zstd",
             "openssl"
+        ],
+        "lib-depends-windows": [
+            "zlib",
+            "bzip2",
+            "xz"
+        ],
+        "lib-suggests-windows": [
+            "zstd",
+            "openssl"
+        ]
+    },
+    "mimalloc": {
+        "source": "mimalloc",
+        "static-libs-unix": [
+            "libmimalloc.a"
         ]
     },
     "ncurses": {
@@ -454,6 +779,17 @@
             "libncurses.a"
         ]
     },
+    "net-snmp": {
+        "source": "net-snmp",
+        "pkg-configs": [
+            "netsnmp",
+            "netsnmp-agent"
+        ],
+        "lib-depends": [
+            "openssl",
+            "zlib"
+        ]
+    },
     "nghttp2": {
         "source": "nghttp2",
         "static-libs-unix": [
@@ -470,7 +806,45 @@
             "openssl"
         ],
         "lib-suggests": [
-            "libxml2"
+            "libxml2",
+            "nghttp3",
+            "ngtcp2"
+        ]
+    },
+    "nghttp3": {
+        "source": "nghttp3",
+        "static-libs-unix": [
+            "libnghttp3.a"
+        ],
+        "static-libs-windows": [
+            "nghttp3.lib"
+        ],
+        "headers": [
+            "nghttp3"
+        ],
+        "lib-depends": [
+            "openssl"
+        ]
+    },
+    "ngtcp2": {
+        "source": "ngtcp2",
+        "static-libs-unix": [
+            "libngtcp2.a",
+            "libngtcp2_crypto_ossl.a"
+        ],
+        "static-libs-windows": [
+            "ngtcp2.lib",
+            "ngtcp2_crypto_ossl.lib"
+        ],
+        "headers": [
+            "ngtcp2"
+        ],
+        "lib-depends": [
+            "openssl"
+        ],
+        "lib-suggests": [
+            "nghttp3",
+            "brotli"
         ]
     },
     "onig": {
@@ -489,6 +863,9 @@
     },
     "openssl": {
         "source": "openssl",
+        "pkg-configs": [
+            "openssl"
+        ],
         "static-libs-unix": [
             "libssl.a",
             "libcrypto.a"
@@ -504,22 +881,17 @@
             "zlib"
         ]
     },
-    "pkg-config": {
-        "source": "pkg-config"
-    },
     "postgresql": {
         "source": "postgresql",
-        "static-libs-unix": [
-            "libpq.a",
-            "libpgport.a",
-            "libpgcommon.a"
+        "pkg-configs": [
+            "libpq"
         ],
         "lib-depends": [
             "libiconv",
             "libxml2",
             "openssl",
             "zlib",
-            "readline"
+            "libedit"
         ],
         "lib-suggests": [
             "icu",
@@ -528,6 +900,20 @@
             "zstd"
         ]
     },
+    "postgresql-win": {
+        "source": "postgresql-win",
+        "static-libs": [
+            "libpq.lib",
+            "libpgport.lib",
+            "libpgcommon.lib"
+        ]
+    },
+    "pthreads4w": {
+        "source": "pthreads4w",
+        "static-libs-windows": [
+            "libpthreadVC3.lib"
+        ]
+    },
     "qdbm": {
         "source": "qdbm",
         "static-libs-unix": [
@@ -540,6 +926,12 @@
             "depot.h"
         ]
     },
+    "re2c": {
+        "source": "re2c",
+        "bin-unix": [
+            "re2c"
+        ]
+    },
     "readline": {
         "source": "readline",
         "static-libs-unix": [
@@ -551,6 +943,7 @@
     },
     "snappy": {
         "source": "snappy",
+        "cpp-library": true,
         "static-libs-unix": [
             "libsnappy.a"
         ],
@@ -585,6 +978,11 @@
     },
     "unixodbc": {
         "source": "unixodbc",
+        "pkg-configs": [
+            "odbc",
+            "odbccr",
+            "odbcinst"
+        ],
         "static-libs-unix": [
             "libodbc.a",
             "libodbccr.a",
@@ -594,16 +992,24 @@
             "libiconv"
         ]
     },
+    "watcher": {
+        "source": "watcher",
+        "cpp-library": true,
+        "static-libs-unix": [
+            "libwatcher-c.a"
+        ],
+        "headers": [
+            "wtr/watcher-c.h"
+        ]
+    },
     "xz": {
         "source": "xz",
         "static-libs-unix": [
             "liblzma.a"
         ],
         "static-libs-windows": [
-            [
-                "liblzma.lib",
-                "liblzma_a.lib"
-            ]
+            "lzma.lib",
+            "liblzma_a.lib"
         ],
         "headers-unix": [
             "lzma"
@@ -612,12 +1018,15 @@
             "lzma",
             "lzma.h"
         ],
-        "lib-depends": [
+        "lib-depends-unix": [
             "libiconv"
         ]
     },
     "zlib": {
         "source": "zlib",
+        "pkg-configs": [
+            "zlib"
+        ],
         "static-libs-unix": [
             "libz.a"
         ],
@@ -631,6 +1040,9 @@
     },
     "zstd": {
         "source": "zstd",
+        "pkg-configs": [
+            "libzstd"
+        ],
         "static-libs-unix": [
             "libzstd.a"
         ],

config/pkg.json

@@ -1,4 +1,16 @@
 {
+    "go-xcaddy-aarch64-linux": {
+        "type": "custom"
+    },
+    "go-xcaddy-aarch64-macos": {
+        "type": "custom"
+    },
+    "go-xcaddy-x86_64-linux": {
+        "type": "custom"
+    },
+    "go-xcaddy-x86_64-macos": {
+        "type": "custom"
+    },
     "musl-toolchain-aarch64-linux": {
         "type": "url",
         "url": "https://dl.static-php.dev/static-php-cli/deps/musl-toolchain/aarch64-musl-toolchain.tgz"
@@ -9,10 +21,42 @@
     },
     "nasm-x86_64-win": {
         "type": "url",
-        "url": "https://www.nasm.us/pub/nasm/releasebuilds/2.16.01/win64/nasm-2.16.01-win64.zip",
+        "url": "https://dl.static-php.dev/static-php-cli/deps/nasm/nasm-2.16.01-win64.zip",
         "extract-files": {
-            "nasm-2.16.01/nasm.exe": "{php_sdk_path}/bin/nasm.exe",
-            "nasm-2.16.01/ndisasm.exe": "{php_sdk_path}/bin/ndisasm.exe"
+            "nasm.exe": "{php_sdk_path}/bin/nasm.exe",
+            "ndisasm.exe": "{php_sdk_path}/bin/ndisasm.exe"
+        }
+    },
+    "pkg-config-aarch64-linux": {
+        "type": "ghrel",
+        "repo": "static-php/static-php-cli-hosted",
+        "match": "pkg-config-aarch64-linux-musl-1.2.5.txz",
+        "extract-files": {
+            "bin/pkg-config": "{pkg_root_path}/bin/pkg-config"
+        }
+    },
+    "pkg-config-aarch64-macos": {
+        "type": "ghrel",
+        "repo": "static-php/static-php-cli-hosted",
+        "match": "pkg-config-aarch64-darwin.txz",
+        "extract-files": {
+            "bin/pkg-config": "{pkg_root_path}/bin/pkg-config"
+        }
+    },
+    "pkg-config-x86_64-linux": {
+        "type": "ghrel",
+        "repo": "static-php/static-php-cli-hosted",
+        "match": "pkg-config-x86_64-linux-musl-1.2.5.txz",
+        "extract-files": {
+            "bin/pkg-config": "{pkg_root_path}/bin/pkg-config"
+        }
+    },
+    "pkg-config-x86_64-macos": {
+        "type": "ghrel",
+        "repo": "static-php/static-php-cli-hosted",
+        "match": "pkg-config-x86_64-darwin.txz",
+        "extract-files": {
+            "bin/pkg-config": "{pkg_root_path}/bin/pkg-config"
         }
     },
     "strawberry-perl-x86_64-win": {
@@ -40,7 +84,22 @@
         "repo": "upx/upx",
         "match": "upx.+-win64\\.zip",
         "extract-files": {
-            "upx-*-win64/upx.exe": "{pkg_root_path}/bin/upx.exe"
+            "upx.exe": "{pkg_root_path}/bin/upx.exe"
         }
+    },
+    "zig-aarch64-linux": {
+        "type": "custom"
+    },
+    "zig-aarch64-macos": {
+        "type": "custom"
+    },
+    "zig-x86_64-linux": {
+        "type": "custom"
+    },
+    "zig-x86_64-macos": {
+        "type": "custom"
+    },
+    "zig-x86_64-win": {
+        "type": "custom"
     }
 }

config/pre-built.json

@@ -0,0 +1,7 @@
+{
+    "repo": "static-php/static-php-cli-hosted",
+    "prefer-stable": true,
+    "match-pattern-linux": "{name}-{arch}-{os}-{libc}-{libcver}.txz",
+    "match-pattern-macos": "{name}-{arch}-{os}.txz",
+    "match-pattern-windows": "{name}-{arch}-{os}.tgz"
+}

docs/.vitepress/components/Contributors.vue

@@ -0,0 +1,219 @@
+<template>
+  <div class="contributors-container">
+    <div class="contributors-header">
+      <h2>Contributors</h2>
+      <p class="contributors-description">
+        Thanks to all the amazing people who have contributed to this project!
+      </p>
+    </div>
+
+    <div v-if="loading" class="loading-state">
+      <div class="spinner"></div>
+      <p>Loading contributors...</p>
+    </div>
+
+    <div v-else-if="error" class="error-state">
+      <p>{{ error }}</p>
+    </div>
+
+    <div v-else class="contributors-grid">
+      <a
+        v-for="contributor in contributors"
+        :key="contributor.id"
+        :href="contributor.html_url"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="contributor-card"
+        :title="contributor.login"
+      >
+        <img
+          :src="contributor.avatar_url"
+          :alt="contributor.login"
+          class="contributor-avatar"
+          loading="lazy"
+        />
+        <div class="contributor-name">{{ contributor.login }}</div>
+      </a>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+
+interface Contributor {
+  id: number;
+  login: string;
+  avatar_url: string;
+  html_url: string;
+  contributions: number;
+}
+
+const contributors = ref<Contributor[]>([]);
+const loading = ref(true);
+const error = ref('');
+
+const fetchContributors = async () => {
+  try {
+    loading.value = true;
+    error.value = '';
+
+    const response = await fetch(
+      'https://api.github.com/repos/crazywhalecc/static-php-cli/contributors?per_page=24'
+    );
+
+    if (!response.ok) {
+      throw new Error('Failed to fetch contributors');
+    }
+
+    const data = await response.json();
+    contributors.value = data;
+  } catch (err) {
+    error.value = 'Failed to load contributors. Please try again later.';
+    console.error('Error fetching contributors:', err);
+  } finally {
+    loading.value = false;
+  }
+};
+
+onMounted(() => {
+  fetchContributors();
+});
+</script>
+
+<style scoped>
+.contributors-container {
+  margin: 48px auto;
+  padding: 32px 24px;
+  max-width: 1152px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-bg) 100%);
+  border-radius: 16px;
+  border: 1px solid var(--vp-c-divider);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+}
+
+.contributors-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.contributors-header h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin: 0 0 8px 0;
+  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.contributors-description {
+  font-size: 0.95rem;
+  color: var(--vp-c-text-2);
+  margin: 0;
+  line-height: 1.5;
+}
+
+.loading-state,
+.error-state {
+  text-align: center;
+  padding: 40px 20px;
+  color: var(--vp-c-text-2);
+}
+
+.spinner {
+  width: 40px;
+  height: 40px;
+  margin: 0 auto 16px;
+  border: 4px solid var(--vp-c-divider);
+  border-top-color: var(--vp-c-brand-1);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.contributors-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(90px, 1fr));
+  gap: 16px;
+}
+
+.contributor-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 12px;
+  background: var(--vp-c-bg);
+  border-radius: 12px;
+  border: 1px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+  text-decoration: none;
+  color: var(--vp-c-text-1);
+}
+
+.contributor-card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+  border-color: var(--vp-c-brand-1);
+}
+
+.contributor-avatar {
+  width: 60px;
+  height: 60px;
+  border-radius: 50%;
+  border: 2px solid var(--vp-c-divider);
+  transition: all 0.3s ease;
+  margin-bottom: 8px;
+}
+
+.contributor-card:hover .contributor-avatar {
+  border-color: var(--vp-c-brand-1);
+  transform: scale(1.05);
+}
+
+.contributor-name {
+  font-size: 12px;
+  font-weight: 500;
+  text-align: center;
+  word-break: break-word;
+  max-width: 100%;
+}
+
+@media (max-width: 768px) {
+  .contributors-container {
+    margin: 32px 16px;
+    padding: 24px 16px;
+  }
+
+  .contributors-header h2 {
+    font-size: 1.25rem;
+  }
+
+  .contributors-description {
+    font-size: 0.9rem;
+  }
+
+  .contributors-grid {
+    grid-template-columns: repeat(auto-fill, minmax(70px, 1fr));
+    gap: 12px;
+  }
+
+  .contributor-card {
+    padding: 8px;
+  }
+
+  .contributor-avatar {
+    width: 48px;
+    height: 48px;
+  }
+
+  .contributor-name {
+    font-size: 11px;
+  }
+}
+</style>

docs/.vitepress/components/DependencyUtil.js

@@ -0,0 +1,193 @@
+export function getMetaList(meta, type, name, list_name) {
+  if (meta.os === 'linux') {
+    return meta[type][name][list_name + '-linux'] ?? meta[type][name][list_name + '-unix'] ?? meta[type][name][list_name] ?? [];
+  }
+  if (meta.os === 'macos') {
+    return meta[type][name][list_name + '-macos'] ?? meta[type][name][list_name + '-unix'] ?? meta[type][name][list_name] ?? [];
+  }
+  if (meta.os === 'windows') {
+    return meta[type][name][list_name + '-windows'] ?? meta[type][name][list_name] ?? [];
+  }
+  return [];
+}
+
+export function getExtDepends(meta, ext_name) {
+  return getMetaList(meta, 'ext', ext_name, 'ext-depends');
+}
+
+export function getExtSuggests(meta, ext_name) {
+  return getMetaList(meta, 'ext', ext_name, 'ext-suggests');
+}
+
+export function getExtLibDepends(meta, ext_name) {
+  const ls = getMetaList(meta, 'ext', ext_name, 'lib-depends');
+  return ls;
+}
+
+export function getExtLibSuggests(meta, ext_name) {
+  return getMetaList(meta, 'ext', ext_name, 'lib-suggests');
+}
+
+export function getLibDepends(meta, lib_name) {
+  return getMetaList(meta, 'lib', lib_name, 'lib-depends');
+}
+
+export function getLibSuggests(meta, lib_name) {
+  return getMetaList(meta, 'lib', lib_name, 'lib-suggests');
+}
+
+/**
+ * Obtain the dependent lib list according to the required ext list, and sort according to the dependency
+ * @param meta
+ * @param exts
+ */
+export function getExtLibsByDeps(meta, exts) {
+  const sorted = [];
+  const visited = new Set();
+  const notIncludedExts = [];
+  exts.forEach((ext) => {
+    if (!visited.has(ext)) {
+      visitExtDeps(meta, ext, visited, sorted);
+    }
+  });
+
+  const sortedSuggests = [];
+  const visitedSuggests = new Set();
+  const final = [];
+  exts.forEach((ext) => {
+    if (!visited.has(ext)) {
+      visitExtAllDeps(meta, ext, visitedSuggests, sortedSuggests);
+    }
+  });
+  sortedSuggests.forEach((suggest) => {
+    if (sorted.indexOf(suggest) !== -1) {
+      final.push(suggest);
+    }
+  });
+  const libs = [];
+  final.forEach((ext) => {
+    if (exts.indexOf(ext) === -1) {
+      notIncludedExts.push(ext);
+    }
+    getExtLibDepends(meta, ext).forEach((lib) => {
+      if (libs.indexOf(lib) === -1) {
+        libs.push(lib);
+      }
+    });
+  });
+
+  return { exts: final, libs: getLibsByDeps(meta, libs), notIncludedExts: notIncludedExts };
+}
+
+export function getAllExtLibsByDeps(meta, exts) {
+  const sorted = [];
+  const visited = new Set();
+  const notIncludedExts = [];
+  exts.forEach((ext) => {
+    if (!visited.has(ext)) {
+      visitExtAllDeps(meta, ext, visited, sorted);
+    }
+  });
+  const libs = [];
+  sorted.forEach((ext) => {
+    if (exts.indexOf(ext) === -1) {
+      notIncludedExts.push(ext);
+    }
+    const allLibs = [...getExtLibDepends(meta, ext), ...getExtLibSuggests(meta, ext)];
+    allLibs.forEach((dep) => {
+      if (libs.indexOf(dep) === -1) {
+        libs.push(dep);
+      }
+    });
+  });
+  return { exts: sorted, libs: getAllLibsByDeps(meta, libs), notIncludedExts: notIncludedExts };
+}
+
+export function getAllLibsByDeps(meta, libs) {
+  const sorted = [];
+  const visited = new Set();
+
+  libs.forEach((lib) => {
+    if (!visited.has(lib)) {
+      console.log('before visited');
+      console.log(visited);
+      visitLibAllDeps(meta, lib, visited, sorted);
+      console.log('after visited');
+      console.log(visited);
+    }
+  });
+  return sorted;
+}
+
+export function getLibsByDeps(meta, libs) {
+  const sorted = [];
+  const visited = new Set();
+
+  libs.forEach((lib) => {
+    if (!visited.has(lib)) {
+      visitLibDeps(meta, lib, visited, sorted);
+    }
+  });
+
+  const sortedSuggests = [];
+  const visitedSuggests = new Set();
+  const final = [];
+  libs.forEach((lib) => {
+    if (!visitedSuggests.has(lib)) {
+      visitLibAllDeps(meta, lib, visitedSuggests, sortedSuggests);
+    }
+  });
+  sortedSuggests.forEach((suggest) => {
+    if (sorted.indexOf(suggest) !== -1) {
+      final.push(suggest);
+    }
+  });
+  return final;
+}
+
+export function visitLibAllDeps(meta, lib_name, visited, sorted) {
+  if (visited.has(lib_name)) {
+    return;
+  }
+  visited.add(lib_name);
+  const allLibs = [...getLibDepends(meta, lib_name), ...getLibSuggests(meta, lib_name)];
+  allLibs.forEach((dep) => {
+    visitLibDeps(meta, dep, visited, sorted);
+  });
+  sorted.push(lib_name);
+}
+
+export function visitLibDeps(meta, lib_name, visited, sorted) {
+  if (visited.has(lib_name)) {
+    return;
+  }
+  visited.add(lib_name);
+  getLibDepends(meta, lib_name).forEach((dep) => {
+    visitLibDeps(meta, dep, visited, sorted);
+  });
+  sorted.push(lib_name);
+}
+
+export function visitExtDeps(meta, ext_name, visited, sorted) {
+  if (visited.has(visited)) {
+    return;
+  }
+  visited.add(ext_name);
+  getExtDepends(meta, ext_name).forEach((dep) => {
+    visitExtDeps(meta, dep, visited, sorted);
+  });
+  sorted.push(ext_name);
+}
+
+export function visitExtAllDeps(meta, ext_name, visited, sorted) {
+  if (visited.has(ext_name)) {
+    return;
+  }
+  visited.add(ext_name);
+
+  const allExts = [...getExtDepends(meta, ext_name), ...getExtSuggests(meta, ext_name)];
+  allExts.forEach((dep) => {
+    visitExtDeps(meta, dep, visited, sorted);
+  });
+  sorted.push(ext_name);
+}

docs/.vitepress/components/SearchTable.vue

@@ -0,0 +1,79 @@
+<template>
+  <div>
+    <header class="DocSearch-SearchBar" style="padding: 0">
+      <form class="DocSearch-Form searchinput">
+        <input class="DocSearch-Input" v-model="filterText" placeholder="Filter name..." @input="doFilter" />
+      </form>
+    </header>
+    <table>
+      <thead>
+      <tr>
+        <th>Extension Name</th>
+        <th>Linux</th>
+        <th>macOS</th>
+        <th>FreeBSD</th>
+        <th>Windows</th>
+      </tr>
+      </thead>
+      <tbody>
+      <tr v-for="item in filterData">
+        <td v-if="!item.notes">{{ item.name }}</td>
+        <td v-else>
+          <a :href="'./extension-notes.html#' + item.name">{{ item.name }}</a>
+        </td>
+        <td>{{ item.linux }}</td>
+        <td>{{ item.macos }}</td>
+        <td>{{ item.freebsd }}</td>
+        <td>{{ item.windows }}</td>
+      </tr>
+      </tbody>
+    </table>
+    <div v-if="filterData.length === 0" style="margin: 0 4px 20px 4px; color: var(--vp-c-text-2); font-size: 14px">
+      No result, please try another keyword.
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  name: "SearchTable"
+}
+</script>
+
+<script setup>
+import {ref} from "vue";
+import ext from '../../../config/ext.json';
+
+// 将 ext 转换为列表，方便后续操作
+const data = ref([]);
+for (const [name, item] of Object.entries(ext)) {
+  data.value.push({
+    name,
+    linux: item.support?.Linux === undefined ? 'yes' : (item.support?.Linux === 'wip' ? '' : item.support?.Linux),
+    macos: item.support?.Darwin === undefined ? 'yes' : (item.support?.Darwin === 'wip' ? '' : item.support?.Darwin),
+    freebsd: item.support?.BSD === undefined ? 'yes' : (item.support?.BSD === 'wip' ? '' : item.support?.BSD),
+    windows: item.support?.Windows === undefined ? 'yes' : (item.support?.Windows === 'wip' ? '' : item.support?.Windows),
+    notes: item.notes === true,
+  });
+}
+
+
+const filterData = ref(data.value);
+const filterText = ref('');
+
+const doFilter = () => {
+  if (filterText.value === '') {
+    filterData.value = data.value;
+    return;
+  }
+  filterData.value = data.value.filter(item => {
+    return item.name.toLowerCase().includes(filterText.value.toLowerCase());
+  });
+}
+</script>
+
+<style>
+.searchinput {
+  border: 1px solid var(--vp-c-divider);
+}
+</style>

docs/.vitepress/config.ts

@@ -0,0 +1,65 @@
+import sidebarEn from "./sidebar.en";
+import sidebarZh from "./sidebar.zh";
+
+
+// https://vitepress.dev/reference/site-config
+export default {
+  title: "Static PHP",
+  description: "Build single static PHP binary, with PHP project together, with popular extensions included.",
+  locales: {
+    en: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        nav: [
+          {text: 'Guide', link: '/en/guide/',},
+          {text: 'Advanced', link: '/en/develop/'},
+          {text: 'Contributing', link: '/en/contributing/'},
+          {text: 'FAQ', link: '/en/faq/'},
+        ],
+        sidebar: sidebarEn,
+        footer: {
+          message: 'Released under the MIT License.',
+          copyright: 'Copyright © 2023-present crazywhalecc'
+        }
+      },
+    },
+    zh: {
+      label: '简体中文',
+      lang: 'zh', // optional, will be added  as `lang` attribute on `html` tag
+      themeConfig: {
+        nav: [
+          {text: '构建指南', link: '/zh/guide/'},
+          {text: '进阶', link: '/zh/develop/'},
+          {text: '贡献', link: '/zh/contributing/'},
+          {text: 'FAQ', link: '/zh/faq/'},
+        ],
+        sidebar: sidebarZh,
+        footer: {
+          message: 'Released under the MIT License.',
+          copyright: 'Copyright © 2023-present crazywhalecc'
+        }
+      },
+    }
+  },
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    logo: '/images/static-php_nobg.png',
+    nav: [],
+    socialLinks: [
+      {icon: 'github', link: 'https://github.com/crazywhalecc/static-php-cli'}
+    ],
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2023-present crazywhalecc'
+    },
+    search: {
+      provider: 'algolia',
+      options: {
+        appId: 'IHJHUB1SF1',
+        apiKey: '8266d31cc2ffbd0e059f1c6e5bdaf8fc',
+        indexName: 'static-php docs',
+      },
+    },
+  }
+}

docs/.vitepress/sidebar.en.ts

@@ -0,0 +1,57 @@
+export default {
+    '/en/guide/': [
+        {
+            text: 'Basic Build Guides',
+            items: [
+                {text: 'Guide', link: '/en/guide/'},
+                {text: 'Build (Local)', link: '/en/guide/manual-build'},
+                {text: 'Build (CI)', link: '/en/guide/action-build'},
+                {text: 'Supported Extensions', link: '/en/guide/extensions'},
+                {text: 'Extension Notes', link: '/en/guide/extension-notes'},
+                {text: 'Build Command Generator', link: '/en/guide/cli-generator'},
+                {text: 'Environment Variables', link: '/en/guide/env-vars', collapsed: true,},
+                {text: 'Dependency Table', link: '/en/guide/deps-map'},
+            ]
+        },
+        {
+            text: 'Extended Build Guides',
+            items: [
+                {text: 'Troubleshooting', link: '/en/guide/troubleshooting'},
+                {text: 'Build on Windows', link: '/en/guide/build-on-windows'},
+                {text: 'Build with GNU libc', link: '/en/guide/build-with-glibc'},
+            ],
+        }
+    ],
+    '/en/develop/': [
+        {
+            text: 'Development',
+            items: [
+                {text: 'Get Started', link: '/en/develop/'},
+                {text: 'Project Structure', link: '/en/develop/structure'},
+                {text: 'PHP Source Modification', link: '/en/develop/php-src-changes'},
+            ],
+        },
+        {
+            text: 'Module',
+            items: [
+                {text: 'Doctor ', link: '/en/develop/doctor-module'},
+                {text: 'Source', link: '/en/develop/source-module'},
+            ]
+        },
+        {
+            text: 'Extra',
+            items: [
+                {text: 'Compilation Tools', link: '/en/develop/system-build-tools'},
+                {text: 'craft.yml Configuration', link: '/zh/develop/craft-yml'},
+            ]
+        }
+    ],
+    '/en/contributing/': [
+        {
+            text: 'Contributing',
+            items: [
+                {text: 'Contributing', link: '/en/contributing/'},
+            ],
+        }
+    ],
+};

docs/.vitepress/sidebar.zh.ts

@@ -0,0 +1,57 @@
+export default {
+    '/zh/guide/': [
+        {
+            text: '构建指南',
+            items: [
+                {text: '指南', link: '/zh/guide/'},
+                {text: '本地构建', link: '/zh/guide/manual-build'},
+                {text: 'Actions 构建', link: '/zh/guide/action-build'},
+                {text: '扩展列表', link: '/zh/guide/extensions'},
+                {text: '扩展注意事项', link: '/zh/guide/extension-notes'},
+                {text: '编译命令生成器', link: '/zh/guide/cli-generator'},
+                {text: '环境变量列表', link: '/zh/guide/env-vars'},
+                {text: '依赖关系图表', link: '/zh/guide/deps-map'},
+            ]
+        },
+        {
+            text: '扩展构建指南',
+            items: [
+                {text: '故障排除', link: '/zh/guide/troubleshooting'},
+                {text: '在 Windows 上构建', link: '/zh/guide/build-on-windows'},
+                {text: '构建 GNU libc 兼容的二进制', link: '/zh/guide/build-with-glibc'},
+            ],
+        }
+    ],
+    '/zh/develop/': [
+        {
+            text: '开发指南',
+            items: [
+                {text: '开发简介', link: '/zh/develop/'},
+                {text: '项目结构简介', link: '/zh/develop/structure'},
+                {text: '对 PHP 源码的修改', link: '/zh/develop/php-src-changes'},
+            ],
+        },
+        {
+            text: '模块',
+            items: [
+                {text: 'Doctor 环境检查工具', link: '/zh/develop/doctor-module'},
+                {text: '资源模块', link: '/zh/develop/source-module'},
+            ]
+        },
+        {
+            text: '其他',
+            items: [
+                {text: '系统编译工具', link: '/zh/develop/system-build-tools'},
+                {text: 'craft.yml 配置详解', link: '/zh/develop/craft-yml'},
+            ]
+        }
+    ],
+    '/zh/contributing/': [
+        {
+            text: '贡献指南',
+            items: [
+                {text: '贡献指南', link: '/zh/contributing/'},
+            ],
+        }
+    ],
+};

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// docs/.vitepress/theme/index.ts
+import DefaultTheme from 'vitepress/theme'
+import {inBrowser, useData} from "vitepress";
+import {watchEffect} from "vue";
+import './style.css';
+
+export default {
+    ...DefaultTheme,
+    setup() {
+        const { lang } = useData()
+        watchEffect(() => {
+            if (inBrowser) {
+                document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2024 00:00:00 UTC; path=/`
+            }
+        })
+    }
+}

docs/.vitepress/theme/style.css

@@ -0,0 +1,24 @@
+/** override default styles */
+.vp-sponsor-grid-image {
+    max-height:36px !important;
+    max-width: 1000px !important;
+}
+
+
+.vp-doc .contributors-header h2 {
+    padding-top: 0;
+    border-top: none;
+}
+
+.vp-doc .sponsors-header h2 {
+    padding-top: 0;
+    border-top: none;
+}
+
+.dark .VPImage.logo {
+  filter: contrast(0.7);
+}
+
+.dark .VPImage.image-src {
+  filter: contrast(0.7);
+}

docs/deps-craft-yml.md

@@ -0,0 +1,70 @@
+```yaml
+# PHP version to build (default: 8.4)
+php-version: 8.4
+# [REQUIRED] Static PHP extensions to build (list or comma-separated are both accepted)
+extensions: bcmath,fileinfo,phar,zlib,sodium,posix,pcntl
+# Extra libraries to build (list or comma-separated are both accepted)
+libs: [ ]
+# [REQUIRED] Build SAPIs (list or comma-separated are both accepted)
+sapi: cli,micro,fpm
+# Show full console output (default: false)
+debug: false
+# Build options (same as `build` command options, all options are optional)
+build-options:
+  # Before build, remove all old build files and sources (default: false)
+  with-clean: false
+  # Build with all suggested libraries (default: false)
+  with-suggested-libs: false
+  # Build with all suggested extensions (default: false)
+  with-suggested-exts: false
+  # Build extra shared extensions (list or comma-separated are both accepted)
+  build-shared: [ ]
+  # Build without stripping the binary (default: false)
+  no-strip: false
+  # Disable Opcache JIT (default: false)
+  disable-opcache-jit: 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
+
+# Build options for shared extensions (list or comma-separated are both accepted)
+shared-extensions: [ ]
+
+# Download options
+download-options:
+  # 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: [ ]
+  # Retries count for downloading sources (default: 5)
+  retry: 5
+  # Use pre-built libraries if available (default: false)
+  prefer-pre-built: true
+  # Do not download from alternative sources (default: false)
+  no-alt: false
+
+craft-options:
+  doctor: true
+  download: true
+  build: true
+
+# Extra environment variables
+extra-env:
+  # e.g. Use github token to avoid rate limit
+  GITHUB_TOKEN: your-github-token
+```

docs/en/contributing/index.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thank you for being here, this project welcomes your contributions!
+
+## Contribution Guide
+
+If you have code or documentation to contribute, here's what you need to know first.
+
+1. What type of code are you contributing? (new extensions, bug fixes, security issues, project framework optimizations, documentation)
+2. If you contribute new files or new snippets, is your code checked by `php-cs-fixer` and `phpstan`?
+3. Have you fully read the [Developer Guide](../develop/) before contributing code?
+
+If you can answer the above questions and have made changes to the code, 
+you can initiate a Pull Request in the project GitHub repository in time. 
+After the code review is completed, the code can be modified according to the suggestion, or directly merged into the main branch.
+
+## Contribution Type
+
+The main purpose of this project is to compile statically linked PHP binaries, 
+and the command line processing function is written based on `symfony/console`. 
+Before development, if you are not familiar with it,
+Check out the [symfony/console documentation](https://symfony.com/doc/current/components/console.html) first.
+
+### Security Update
+
+Because this project is basically a PHP project running locally, generally speaking, there will be no remote attacks. 
+But if you find such a problem, please **DO NOT submit a PR or Issue in the GitHub repository,
+You need to contact the project maintainer (crazywhalecc) via [mail](mailto:admin@zhamao.me).
+
+### Fix Bugs
+
+Fixing bugs generally does not involve modification of the project structure and framework, 
+so if you can locate the wrong code and fix it directly, please submit a PR directly.
+
+### New Extensions
+
+For adding a new extension, 
+you need to understand some basic structure of the project and how to add a new extension according to the existing logic. 
+It will be covered in detail in the next section on this page.
+In general, you will need:
+
+1. Evaluate whether the extension can be compiled inline into PHP.
+2. Evaluate whether the extension's dependent libraries (if any) can be compiled statically.
+3. Write library compile commands on different platforms.
+4. Verify that the extension and its dependencies are compatible with existing extensions and dependencies.
+5. Verify that the extension works normally in `cli`, `micro`, `fpm`, `embed` SAPIs.
+6. Write documentation and add your extension.
+
+### Project Framework Optimization
+
+If you are already familiar with the working principle of `symfony/console`, 
+and at the same time want to make some modifications or optimizations to the framework of the project, 
+please understand the following things first:
+
+1. Adding extensions does not belong to project framework optimization, 
+but if you find that you have to optimize the framework when adding new extensions, 
+you need to modify the framework itself before adding extensions.
+2. For some large-scale logical modifications (such as those involving LibraryBase, Extension objects, etc.), 
+it is recommended to submit an Issue or Draft PR for discussion first.
+3. In the early stage of the project, it was a pure private development project, and there were some Chinese comments in the code. 
+After internationalizing your project you can submit a PR to translate these comments into English.
+4. Please do not submit more useless code fragments in the code, 
+such as a large number of unused variables, methods, classes, and code that has been rewritten many times.

docs/en/develop/craft-yml.md

@@ -0,0 +1,7 @@
+---
+aside: false
+---
+
+# craft.yml Configuration
+
+<!--@include: ../../deps-craft-yml.md-->

docs/en/develop/doctor-module.md

@@ -0,0 +1,70 @@
+# Doctor module
+
+The Doctor module is a relatively independent module used to check the system environment, which can be entered with the command `bin/spc doctor`, and the entry command class is in `DoctorCommand.php`.
+
+The Doctor module is a checklist with a series of check items and automatic repair items.
+These items are stored in the `src/SPC/doctor/item/` directory,
+And two Attributes are used as check item tags and auto-fix item tags: `#[AsCheckItem]` and `#[AsFixItem]`.
+
+Take the existing check item `if necessary tools are installed`,
+which is used to check whether the packages necessary for compilation are installed in the macOS system.
+The following is its source code:
+
+```php
+use SPC\doctor\AsCheckItem;
+use SPC\doctor\AsFixItem;
+use SPC\doctor\CheckResult;
+
+#[AsCheckItem('if necessary tools are installed', limit_os: 'Darwin', level: 997)]
+public function checkCliTools(): ?CheckResult
+{
+    $missing = [];
+    foreach (self::REQUIRED_COMMANDS as $cmd) {
+        if ($this->findCommand($cmd) === null) {
+            $missing[] = $cmd;
+        }
+    }
+    if (!empty($missing)) {
+        return CheckResult::fail('missing system commands: ' . implode(', ', $missing), 'build-tools', [$missing]);
+    }
+    return CheckResult::ok();
+}
+```
+
+The first parameter of the attribute is the name of the check item,
+and the following `limit_os` parameter restricts the check item to be triggered only under the specified system,
+and `level` is the priority of executing the check item, the larger the number, the higher the priority higher.
+
+The `$this->findCommand()` method used in it is the method of `SPC\builder\traits\UnixSystemUtilTrait`,
+the purpose is to find the location of the system command, and return NULL if it cannot be found.
+
+Each check item method should return a `SPC\doctor\CheckResult`:
+
+- When returning `CheckResult::fail()`, the first parameter is used to output the error prompt of the terminal,
+  and the second parameter is the name of the repair item when this check item can be automatically repaired.
+- When `CheckResult::ok()` is returned, the check passed. You can also pass a parameter to return the check result, for example: `CheckResult::ok('OS supported')`.
+- When returning `CheckResult::fail()`, if the third parameter is included, the array of the third parameter will be used as the parameter of `AsFixItem`.
+
+The following is the method for automatically repairing items corresponding to this check item:
+
+```php
+#[AsFixItem('build-tools')]
+public function fixBuildTools(array $missing): bool
+{
+    foreach ($missing as $cmd) {
+        try {
+            shell(true)->exec('brew install ' . escapeshellarg($cmd));
+        } catch (RuntimeException) {
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+`#[AsFixItem()]` first parameter is the name of the fix item, and this method must return True or False.
+When False is returned, the automatic repair failed and manual handling is required.
+
+In the code here, `shell()->exec()` is the method of executing commands of the project,
+which is used to replace `exec()` and `system()`, and also provides debugging, obtaining execution status,
+entering directories, etc. characteristic.

docs/en/develop/index.md

@@ -0,0 +1,35 @@
+# Start Developing
+
+Developing this project requires the installation and deployment of a PHP environment, 
+as well as some extensions and Composer commonly used in PHP projects.
+
+The development environment and running environment of the project are almost exactly the same. 
+You can refer to the **Manual Build** section to install system PHP or use the pre-built static PHP of this project as the environment. 
+I will not go into details here.
+
+Regardless of its purpose, this project itself is actually a `php-cli` program. You can edit and develop it as a normal PHP project. 
+At the same time, you need to understand the Shell languages of different systems.
+
+The current purpose of this project is to compile statically compiled independent PHP, 
+but the main part also includes compiling static versions of many dependent libraries, 
+so you can reuse this set of compilation logic to build independent binary versions of other programs, such as Nginx, etc.
+
+## Environment preparation
+
+A PHP environment is required to develop this project. You can use the PHP that comes with the system, 
+or you can use the static PHP built by this project.
+
+Regardless of which PHP you use, in your development environment you need to install these extensions:
+
+```
+curl,dom,filter,mbstring,openssl,pcntl,phar,posix,sodium,tokenizer,xml,xmlwriter
+```
+
+The static-php-cli project itself does not require so many extensions, but during the development process, 
+you will use tools such as Composer and PHPUnit, which require these extensions.
+
+> For micro self-executing binaries built by static-php-cli itself, only `pcntl,posix,mbstring,tokenizer,phar` is required.
+
+## Start development
+
+Continuing down to see the project structure documentation, you can learn how `static-php-cli` works.

docs/en/develop/php-src-changes.md

@@ -0,0 +1,59 @@
+# Modifications to PHP source code
+
+During the static compilation process, static-php-cli made some modifications to the PHP source code 
+in order to achieve good compatibility, performance, and security. 
+The following is a description of the current modifications to the PHP source code.
+
+## Micro related patches
+
+Based on the patches provided by the phpmicro project, 
+static-php-cli has made some modifications to the PHP source code to meet the needs of static compilation. 
+The patches currently used by static-php-cli during compilation in the [patch list](https://github.com/easysoft/phpmicro/tree/master/patches) are:
+
+- static_opcache
+- static_extensions_win32
+- cli_checks
+- disable_huge_page
+- vcruntime140
+- win32
+- zend_stream
+- cli_static
+- macos_iconv
+- phar
+
+## PHP <= 8.1 libxml patch
+
+Because PHP only provides security updates for 8.1 and stops updating older versions, 
+static-php-cli applies the libxml compilation patch that has been applied in newer versions of PHP to PHP 8.1 and below.
+
+## gd extension Windows patch
+
+Compiling the gd extension under Windows requires major changes to the `config.w32` file. 
+static-php-cli has made some changes to the gd extension to make it easier to compile under Windows.
+
+## YAML extension Windows patch
+
+YAML extension needs to modify the `config.w32` file to compile under Windows. 
+static-php-cli has made some modifications to the YAML extension to make it easier to compile under Windows.
+
+## static-php-cli version information insertion
+
+When compiling, static-php-cli will insert the static-php-cli version information into the PHP version information for easy identification.
+
+## Add option to hardcode INI
+
+When using the `-I` parameter to hardcode INI into static PHP functionality, 
+static-php-cli will modify the PHP source code to insert the hardcoded content.
+
+## Linux system repair patch
+
+Some compilation environments may lack some system header files or libraries. 
+static-php-cli will automatically fix these problems during compilation, such as:
+
+- HAVE_STRLCAT missing problem
+- HAVE_STRLCPY missing problem
+
+## Fiber issue fix patch for Windows
+
+When compiling PHP on Windows, there will be some issues with the Fiber extension. 
+static-php-cli will automatically fix these issues during compilation (modify `config.w32` in php-src).

docs/en/develop/source-module.md

@@ -0,0 +1,372 @@
+# Source module
+
+The download source module of static-php-cli is a major module.
+It includes dependent libraries, external extensions, PHP source code download methods and file decompression methods.
+The download configuration file mainly involves the `source.json` and `pkg.json` file, which records the download method of all downloadable sources.
+
+The main commands involved in the download function are `bin/spc download` and `bin/spc extract`. 
+The `download` command is a downloader that downloads sources according to the configuration file, 
+and the `extract` command is an extractor that extract sources from downloaded files.
+
+Generally speaking, downloading sources may be slow because these sources come from various official websites, GitHub, 
+and other different locations. 
+At the same time, they also occupy a large space, so you can download the sources once and reuse them.
+
+The configuration file of the downloader is `source.json`, which contains the download methods of all sources. 
+You can add the source download methods you need, or modify the existing source download methods.
+
+The download configuration structure of each source is as follows. 
+The following is the source download configuration corresponding to the `libevent` extension:
+
+```json
+{
+  "libevent": {
+    "type": "ghrel",
+    "repo": "libevent/libevent",
+    "match": "libevent.+\\.tar\\.gz",
+    "provide-pre-built": true,
+      "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+The most important field here is `type`. Currently, the types it supports are:
+
+- `url`: Directly use URL to download, for example: `https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz`.
+- `pie`: Download PHP extensions from Packagist using the PIE (PHP Installer for Extensions) standard.
+- `ghrel`: Use the GitHub Release API to download, download the artifacts uploaded from the latest version released by maintainers.
+- `ghtar`: Use the GitHub Release API to download. 
+    Different from `ghrel`, `ghtar` is downloaded from the `source code (tar.gz)` in the latest Release of the project.
+- `ghtagtar`: Use GitHub Release API to download. 
+    Compared with `ghtar`, `ghtagtar` can find the latest one from the `tags` list and download the source code in `tar.gz` format 
+    (because some projects only use `tag` release version).
+- `bitbuckettag`: Download using BitBucket API, basically the same as `ghtagtar`, except this one applies to BitBucket.
+- `git`: Clone the project directly from a Git address to download sources, applicable to any public Git repository.
+- `filelist`: Use a crawler to crawl the Web download site that provides file index,
+    and get the latest version of the file name and download it.
+- `custom`: If none of the above download methods are satisfactory, you can write `custom`, 
+    create a new class under `src/SPC/store/source/`, extends `CustomSourceBase`, and write the download script yourself.
+
+## source.json Common parameters
+
+Each source file in source.json has the following params:
+
+- `license`: the open source license of the source code, see **Open Source License** section below
+- `type`: must be one of the types mentioned above
+- `path` (optional): release the source code to the specified directory instead of `source/{name}`
+- `provide-pre-built` (optional): whether to provide precompiled binary files. 
+    If `true`, it will automatically try to download precompiled binary files when running `bin/spc download`
+
+::: tip
+The `path` parameter in `source.json` can specify a relative or absolute path. When specified as a relative path, the path is based on `source/`.
+:::
+
+## Download type - url
+
+URL type sources refer to downloading files directly from the URL.
+
+The parameters included are:
+
+- `url`: The download address of the file, such as `https://example.com/file.tgz`
+- `filename` (optional): The file name saved to the local area. If not specified, the file name of the url will be used.
+
+Example (download the imagick extension and extract it to the extension storage path of the php source code):
+
+```json
+{
+   "ext-imagick": {
+     "type": "url",
+     "url": "https://pecl.php.net/get/imagick",
+     "path": "php-src/ext/imagick",
+     "filename": "imagick.tgz",
+     "license": {
+       "type": "file",
+       "path": "LICENSE"
+     }
+   }
+}
+```
+
+## Download type - pie
+
+PIE (PHP Installer for Extensions) type sources refer to downloading PHP extensions from Packagist that follow the PIE standard.
+This method automatically fetches extension information from the Packagist repository and downloads the appropriate distribution file.
+
+The parameters included are:
+
+- `repo`: The Packagist vendor/package name, such as `vendor/package-name`
+
+Example (download a PHP extension from Packagist using PIE):
+
+```json
+{
+  "ext-example": {
+    "type": "pie",
+    "repo": "vendor/example-extension",
+    "path": "php-src/ext/example",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+::: tip
+The PIE download type will automatically detect the extension information from Packagist metadata, 
+including the download URL, version, and distribution type. 
+The extension must be marked as `type: php-ext` or contain `php-ext` metadata in its Packagist package definition.
+:::
+
+## Download type - ghrel
+
+ghrel will download files from Assets uploaded in GitHub Release. 
+First use the GitHub Release API to get the latest version, and then download the corresponding files according to the regular matching method.
+
+The parameters included are:
+
+- `repo`: GitHub repository name
+- `match`: regular expression matching Assets files
+- `prefer-stable`: Whether to download stable versions first (default is `false`)
+
+Example (download the libsodium library, matching the libsodium-x.y.tar.gz file in Release):
+
+```json
+{
+   "libsodium": {
+     "type": "ghrel",
+     "repo": "jedisct1/libsodium",
+     "match": "libsodium-\\d+(\\.\\d+)*\\.tar\\.gz",
+     "license": {
+       "type": "file",
+       "path": "LICENSE"
+     }
+   }
+}
+```
+
+## Download type - ghtar
+
+ghtar will download the file from the GitHub Release Tag. 
+Unlike `ghrel`, `ghtar` will download the `source code (tar.gz)` from the latest Release of the project.
+
+The parameters included are:
+
+- `repo`: GitHub repository name
+- `prefer-stable`: Whether to download stable versions first (default is `false`)
+
+Example (brotli library):
+
+```json
+{
+   "brotli": {
+     "type": "ghtar",
+     "repo": "google/brotli",
+     "license": {
+       "type": "file",
+       "path": "LICENSE"
+     }
+   }
+}
+```
+
+## Download type - ghtagtar
+
+Use the GitHub Release API to download. 
+Compared with `ghtar`, `ghtagtar` can find the latest one from the `tags` list and download the source code in `tar.gz` format 
+(because some projects only use the `tag` version).
+
+The parameters included are:
+
+- `repo`: GitHub repository name
+- `prefer-stable`: Whether to download stable versions first (default is `false`)
+
+Example (gmp library):
+
+```json
+{
+   "gmp": {
+     "type": "ghtagtar",
+     "repo": "alisw/GMP",
+     "license": {
+       "type": "text",
+       "text": "EXAMPLE LICENSE"
+     }
+   }
+}
+```
+
+## Download Type - bitbuckettag
+
+Download using BitBucket API, basically the same as `ghtagtar`, except this one works with BitBucket.
+
+The parameters included are:
+
+- `repo`: BitBucket repository name
+
+## Download type - git
+
+Clone the project directly from a Git address to download sources, applicable to any public Git repository.
+
+The parameters included are:
+
+- `url`: Git link (HTTPS only)
+- `rev`: branch name
+
+```json
+{
+   "imap": {
+     "type": "git",
+     "url": "https://github.com/static-php/imap.git",
+     "rev": "master",
+     "license": {
+       "type": "file",
+       "path": "LICENSE"
+     }
+   }
+}
+```
+
+## Download type - filelist
+
+Use a crawler to crawl a web download site that provides a file index and get the latest version of the file name and download it.
+
+Note that this method is only applicable to static sites with page index functions such as mirror sites and GNU official websites.
+
+The parameters included are:
+
+- `url`: The URL of the page to crawl the latest version of the file
+- `regex`: regular expression matching file names and download links
+
+Example (download the libiconv library from the GNU official website):
+
+```json
+{
+   "libiconv": {
+     "type": "filelist",
+     "url": "https://ftp.gnu.org/gnu/libiconv/",
+     "regex": "/href=\"(?<file>libiconv-(?<version>[^\"]+)\\.tar\\.gz)\"/",
+     "license": {
+       "type": "file",
+       "path": "COPYING"
+     }
+   }
+}
+```
+
+## Download type - custom
+
+If the above downloading methods are not satisfactory, you can write `custom`, 
+create a new class under `src/SPC/store/source/`, extends `CustomSourceBase`, and write the download script yourself.
+
+I won’t go into details here, you can look at `src/SPC/store/source/PhpSource.php` or `src/SPC/store/source/PostgreSQLSource.php` as examples.
+
+## pkg.json General parameters
+
+pkg.json stores non-source-code files, such as precompiled tools musl-toolchain and UPX. It includes:
+
+- `type`: The same type as `source.json` and different kinds of parameters.
+- `extract` (optional): The path to decompress after downloading, the default is `pkgroot/{pkg_name}`.
+- `extract-files` (optional): Extract only the specified files to the specified location after downloading.
+
+It should be noted that `pkg.json` does not involve compilation, modification and distribution of source code, 
+so there is no `license` open source license field. 
+And you cannot use the `extract` and `extract-files` parameters at the same time.
+
+Example (download nasm locally and extract only program files to PHP SDK):
+
+```json
+{
+   "nasm-x86_64-win": {
+     "type": "url",
+     "url": "https://www.nasm.us/pub/nasm/releasebuilds/2.16.01/win64/nasm-2.16.01-win64.zip",
+     "extract-files": {
+       "nasm-2.16.01/nasm.exe": "{php_sdk_path}/bin/nasm.exe",
+       "nasm-2.16.01/ndisasm.exe": "{php_sdk_path}/bin/ndisasm.exe"
+     }
+   }
+}
+```
+
+The key name in `extract-files` is the file in the source folder, and the key value is the storage path. The storage path can use the following variables:
+
+- `{php_sdk_path}`: (Windows only) PHP SDK path
+- `{pkg_root_path}`: `pkgroot/`
+- `{working_dir}`: current working directory
+- `{download_path}`: download directory
+- `{source_path}`: source code decompression directory
+
+When `extract-files` does not use variables and is a relative path, the directory of the relative path is `{working_dir}`.
+
+## Open source license
+
+For `source.json`, each source file should contain an open source license. 
+The `license` field stores the open source license information.
+
+Each `license` contains the following parameters:
+
+- `type`: `file` or `text`
+- `path`: the license file in the source code directory (required when `type` is `file`)
+- `text`: License text (required when `type` is `text`)
+
+Example (yaml extension source code with LICENSE file):
+
+```json
+{
+   "yaml": {
+     "type": "git",
+     "path": "php-src/ext/yaml",
+     "rev": "php7",
+     "url": "https://github.com/php/pecl-file_formats-yaml",
+     "license": {
+       "type": "file",
+       "path": "LICENSE"
+     }
+   }
+}
+```
+
+When an open source project has multiple licenses, multiple files can be specified:
+
+```json
+{
+   "libuv": {
+     "type": "ghtar",
+     "repo": "libuv/libuv",
+     "license": [
+       {
+         "type": "file",
+         "path": "LICENSE"
+       },
+       {
+         "type": "file",
+         "path": "LICENSE-extra"
+       }
+     ]
+   }
+}
+```
+
+When the license of an open source project uses different files between versions, 
+`path` can be used as an array to list the possible license files:
+
+```json
+{
+  "redis": {
+    "type": "git",
+    "path": "php-src/ext/redis",
+    "rev": "release/6.0.2",
+    "url": "https://github.com/phpredis/phpredis",
+    "license": {
+      "type": "file",
+      "path": [
+        "LICENSE",
+        "COPYING"
+      ]
+    }
+  }
+}
+```

docs/en/develop/structure.md

@@ -0,0 +1,180 @@
+# Introduction to project structure
+
+static-php-cli mainly contains three logical components: sources, dependent libraries, and extensions.
+These components contains 4 configuration files: `source.json`, `pkg.json`, `lib.json`, and `ext.json`.
+
+A complete process for building standalone static PHP is:
+
+1. Use the source download module `Downloader` to download specified or all source codes. 
+    These sources include PHP source code, dependent library source code, and extension source code.
+2. Use the source decompression module `SourceExtractor` to decompress the downloaded sources to the compilation directory.
+3. Use the dependency tool to calculate the dependent extensions and dependent libraries of the currently added extension, 
+    and then compile each library that needs to be compiled in the order of dependencies.
+4. After building each dependent library using `Builder` under the corresponding operating system, install it to the `buildroot` directory.
+5. If external extensions are included (the source code does not contain extensions within PHP), 
+    copy the external extensions to the `source/php-src/ext/` directory.
+6. Use `Builder` to build the PHP source code and build target to the `buildroot` directory.
+
+The project is mainly divided into several folders:
+
+- `bin/`: used to store program entry files, including `bin/spc`, `bin/spc-alpine-docker`, `bin/setup-runtime`.
+- `config/`: Contains all the extensions and dependent libraries supported by the project, 
+    as well as the download link and download methods of these sources. It is divided into files: `lib.json`, `ext.json`, `source.json`, `pkg.json`, `pre-built.json` .
+- `src/`: The core code of the project, including the entire framework and commands for compiling various extensions and libraries.
+- `vendor/`: The directory that Composer depends on, you do not need to make any modifications to it.
+
+The operating principle is to start a `ConsoleApplication` of `symfony/console`, and then parse the commands entered by the user in the terminal.
+
+## Basic command line structure
+
+`bin/spc` is an entry file, including the Unix common `#!/usr/bin/env php`, 
+which is used to allow the system to automatically execute with the PHP interpreter installed on the system.
+After the project executes `new ConsoleApplication()`, the framework will automatically register them as commands.
+
+The project does not directly use the Command registration method and command execution method recommended by Symfony. Here are small changes:
+
+1. Each command uses the `#[AsCommand()]` Attribute to register the name and description.
+2. Abstract `execute()` so that all commands are based on `BaseCommand` (which is based on `Symfony\Component\Console\Command\Command`), 
+    and the execution code of each command itself is written in the `handle()` method .
+3. Added variable `$no_motd` to `BaseCommand`, which is used to display the Figlet greeting when the command is executed.
+4. `BaseCommand` saves `InputInterface` and `OutputInterface` as member variables. You can use `$this->input` and `$this->output` within the command class.
+
+## Basic source code structure
+
+The source code of the project is located in the `src/SPC` directory, 
+supports automatic loading of the PSR-4 standard, and contains the following subdirectories and classes:
+
+- `src/SPC/builder/`: The core compilation command code used to build libraries, 
+    PHP and related extensions under different operating systems, and also includes some compilation system tool methods.
+- `src/SPC/command/`: All commands of the project are here.
+- `src/SPC/doctor/`: Doctor module, which is a relatively independent module used to check the system environment. 
+    It can be entered using the command `bin/spc doctor`.
+- `src/SPC/exception/`: exception class.
+- `src/SPC/store/`: Classes related to storage, files and sources are all here.
+- `src/SPC/util/`: Some reusable tool methods are here.
+- `src/SPC/ConsoleApplication.php`: command line program entry file.
+
+If you have read the source code, you may find that there is also a `src/globals/` directory, 
+which is used to store some global variables, global methods, 
+and non-PSR-4 standard PHP source code that is relied upon during the build process, such as extension sanity check code etc.
+
+## Phar application directory issue
+
+Like other php-cli projects, spc itself has additional considerations for paths.
+Because spc can run in multiple modes such as `php-cli directly`, `micro SAPI`, `php-cli with Phar`, `vendor with Phar`, etc., 
+there are ambiguities in various root directories. A complete explanation is given here.
+This problem is generally common in the base class path selection problem of accessing files in PHP projects, especially when used with `micro.sfx`.
+
+Note that this may only be useful for you when developing Phar projects or PHP frameworks.
+
+> Next, we will treat `static-php-cli` (that is, spc) as a normal `php` command line program. You can understand spc as any of your own php-cli applications for reference.
+
+There are three basic constant theoretical values below. We recommend that you introduce these three constants when writing PHP projects:
+
+- `WORKING_DIR`: the working directory when executing PHP scripts
+
+- `SOURCE_ROOT_DIR` or `ROOT_DIR`: the root directory of the project folder, generally the directory where `composer.json` is located
+
+- `FRAMEWORK_ROOT_DIR`: the root directory of the framework used, which may be used by self-developed frameworks. Generally, the framework directory is read-only
+
+You can define these constants in your framework entry or cli applications to facilitate the use of paths in your project.
+
+The following are PHP built-in constant values, which have been defined inside the PHP interpreter:
+
+- `__DIR__`: the directory where the file of the currently executed script is located
+
+- `__FILE__`: the file path of the currently executed script
+
+### Git project mode (source)
+
+Git project mode refers to a framework or program itself stored in plain text in the current folder, and running through `php path/to/entry.php`.
+
+Assume that your project is stored in the `/home/example/static-php-cli/` directory, or your project is the framework itself, 
+which contains project files such as `composer.json`:
+
+```
+composer.json
+src/App/MyCommand.app
+vendor/*
+bin/entry.php
+```
+
+We assume that the above constants are obtained from `src/App/MyCommand.php`:
+
+| Constant             | Value                                                |
+|----------------------|------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/static-php-cli`                       |
+| `SOURCE_ROOT_DIR`    | `/home/example/static-php-cli`                       |
+| `FRAMEWORK_ROOT_DIR` | `/home/example/static-php-cli`                       |
+| `__DIR__`            | `/home/example/static-php-cli/src/App`               |
+| `__FILE__`           | `/home/example/static-php-cli/src/App/MyCommand.php` |
+
+In this case, the values of `WORKING_DIR`, `SOURCE_ROOT_DIR`, and `FRAMEWORK_ROOT_DIR` are exactly the same: `/home/example/static-php-cli`.
+
+The source code of the framework and the source code of the application are both in the current path.
+
+### Vendor library mode (vendor)
+
+The vendor library mode generally means that your project is a framework or is installed into the project as a composer dependency by other applications, 
+and the storage location is in the `vendor/author/XXX` directory.
+
+Suppose your project is `crazywhalecc/static-php-cli`, and you or others install this project in another project using `composer require`.
+
+We assume that static-php-cli contains all files except the `vendor` directory with the same `Git mode`, and get the constant value from `src/App/MyCommand`,
+Directory constant should be:
+
+| Constant             | Value                                                                                |
+|----------------------|--------------------------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/another-app`                                                          |
+| `SOURCE_ROOT_DIR`    | `/home/example/another-app`                                                          |
+| `FRAMEWORK_ROOT_DIR` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli`                       |
+| `__DIR__`            | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App`               |
+| `__FILE__`           | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |
+
+Here `SOURCE_ROOT_DIR` refers to the root directory of the project using `static-php-cli`.
+
+### Git project Phar mode (source-phar)
+
+Git project Phar mode refers to the mode of packaging the project directory of the Git project mode into a `phar` file. We assume that `/home/example/static-php-cli` will be packaged into a Phar file, and the directory has the following files:
+
+```
+composer.json
+src/App/MyCommand.app
+vendor/*
+bin/entry.php
+```
+
+When packaged into `app.phar` and stored in the `/home/example/static-php-cli` directory, `app.phar` is executed at this time. Assuming that the `src/App/MyCommand` code is executed, the constant is obtained in the file:
+
+| Constant             | Value                                                                |
+|----------------------|----------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/static-php-cli`                                       |
+| `SOURCE_ROOT_DIR`    | `phar:///home/example/static-php-cli/app.phar/`                      |
+| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/static-php-cli/app.phar/`                      |
+| `__DIR__`            | `phar:///home/example/static-php-cli/app.phar/src/App`               |
+| `__FILE__`           | `phar:///home/example/static-php-cli/app.phar/src/App/MyCommand.php` |
+
+Because the `phar://` protocol is required to read files in the phar itself, the project root directory and the framework directory will be different from `WORKING_DIR`.
+
+### Vendor Library Phar Mode (vendor-phar)
+
+Vendor Library Phar Mode means that your project is installed as a framework in other projects and stored in the `vendor` directory.
+
+We assume that your project directory structure is as follows:
+
+```
+composer.json                           # Composer configuration file of the current project
+box.json                                # Configuration file for packaging Phar
+another-app.php                         # Entry file of another project
+vendor/crazywhalecc/static-php-cli/*    # Your project is used as a dependent library
+```
+
+When packaging these files under the directory `/home/example/another-app/` into `app.phar`, the value of the following constant for your project should be:
+
+| Constant             | Value                                                                                                |
+|----------------------|------------------------------------------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/another-app`                                                                          |
+| `SOURCE_ROOT_DIR`    | `phar:///home/example/another-app/app.phar/`                                                         |
+| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli`                       |
+| `__DIR__`            | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App`               |
+| `__FILE__`           | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |

docs/en/develop/system-build-tools.md

@@ -0,0 +1,242 @@
+# Compilation Tools
+
+static-php-cli uses many system compilation tools when building static PHP. These tools mainly include:
+
+- `autoconf`: used to generate `configure` scripts.
+- `make`: used to execute `Makefile`.
+- `cmake`: used to execute `CMakeLists.txt`.
+- `pkg-config`: Used to find the installation path of dependent libraries.
+- `gcc`: used to compile C/C++ projects under Linux.
+- `clang`: used to compile C/C++ projects under macOS.
+
+For Linux and macOS operating systems, 
+these tools can usually be installed through the package manager, which is written in the doctor module.
+Theoretically we can also compile and download these tools manually, 
+but this will increase the complexity of compilation, so we do not recommend this.
+
+## Linux Compilation Tools
+
+For Linux systems, different distributions have different installation methods for compilation tools. 
+And for static compilation, the package management of some distributions cannot install libraries and tools for pure static compilation.
+Therefore, for the Linux platform and its different distributions, 
+we currently provide a variety of compilation environment preparations.
+
+### Glibc Environment
+
+The glibc environment refers to the underlying `libc` library of the system 
+(that is, the C standard library that all programs written in C language are dynamically linked to) uses `glibc`, 
+which is the default environment for most distributions.
+For example: Ubuntu, Debian, CentOS, RHEL, openSUSE, Arch Linux, etc.
+
+In the glibc environment, the package management and compiler we use point to glibc by default, 
+and glibc cannot be statically linked well. 
+One of the reasons it cannot be statically linked is that its network library `nss` cannot be compiled statically.
+
+For the glibc environment, in static-php-cli and spc in 2.0-RC8 and later, you can choose two ways to build static PHP:
+
+1. Use Docker to build, you can use `bin/spc-alpine-docker` to build, it will build an Alpine Linux docker image.
+2. Use `bin/spc doctor --auto-fix` to install the `musl-wrapper` and `musl-cross-make` packages, and then build directly. 
+([Related source code](https://github.com/crazywhalecc/static-php-cli/blob/main/src/SPC/doctor/item/LinuxMuslCheck.php))
+
+Generally speaking, the build results in these two environments are consistent, and you can choose according to actual needs.
+
+In the doctor module, static-php-cli will first detect the current Linux distribution. 
+If the current distribution is a glibc environment, you will be prompted to install the musl-wrapper and musl-cross-make packages.
+
+The process of installing `musl-wrapper` in the glibc environment is as follows:
+
+1. Download the specific version of [musl-wrapper source code](https://musl.libc.org/releases/) from the musl official website.
+2. Use `gcc` installed from the package management to compile the musl-wrapper source code and generate `musl-libc` and other libraries: `./configure --disable-gcc-wrapper && make -j && sudo make install`.
+3. The musl-wrapper related libraries will be installed in the `/usr/local/musl` directory.
+
+The process of installing `musl-cross-make` in the glibc environment is as follows:
+
+1. Download the precompiled [musl-cross-make](https://dl.static-php.dev/static-php-cli/deps/musl-toolchain/) compressed package from dl.static-php.dev .
+2. Unzip to the `/usr/local/musl` directory.
+
+::: tip
+In the glibc environment, static compilation can be achieved by directly installing musl-wrapper, 
+but musl-wrapper only contains `musl-gcc` and not `musl-g++`, which means that C++ code cannot be compiled.
+So we need musl-cross-make to provide `musl-g++`.
+
+The reason why the musl-cross-make package cannot be compiled directly locally is that 
+its compilation environment requirements are relatively high (requires more than 36GB of memory, compiled under Alpine Linux), 
+so we provide precompiled binary packages that can be used for all Linux distributions.
+
+At the same time, the package management of some distributions provides musl-wrapper, 
+but musl-cross-make needs to match the corresponding musl-wrapper version, 
+so we do not use package management to install musl-wrapper.
+
+Compiling musl-cross-make will be introduced in the **musl-cross-make Toolchain Compilation** section of this chapter.
+:::
+
+### Musl Environment
+
+The musl environment refers to the system's underlying `libc` library that uses `musl`, 
+which is a lightweight C standard library that can be well statically linked.
+
+For the currently popular Linux distributions, Alpine Linux uses the musl environment, 
+so static-php-cli can directly build static PHP under Alpine Linux. 
+You only need to install basic compilation tools (such as `gcc`, `cmake`, etc.) directly from the package management.
+
+For other distributions, if your distribution uses the musl environment, 
+you can also use static-php-cli to build static PHP directly after installing the necessary compilation tools.
+
+::: tip
+In the musl environment, static-php-cli will automatically skip the installation of musl-wrapper and musl-cross-make.
+:::
+
+### Docker Environment
+
+The Docker environment refers to using Docker containers to build static PHP. You can use `bin/spc-alpine-docker` to build.
+Before executing this command, you need to install Docker first, and then execute `bin/spc-alpine-docker` in the project root directory.
+
+After executing `bin/spc-alpine-docker`, static-php-cli will automatically download the Alpine Linux image and then build a `cwcc-spc-x86_64` or `cwcc-spc-aarch64` image.
+Then all build process is performed within this image, which is equivalent to compiling in Alpine Linux.
+
+## musl-cross-make Toolchain Compilation
+
+In Linux, although you do not need to manually compile the musl-cross-make tool, 
+if you want to understand its compilation process, you can refer here.
+Another important reason is that this may not be compiled using automated tools such as CI and Actions, 
+because the existing CI service compilation environment does not meet the compilation requirements of musl-cross-make, 
+and the configuration that meets the requirements is too expensive.
+
+The compilation process of musl-cross-make is as follows:
+
+Prepare an Alpine Linux environment (either directly installed or using Docker). 
+The compilation process requires more than **36GB** of memory, 
+so you need to compile on a machine with larger memory. 
+Without this much memory, compilation may fail.
+
+Then write the following content into the `config.mak` file:
+
+```makefile
+STAT = -static --static
+FLAG = -g0 -Os -Wno-error
+
+ifneq ($(NATIVE),)
+COMMON_CONFIG += CC="$(HOST)-gcc ${STAT}" CXX="$(HOST)-g++ ${STAT}"
+else
+COMMON_CONFIG += CC="gcc ${STAT}" CXX="g++ ${STAT}"
+endif
+
+COMMON_CONFIG += CFLAGS="${FLAG}" CXXFLAGS="${FLAG}" LDFLAGS="${STAT}"
+
+BINUTILS_CONFIG += --enable-gold=yes --enable-gprofng=no
+GCC_CONFIG += --enable-static-pie --disable-cet --enable-default-pie  
+#--enable-default-pie
+
+CONFIG_SUB_REV = 888c8e3d5f7b
+GCC_VER = 13.2.0
+BINUTILS_VER = 2.40
+MUSL_VER = 1.2.4
+GMP_VER = 6.2.1
+MPC_VER = 1.2.1
+MPFR_VER = 4.2.0
+LINUX_VER = 6.1.36
+```
+
+And also you need to add `gcc-13.2.0.tar.xz.sha1` file, contents here:
+
+```
+5f95b6d042fb37d45c6cbebfc91decfbc4fb493c  gcc-13.2.0.tar.xz
+```
+
+If you are using Docker to build, create a new `Dockerfile` file and write the following content:
+
+```dockerfile
+FROM alpine:edge
+
+RUN apk add --no-cache \
+gcc g++ git make curl perl \
+rsync patch wget libtool \
+texinfo autoconf automake \
+bison tar xz bzip2 zlib \
+file binutils flex \
+linux-headers libintl \
+gettext gettext-dev icu-libs pkgconf \
+pkgconfig icu-dev bash \
+ccache libarchive-tools zip
+
+WORKDIR /opt
+
+RUN git clone https://git.zv.io/toolchains/musl-cross-make.git
+WORKDIR /opt/musl-cross-make
+COPY config.mak /opt/musl-cross-make
+COPY gcc-13.2.0.tar.xz.sha1 /opt/musl-cross-make/hashes
+
+RUN make TARGET=x86_64-linux-musl -j || :
+RUN sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
+RUN make TARGET=x86_64-linux-musl -j
+RUN make TARGET=x86_64-linux-musl install -j
+RUN tar cvzf x86_64-musl-toolchain.tgz output/*
+```
+
+If you are using Alpine Linux in a non-Docker environment, you can directly execute the commands in the Dockerfile, for example:
+
+```bash
+apk add --no-cache \
+gcc g++ git make curl perl \
+rsync patch wget libtool \
+texinfo autoconf automake \
+bison tar xz bzip2 zlib \
+file binutils flex \
+linux-headers libintl \
+gettext gettext-dev icu-libs pkgconf \
+pkgconfig icu-dev bash \
+ccache libarchive-tools zip
+
+git clone https://git.zv.io/toolchains/musl-cross-make.git
+# Copy config.mak to the working directory of musl-cross-make.
+# You need to replace /path/to/config.mak with your config.mak file path.
+cp /path/to/config.mak musl-cross-make/
+cp /path/to/gcc-13.2.0.tar.xz.sha1 musl-cross-make/hashes
+
+make TARGET=x86_64-linux-musl -j || :
+sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
+make TARGET=x86_64-linux-musl -j
+make TARGET=x86_64-linux-musl install -j
+tar cvzf x86_64-musl-toolchain.tgz output/*
+```
+
+::: tip
+All the above scripts are suitable for x86_64 architecture Linux. 
+If you need to build musl-cross-make for the ARM environment, just replace all `x86_64` above with `aarch64`.
+:::
+
+This compilation process may fail due to insufficient memory, network problems, etc. 
+You can try a few more times, or use a machine with larger memory to compile.
+If you encounter problems or you have better improvement solutions, go to [Discussion](https://github.com/crazywhalecc/static-php-cli-hosted/issues/1).
+
+## macOS Environment
+
+For macOS systems, the main compilation tool we use is `clang`, 
+which is the default compiler for macOS systems and is also the compiler of Xcode.
+
+Compiling under macOS mainly relies on Xcode or Xcode Command Line Tools. 
+You can download Xcode from the App Store, 
+or execute `xcode-select --install` in the terminal to install Xcode Command Line Tools.
+
+In addition, in the `doctor` environment check module, static-php-cli will check whether Homebrew, 
+compilation tools, etc. are installed on the macOS system. 
+If not, you will be prompted to install them. I will not go into details here.
+
+## FreeBSD Environment
+
+FreeBSD is also a Unix system, and its compilation tools are similar to macOS. 
+You can directly use the package management `pkg` to install `clang` and other compilation tools through the `doctor` command.
+
+## pkg-config Compilation (*nix only)
+
+If you observe the compilation log when using static-php-cli to build static PHP, you will find that no matter what is compiled, 
+`pkg-config` will be compiled first. This is because `pkg-config` is a library used to find dependencies.
+In earlier versions of static-php-cli, we directly used the `pkg-config` tool installed by package management, 
+but this would cause some problems, such as:
+
+- Even if `PKG_CONFIG_PATH` is specified, `pkg-config` will try to find dependent packages from the system path.
+- Since `pkg-config` will look for dependent packages from the system path, 
+  if a dependent package with the same name exists in the system, compilation may fail.
+
+In order to avoid the above problems, we compile `pkg-config` into `buildroot/bin` in user mode and use it. 
+We use parameters such as `--without-sysroot` to avoid looking for dependent packages from the system path.

docs/en/faq/index.md

@@ -0,0 +1,108 @@
+# FAQ
+
+Here will be some questions that you may encounter easily. There are currently many, but I need to take time to organize them.
+
+## What is the path of php.ini ?
+
+On Linux, macOS and FreeBSD, the path of `php.ini` is `/usr/local/etc/php/php.ini`.
+On Windows, the path is `C:\windows\php.ini` or the current directory of `php.exe`.
+The directory where to look for `php.ini` can be changed on *nix using the manual build option `--with-config-file-path`.
+
+In addition, on Linux, macOS and FreeBSD, `.ini` files present in the `/usr/local/etc/php/conf.d` directory will also be loaded.
+On Windows, this path is empty by default.
+The directory can be changed using the manual build option `--with-config-file-scan-dir`.
+
+`php.ini` will also be searched for in [the other standard locations](https://www.php.net/manual/configuration.file.php). 
+
+## Can statically-compiled PHP install extensions?
+
+Because the principle of installing PHP extensions under the normal mode is to use `.so` type dynamic link library to install new extensions, 
+and we use the static link PHP compiled by this project. However, static linking has different definitions in different operating systems.
+
+First of all, for Linux systems, statically linked binaries will not link the system's dynamic link library. 
+Purely statically linked binaries (`build with -all-static`) cannot load dynamic libraries, so new extensions cannot be added.
+At the same time, in pure static mode, you cannot use extensions such as `ffi` to load external `.so` modules.
+
+You can use the command `ldd buildroot/bin/php` to check whether the binary you built under Linux is purely statically linked.
+
+If you [build GNU libc based PHP](../guide/build-with-glibc), you can use the `ffi` extension to load external `.so` modules and load `.so` extensions with the same ABI.
+
+For example, you can use the following command to build a static PHP binary dynamically linked with glibc, 
+supporting FFI extensions and loading the `xdebug.so` extension of the same PHP version and the same TS type:
+
+```bash
+bin/spc-gnu-docker download --for-extensions=ffi,xml --with-php=8.4
+bin/spc-gnu-docker build ffi,xml --build-cli --debug
+
+buildroot/bin/php -d "zend_extension=/path/to/php{PHP_VER}-{ts/nts}/xdebug.so" --ri xdebug
+```
+
+For macOS platform, almost all binaries under macOS cannot be truly purely statically linked, and almost all binaries will link macOS system libraries: `/usr/lib/libresolv.9.dylib` and `/usr/lib/libSystem.B.dylib`.
+So on macOS, you can **directly** use SPC to build statically compiled PHP binaries with dynamically linked extensions:
+
+1. Build shared extension `xxx.so` using: `--build-shared=XXX` option. e.g. `bin/spc build bcmath,zlib --build-shared=xdebug --build-cli`
+2. You will get `buildroot/modules/xdebug.so` and `buildroot/bin/php`.
+3. The `xdebug.so` file could be used for php that version and thread-safe are the same.
+
+For the Windows platform, since officially built extensions (such as `php_yaml.dll`) force the use of the `php8.dll` dynamic library as a link, and statically built PHP does not include any dynamic libraries other than system libraries,
+php.exe built by static-php cannot load officially built dynamic extensions. Since static-php-cli does not yet support building dynamic extensions, there is currently no way to load dynamic extensions with static-php.
+
+However, Windows can normally use the `FFI` extension to load other dll files and call them.
+
+## Can it support Oracle database extension?
+
+Some extensions that rely on closed source libraries, such as `oci8`, `sourceguardian`, etc., 
+they do not provide purely statically compiled dependent library files (`.a`), only dynamic dependent library files (`.so`).
+These extensions cannot be compiled into static-php-cli using source code, so this project may never support these extensions.
+However, in theory you can access and use such extensions under macOS and Linux according to the above questions.
+
+If you have a need for such extensions, or most people have needs for these closed-source extensions,
+see the discussion on [standalone-php-cli](https://github.com/crazywhalecc/static-php-cli/discussions/58). Welcome to leave a message.
+
+## Does it support Windows?
+
+The project currently supports Windows, but the number of supported extensions is small. Windows support is not perfect. There are mainly the following problems:
+
+1. The compilation process of Windows is different from that of *nix, and the toolchain used is also different. The compilation tools used to compile the dependent libraries of each extension are almost completely different.
+2. The demand for the Windows version will also be advanced based on the needs of all people who use this project. If many people need it, I will support related extensions as soon as possible.
+
+## Can I protect my source code with micro?
+
+You can't. micro.sfx is essentially combining php and php code into one file, 
+there is no process of compiling or encrypting the PHP code.
+
+First of all, php-src is the official interpreter of PHP code, and there is no PHP compiler compatible with mainstream branches on the market.
+I saw on the Internet that there is a project called BPC (Binary PHP Compiler?) that can compile PHP into binary, 
+but there are many restrictions.
+
+The direction of encrypting and protecting the code is not the same as compiling. 
+After compiling, the code can also be obtained through reverse engineering and other methods. 
+The real protection is still carried out by means of packing and encrypting the code.
+
+Therefore, this project (static-php-cli) and related projects (lwmbs, swoole-cli) all provide a convenient compilation tool for php-src source code.
+The phpmicro referenced by this project and related projects is only a package of PHP's sapi interface, not a compilation tool for PHP code.
+The compiler for PHP code is a completely different project, so the extra cases are not taken into account. 
+If you are interested in encryption, you can consider using existing encryption technologies, 
+such as Swoole Compiler, Source Guardian, etc.
+
+## Unable to use ssl
+
+**Update: This issue has been fixed in the latest version of static-php-cli, which now reads the system's certificate file by default. If you still have problems, try the solution below.**
+
+When using curl, pgsql, etc. to request an HTTPS website or establish an SSL connection, there may be an `error:80000002:system library::No such file or directory` error.
+This error is caused by statically compiled PHP without specifying `openssl.cafile` via `php.ini`.
+
+You can solve this problem by specifying `php.ini` before using PHP and adding `openssl.cafile=/path/to/your-cert.pem` in the INI.
+
+For Linux systems, you can download the [cacert.pem](https://curl.se/docs/caextract.html) file from the curl official website, or you can use the certificate file that comes with the system.
+For the certificate locations of different distros, please refer to [Golang docs](https://go.dev/src/crypto/x509/root_linux.go).
+
+> INI configuration `openssl.cafile` cannot be set dynamically using the `ini_set()` function, because `openssl.cafile` is a `PHP_INI_SYSTEM` type configuration and can only be set in the `php.ini` file.
+
+## Why don't we support older versions of PHP?
+
+Because older versions of PHP have many problems, such as security issues, performance issues, and functional issues. 
+In addition, many older versions of PHP are not compatible with the latest dependency libraries, 
+which is one of the reasons why older versions of PHP are not supported.
+
+You can use older versions compiled earlier by static-php-cli, such as PHP 8.0, but earlier versions will not be explicitly supported.

docs/en/guide/action-build.md

@@ -0,0 +1,31 @@
+# GitHub Action Build
+
+Action Build refers to compiling directly using GitHub Action.
+
+If you don't want to compile it yourself, you can download the artifact from the existing Action in this project, 
+or you can download it from a self-hosted server：[Enter](https://dl.static-php.dev/static-php-cli/common/).
+
+> Self-hosted binaries are also built from Actions: [repo](https://github.com/static-php/static-php-cli-hosted).
+> The extensions included are: bcmath,bz2,calendar,ctype,curl,dom,exif,fileinfo,filter,ftp,gd,gmp,iconv,xml,mbstring,mbregex,mysqlnd,openssl,
+> pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,redis,session,simplexml,soap,sockets,sqlite3,tokenizer,xmlwriter,xmlreader,zlib,zip
+
+## Build Guide
+
+Using GitHub Action makes it easy to build a statically compiled PHP and phpmicro, 
+while also defining the extensions to compile.
+
+1. Fork project.
+2. Go to the Actions of the project and select `CI`.
+3. Select `Run workflow`, fill in the PHP version you want to compile, the target type, and the list of static extensions. (comma separated, e.g. `bcmath,curl,mbstring`)
+4. If you need shared extensions (for example `xdebug`), set `shared-extensions` (comma separated, e.g. `xdebug`).
+5. If you need FrankenPHP, enable `build-frankenphp` and also enable `enable-zts`.
+6. After waiting for about a period of time, enter the corresponding task and get `Artifacts`.
+
+If you enable `debug`, all logs will be output at build time, including compiled logs, for troubleshooting.
+
+> If you need to build in other environments, you can use [manual build](./manual-build).
+
+## Extensions
+
+You can go to [extensions](./extensions) check here to see if all the extensions you need currently support.
+and then go to [command generator](./cli-generator) select the extension you need to compile, copy the extensions string to `extensions` option.

docs/en/guide/build-on-windows.md

@@ -0,0 +1,228 @@
+# Build on Windows
+
+Because the Windows system is an NT kernel, the compilation tools and operating system interfaces 
+used by Unix-like operating systems are almost completely different, 
+so the build process on Windows will be slightly different from that of Unix systems.
+
+## GitHub Actions Build
+
+Building the Windows version of static-php from Actions is now supported.
+Like Linux and macOS, you need to Fork the static-php-cli repository to your GitHub account first, 
+then you can enter [Extension List](./extensions) to select the extension to be compiled, 
+and then go to your own `CI on Windows` select the PHP version, fill in the extension list (comma separated), and click Run.
+
+If you're going to develop or build locally, please read on.
+
+## Requirements
+
+The tools required to build static PHP on Windows are the same as PHP's official Windows build tools. 
+You can read [Official Documentation](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2).
+
+To sum up, you need the following environment and tools:
+
+- Windows 10/11 (requires build 17063 or later)
+- Visual Studio 2019/2022 (recommended 2022)
+- C++ desktop development for Visual Studio
+- Git for Windows
+- [php-sdk-binary-tools](https://github.com/php/php-sdk-binary-tools) (can be installed automatically using doctor)
+- strawberry-perl (can be installed automatically using doctor)
+- nasm (can be installed automatically using doctor)
+
+::: tip
+The construction of static-php-cli on Windows refers to using MSVC to build PHP and is not based on MinGW, Cygwin, WSL and other environments.
+
+If you prefer to use WSL, please refer to the chapter on Building on Linux.
+:::
+
+After installing Visual Studio and selecting the C++ desktop development workload, 
+you may download about 8GB of compilation tools, and the download speed depends on your network conditions.
+
+### Install Git
+
+Git for Windows can be downloaded and installed from [here](https://git-scm.com/download/win) `Standalone Installer 64-bit` version, 
+installed in the default location (`C:\Program Files\Git\`).
+If you don't want to download and install manually, 
+you can also use Visual Studio Installer and check Git in the **Individual component** tab.
+
+### Prepare static-php-cli
+
+Downloading the static-php-cli project is very simple, just use git clone. 
+It is recommended to place the project in `C:\spc-build\` or a similar directory. 
+It is best **not to have spaces in the path**.
+
+```shell
+mkdir "C:\spc-build"
+cd C:\spc-build
+git clone https://github.com/crazywhalecc/static-php-cli.git
+cd static-php-cli
+```
+
+It is a bit strange that static-php-cli itself requires a PHP environment, 
+but now you can quickly install the PHP environment through a script.
+Generally, your computer will not have the Windows version of PHP installed, 
+so we recommend that you use `bin/setup-runtime` directly after downloading static-php-cli to install PHP and Composer in the current directory.
+
+```shell
+# Install PHP and Composer to the ./runtime/ directory
+bin/setup-runtime
+
+# After installation, if you need to use PHP and Composer in global commands, 
+# use the following command to add the runtime/ directory to PATH
+bin/setup-runtime -action add-path
+
+# Delete the runtime/ directory in PATH
+bin/setup-runtime -action remove-path
+```
+
+Finally, now that you have PHP and Composer installed, you need to install static-php-cli's Composer dependencies:
+
+```shell
+composer install
+```
+
+### Install other Tools (automatic)
+
+For `php-sdk-binary-tools`, `strawberry-perl`, and `nasm`, 
+we recommend that you directly use the command `bin/spc doctor` to check and install them.
+
+If doctor successfully installs automatically, please **skip** the steps below to manually install the above tools.
+
+But if the automatic installation fails, please refer to the manual installation method below.
+
+### Install php-sdk-binary-tools (manual)
+
+```shell
+cd C:\spc-build\static-php-cli
+git clone https://github.com/php/php-sdk-binary-tools.git
+```
+
+> You can also set the global variable `PHP_SDK_PATH` in Windows settings and 
+> clone the project to the path corresponding to the variable. 
+> Under normal circumstances, you don't need to change it.
+
+### Install strawberry-perl (manual)
+
+> If you don't need to compile the openssl extension, you don't need to install perl.
+
+1. Download the latest version of strawberry-perl from [GitHub](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/).
+2. Install to the `C:\spc-build\static-php-cli\pkgroot\perl\` directory.
+
+> You can download the `-portable` version and extract it directly to the above directory.
+> The last `perl.exe` should be located at `C:\spc-build\static-php-cli\pkgroot\perl\perl\bin\perl.exe`.
+
+### Install nasm (manual)
+
+> If you don't need to compile openssl extension, you don't need to install nasm.
+
+1. Download the nasm tool (x64) from [official website](https://www.nasm.us/pub/nasm/releasebuilds/).
+2. Place `nasm.exe` and `ndisasm.exe` in the `C:\spc-build\static-php-cli\php-sdk-binary-tools\bin\` directory.
+
+## Download required sources
+
+Same as [Manual build - Download](./manual-build.html#command-download)
+
+## Build PHP
+
+Use the build command to start building the static php binary.
+Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
+It is recommended to use `doctor` to check the environment.
+
+### Build SAPI
+
+You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
+and then use the command `bin/spc build` to compile.
+You need to specify targets, choose from the following parameters (at least one):
+
+- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
+- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
+
+```shell
+# Compile PHP with bcmath,openssl,zlib extensions, the compilation target is cli
+bin/spc build "bcmath,openssl,zlib" --build-cli
+
+# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro and cli
+bin/spc build "bcmath,openssl,zlib" --build-micro --build-cli
+```
+
+::: warning
+In Windows, it is best to use double quotes to wrap parameters containing commas, such as `"bcmath,openssl,mbstring"`.
+:::
+
+### Debug
+
+If you encounter problems during the compilation process, or want to view each executing shell command,
+you can use `--debug` to enable debug mode and view all terminal logs:
+
+```shell
+bin/spc build "openssl" --build-cli --debug
+```
+
+### Build Options
+
+During the compilation process, in some special cases,
+the compiler and the content of the compilation directory need to be intervened.
+You can try to use the following commands:
+
+- `--with-clean`: clean up old make files before compiling PHP
+- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
+- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extension optional functions 
+- `--with-config-file-scan-dir=XXX`: Set the directory to scan for `.ini` files after reading `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
+- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
+- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
+- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
+- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
+- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
+- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
+- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
+- `--with-micro-logo=XXX.ico`: Customize the icon of the `exe` executable file after customizing the micro build (in the format of `.ico`)
+
+Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
+
+```shell
+bin/spc build "bcmath,openssl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
+```
+
+Another example: Customize our hello-world.exe program logo:
+
+```shell
+bin/spc build "ffi,bcmath" --build-micro --with-micro-logo=mylogo.ico --debug
+bin/spc micro:combine hello.php
+# Then we got `my-app.exe` with custom logo!
+my-app.exe
+```
+
+## Use php.exe
+
+After php.exe is compiled, it is located in the `buildroot\bin\` directory. You can copy it to any location for use.
+
+```shell
+.\php -v
+```
+
+## Use micro.sfx
+
+> phpmicro is a SelF-extracted eXecutable SAPI module,
+> provided by [phpmicro](https://github.com/dixyes/phpmicro) project.
+> But this project is using a [fork](https://github.com/static-php/phpmicro) of phpmicro, because we need to add some features to it.
+> It can put php runtime and your source code together.
+
+The final compilation result will output a file named `./micro.sfx`,
+which needs to be used with your PHP source code like `code.php`.
+This file will be located in the path `buildroot/bin/micro.sfx`.
+
+Prepare your project source code, which can be a single PHP file or a Phar file, for use.
+
+> If you want to combine phar files, you must add `phar` extension when compiling!
+
+```shell
+# code.php "<?php echo 'Hello world' . PHP_EOL;"
+bin/spc micro:combine code.php -O my-app.exe
+# Run it!!! Copy it to another computer!!!
+./my-app.exe
+```
+
+If you package a PHAR file, just replace `code.php` with the phar file path.
+You can use [box-project/box](https://github.com/box-project/box) to package your CLI project as Phar,
+It is then combined with phpmicro to produce a standalone executable binary.
+
+For more details on the `micro:combine` command, refer to [command](./manual-build) on Unix systems.

docs/en/guide/build-with-glibc.md

@@ -0,0 +1,64 @@
+# Build glibc Compatible Linux Binary
+
+## Why Build glibc Compatible Binary
+
+Currently, the binaries built by static-php-cli on Linux by default are based on musl-libc (statically linked). 
+musl-libc is a lightweight libc implementation 
+that aims to be compatible with glibc and provides good support for pure static linking. 
+This means that the compiled static PHP executable can be used on almost any Linux distribution without worrying about the versions of libc, libstdc++, etc.
+
+However, there are some issues with pure static linking of musl-libc binaries on Linux:
+
+- The `dl()` function in PHP cannot be used to load dynamic libraries and external PHP extensions.
+- The FFI extension in PHP cannot be used.
+- In some extreme cases, performance issues may occur. See [musl-libc performance issues](https://github.com/php/php-src/issues/13648).
+
+Different Linux distributions use different default libc. 
+For example, Alpine Linux uses musl libc, while most Linux distributions use glibc. 
+However, even so, we cannot directly use any distribution using glibc to build portable static binaries because glibc has some issues:
+
+- Binaries built with gcc and other tools on newer versions of distributions cannot run on older versions of distributions.
+- glibc is not recommended to be statically linked because some of its features require the support of dynamic libraries.
+
+However, we can use Docker to solve this problem. 
+The final output is a binary **dynamically linked with glibc** and some necessary libraries, 
+but **statically linked with all other dependencies**.
+
+1. Use an older version of a Linux distribution (such as CentOS 7.x), which has an older version of glibc but can run on most modern Linux distributions.
+2. Build the static binary of PHP in this container so that it can run on most modern Linux distributions.
+
+> Using glibc static binaries can run on most modern Linux distributions but cannot run on musl libc distributions, such as CentOS 6, Alpine Linux, etc.
+
+## Build glibc Compatible Linux Binary
+
+The latest version of static-php-cli includes the `bin/spc-gnu-docker` script, 
+which can create a CentOS 7.x (glibc-2.17) Docker container with one click and build a glibc compatible PHP static binary in the container.
+
+Then, run the following command once. 
+The first run will take a long time because it needs to download the CentOS 7.x image and some build tools.
+
+```bash
+bin/spc-gnu-docker
+```
+
+After the image is built, you will see the same command help menu as `bin/spc`, which means the container is ready.
+
+After the container is ready, you can refer to the [local build](./manual-build) section to build your PHP static binary. 
+Just replace `bin/spc` or `./spc` with `bin/spc-gnu-docker`.
+
+```bash
+bin/spc-gnu-docker build bcmath,ctype,openssl,pdo,phar,posix,session,tokenizer,xml,zip --build-cli --debug
+```
+
+## Notes
+
+In rare cases, glibc-based static PHP may encounter segment faults and other errors, but there are currently few examples. 
+If you encounter any issues, please submit an issue.
+
+glibc build is an extended feature and is not part of the default static-php support. 
+If you have related issues or requirements, please indicate that you are building based on glibc when submitting an issue.
+
+If you need to build glibc-based binaries without using Docker, 
+please refer to the `bin/spc-gnu-docker` script to manually create a similar environment.
+
+Please keep in mind that we only support glibc build with `bin/spc-gnu-docker`. Compilation on RHEL 9 & 10 has been tested and is stable, but if you run into issues, we may choose not to fix them.

docs/en/guide/cli-generator.md

@@ -0,0 +1,16 @@
+---
+aside: false
+---
+
+<script setup lang="ts">
+import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
+</script>
+
+# CLI Build Command Generator
+
+::: tip
+The extensions selected below may contain extensions that are not supported by the selected operating system, 
+which may cause compilation to fail. Please check [Supported Extensions](./extensions) first.
+:::
+
+<cli-generator lang="en" />

docs/en/guide/deps-map.md

@@ -0,0 +1,26 @@
+---
+outline: 'deep'
+---
+
+# Dependency Table
+
+When compiling PHP, each extension and library has dependencies, which may be required or optional.
+You can choose whether to include these optional dependencies.
+
+For example, when compiling the `gd` extension under Linux, 
+the `zlib,libpng` libraries and the `zlib` extension are forced to be compiled, 
+while the `libavif,libwebp,libjpeg,freetype` libraries are optional libraries and will not be compiled by default
+unless specified by the `--with-libs=avif,webp,jpeg,freetype` option.
+
+- For optional extensions (optional features of extensions), you need to specify them manually at compile time, for example, to enable igbinary support for Redis: `bin/spc build redis,igbinary`.
+- For optional libraries, you need to compile and specify them through the `--with-libs=XXX` option.
+- If you want to enable all optional extensions, you can use `bin/spc build redis --with-suggested-exts`.
+- If you want to enable all optional libraries, you can use `--with-suggested-libs`.
+
+## Extension Dependency Table
+
+<!--@include: ../../deps-map-ext.md-->
+
+## Library Dependency Table
+
+<!--@include: ../../deps-map-lib.md-->

docs/en/guide/env-vars.md

@@ -0,0 +1,121 @@
+# Environment variables
+
+All environment variables mentioned in the list on this page have default values unless otherwise noted. 
+You can override the default values by setting these environment variables.
+
+## Environment variables list
+
+Starting from version 2.3.5, we have centralized the environment variables in the `config/env.ini` file.
+You can set environment variables by modifying this file.
+
+We divide the environment variables supported by static-php-cli into three types:
+
+- Global internal environment variables: declared after static-php-cli starts, you can use `getenv()` to get them internally in static-php-cli, and you can override them before starting static-php-cli.
+- Fixed environment variables: declared after static-php-cli starts, you can only use `getenv()` to get them, but you cannot override them through shell scripts.
+- Config file environment variables: declared before static-php-cli build, you can set these environment variables by modifying the `config/env.ini` file or through shell scripts.
+
+You can read the comments for each parameter in [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/main/config/env.ini) to understand its purpose.
+
+## Custom environment variables
+
+Generally, you don't need to modify any of the following environment variables as they are already set to optimal values.
+However, if you have special needs, you can set these environment variables to meet your needs 
+(for example, you need to debug PHP performance under different compilation parameters).
+
+If you want to use custom environment variables, you can use the `export` command in the terminal or set the environment variables directly before the command, for example:
+
+```shell
+# export first
+export SPC_CONCURRENCY=4
+bin/spc build mbstring,pcntl --build-cli
+
+# or direct use
+SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli
+```
+
+Or, if you need to modify an environment variable for a long time, you can modify the `config/env.ini` file.
+
+`config/env.ini` is divided into three sections, `[global]` is globally effective, `[windows]`, `[macos]`, `[linux]` are only effective for the corresponding operating system.
+
+For example, if you need to modify the `./configure` command for compiling PHP, you can find the `SPC_CMD_PREFIX_PHP_CONFIGURE` environment variable in the `config/env.ini` file, and then modify its value.
+
+If your build conditions are more complex and require multiple `env.ini` files to switch, 
+we recommend that you use the `config/env.custom.ini` file.
+In this way, you can specify your environment variables by writing additional override items 
+without modifying the default `config/env.ini` file.
+
+```ini
+; This is an example of `config/env.custom.ini` file, 
+; we modify the `SPC_CONCURRENCY` and linux default CFLAGS passing to libs and PHP
+[global]
+SPC_CONCURRENCY=4
+
+[linux]
+SPC_DEFAULT_C_FLAGS="-O3"
+```
+
+## Library environment variables (Unix only)
+
+Starting from 2.2.0, static-php-cli supports custom environment variables for all compilation dependent library commands of macOS, Linux, FreeBSD and other Unix systems.
+
+In this way, you can adjust the behavior of compiling dependent libraries through environment variables at any time. 
+For example, you can set the optimization parameters for compiling the xxx library through `xxx_CFLAGS=-O0`.
+
+Of course, not every library supports the injection of environment variables. 
+We currently provide three wildcard environment variables with the suffixes:
+
+- `_CFLAGS`: CFLAGS for the compiler
+- `_LDFLAGS`: LDFLAGS for the linker
+- `_LIBS`: LIBS for the linker
+
+The prefix is the name of the dependent library, and the specific name of the library is subject to `lib.json`. 
+Among them, the library name with `-` needs to replace `-` with `_`.
+
+Here is an example of an optimization option that replaces the openssl library compilation:
+
+```shell
+openssl_CFLAGS="-O0"
+```
+
+The library name uses the same name listed in `lib.json` and is case-sensitive.
+
+::: tip
+When no relevant environment variables are specified, except for the following variables, the remaining values are empty by default:
+
+| var name              | var default value                                                                               |
+|-----------------------|-------------------------------------------------------------------------------------------------|
+| `pkg_config_CFLAGS`   | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
+| `pkg_config_LDFLAGS`  | Linux: `--static`, Other: empty                                                                 |
+| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty                                                                  |
+| `imagemagick_LIBS`    | macOS: `-liconv`, Other: empty                                                                  |
+| `ldap_LDFLAGS`        | `-L$BUILD_LIB_PATH`                                                                             |
+| `openssl_CFLAGS`      | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty                                                     |
+| others...             | empty                                                                                           |
+:::
+
+The following table is a list of library names that support customizing the above three variables:
+
+| lib name    |
+|-------------|
+| brotli      |
+| bzip        |
+| curl        |
+| freetype    |
+| gettext     |
+| gmp         |
+| imagemagick |
+| ldap        |
+| libargon2   |
+| libavif     |
+| libcares    |
+| libevent    |
+| openssl     |
+
+::: tip
+Because adapting custom environment variables to each library is a particularly tedious task, 
+and in most cases you do not need custom environment variables for these libraries, 
+so we currently only support custom environment variables for some libraries.
+
+If the library you need to customize environment variables is not listed above, 
+you can submit your request through [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues).
+:::

docs/en/guide/extension-notes.md

@@ -0,0 +1,168 @@
+# Extension Notes
+
+Because it is a static compilation, extensions will not compile 100% perfectly, 
+and different extensions have different requirements for PHP and the environment, 
+which will be listed one by one here.
+
+## curl
+
+HTTP3 support is not enabled by default, compile with `--with-libs="nghttp2,nghttp3,ngtcp2"` to enable HTTP3 support for PHP >= 8.4.
+
+When using curl to request HTTPS, there may be an `error:80000002:system library::No such file or directory` error.
+For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
+
+## phpmicro
+
+1. Only PHP >= 8.0 is supported.
+
+## swoole
+
+1. swoole >= 5.0 Only PHP >= 8.0 is supported.
+2. swoole Currently, curl hooks are not supported for PHP 8.0.x (which may be fixed in the future).
+3. When compiling, if only `swoole` extension is included, the supported Swoole database coroutine hook will not be fully enabled. 
+   If you need to use it, please add the corresponding `swoole-hook-xxx` extension.
+4. The `zend_mm_heap corrupted` problem may occur in swoole under some extension combinations. The cause has not yet been found.
+
+## swoole-hook-pgsql
+
+swoole-hook-pgsql is not an extension, it's a Hook feature of Swoole.
+If you use `swoole,swoole-hook-pgsql`, you will enable Swoole's PostgreSQL client and the coroutine mode of the `pdo_pgsql` extension.
+
+swoole-hook-pgsql conflicts with the `pdo_pgsql` extension. If you want to use Swoole and `pdo_pgsql`, please delete the pdo_pgsql extension and enable `swoole` and `swoole-hook-pgsql`.
+This extension contains an implementation of the coroutine environment for `pdo_pgsql`.
+
+On macOS systems, `pdo_pgsql` may not be able to connect to the postgresql server normally, please use it with caution.
+
+## swoole-hook-mysql
+
+swoole-hook-mysql is not an extension, it's a Hook feature of Swoole.
+If you use `swoole,swoole-hook-mysql`, you will enable the coroutine mode of Swoole's `mysqlnd` and `pdo_mysql`.
+
+## swoole-hook-sqlite
+
+swoole-hook-sqlite is not an extension, it's a Hook feature of Swoole.
+If you use `swoole,swoole-hook-sqlite`, you will enable the coroutine mode of Swoole's `pdo_sqlite` (Swoole must be 5.1 or above).
+
+swoole-hook-sqlite conflicts with the `pdo_sqlite` extension. If you want to use Swoole and `pdo_sqlite`, please delete the pdo_sqlite extension and enable `swoole` and `swoole-hook-sqlite`.
+This extension contains an implementation of the coroutine environment for `pdo_sqlite`.
+
+## swoole-hook-odbc
+
+swoole-hook-odbc is not an extension, it's a Hook feature of Swoole.
+If you use `swoole,swoole-hook-odbc`, you will enable the coroutine mode of Swoole's `odbc` extension.
+
+swoole-hook-odbc conflicts with the `pdo_odbc` extension. If you want to use Swoole and `pdo_odbc`, please delete the `pdo_odbc` extension and enable `swoole` and `swoole-hook-odbc`.
+This extension contains an implementation of the coroutine environment for `pdo_odbc`.
+
+## swow
+
+1. Only PHP 8.0+ is supported.
+
+## imagick
+
+1. OpenMP support is disabled, this is recommended by the maintainers and also the case system packages.
+
+## imap
+
+1. Kerberos is not supported
+2. ext-imap is not thread safe due to the underlying c-client. It's not possible to use it in `--enable-zts` builds.
+3. The extension was dropped from php 8.4, we recommend you look for an alternative implementation, such as [Webklex/php-imap](https://github.com/Webklex/php-imap)
+
+## gd
+
+1. gd Extension relies on more additional Graphics library. By default, 
+using `bin/spc build gd` directly will not support some Graphics library, such as `libjpeg`, `libavif`, etc.
+Currently, it supports four libraries: `freetype,libjpeg,libavif,libwebp`. 
+Therefore, the following command can be used to introduce them into the gd library:
+
+```bash
+bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
+```
+
+## mcrypt
+
+1. Currently not supported, and this extension will not be supported in the future. [#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
+
+## oci8
+
+1. oci8 is an extension of the Oracle database, because the library on which the extension provided by Oracle does not provide a statically compiled version (`.a`) or source code, 
+and this extension cannot be compiled into php by static linking, so it cannot be supported.
+
+## xdebug
+
+1. Xdebug is only buildable as a shared extension. On Linux, you'll need to use a SPC_TARGET like `native-native -dynamic` or `native-native-gnu`.
+2. When using Linux/glibc or macOS, you can compile Xdebug as a shared extension using --build-shared="xdebug". 
+   The compiled `./php` binary can be configured and run by specifying the INI, eg `./php -d 'zend_extension=/path/to/xdebug.so' your-code.php`.
+
+## xml
+
+1. xml includes xml, xmlreader, xmlwriter, xsl, dom, simplexml, etc. 
+    When adding xml extensions, it is best to enable these extensions at the same time.
+2. libxml is included in xml extension. Enabling xml is equivalent to enabling libxml.
+
+## glfw
+
+1. glfw depends on OpenGL, and linux environment also needs X11, which cannot be linked statically.
+2. macOS platform, we can compile and link system builtin OpenGL and related libraries dynamically.
+
+## rar
+
+1. The rar extension currently has a problem when compiling phpmicro with the `common` extension collection in the macOS x86_64 environment.
+
+## pgsql
+
+~~pgsql ssl connection is not compatible with openssl 3.2.0. See:~~
+
+- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
+- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
+- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
+
+pgsql 16.2 has fixed this bug, now it's working.
+
+When pgsql uses SSL connection, there may be `error:80000002:system library::No such file or directory` error,
+For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
+
+## openssl
+
+When using openssl-based extensions (such as curl, pgsql and other network libraries),
+there may be an `error:80000002:system library::No such file or directory` error.
+For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
+
+## password-argon2
+
+1. password-argon2 is not a standard extension. The algorithm `PASSWORD_ARGON2ID` for the `password_hash` function needs libsodium or libargon2 to work.
+2. using password-argon2 enables multithread support for this.
+
+## ffi
+
+1. Due to the limitation of musl libc's static linkage, you cannot use ffi because dynamic libraries cannot be loaded. 
+   If you need to use the ffi extension, see [Compile PHP with GNU libc](./build-with-glibc).
+2. macOS supports the ffi extension, but errors will occur when some kernels do not contain debugging symbols.
+3. Windows x64 supports the ffi extension.
+
+## xhprof
+
+The xhprof extension consists of three parts: `xhprof_extension`, `xhprof_html`, `xhprof_libs`. 
+Only `xhprof_extension` is included in the compiled binary.
+If you need to use xhprof,
+please download the source code from [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) and specify the `xhprof_libs` and `xhprof_html` paths for use.
+
+## event
+
+If you enable event extension on macOS, the `openpty` will be disabled due to issue:
+
+- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
+
+## parallel
+
+Parallel is only supported on PHP 8.0 ZTS and above.
+
+## spx
+
+1. SPX does not support Windows, and the official repository does not support static compilation. static-php-cli uses a [modified version](https://github.com/static-php/php-spx).
+
+## mimalloc
+
+1. This is not technically an extension, but a library.
+2. Building with `--with-libs="mimalloc"` on Linux or macOS will override the default allocator.
+3. This is experimental for now, but is recommended in threaded environments.

docs/en/guide/extensions.md

@@ -0,0 +1,23 @@
+<script setup>
+import SearchTable from "../../.vitepress/components/SearchTable.vue";
+</script>
+
+# Extensions
+
+> - `yes`: supported
+> - _blank_: not supported yet, or WIP
+> - `no` with issue link: confirmed to be unavailable due to issue
+> - `partial` with issue link: supported but not perfect due to issue
+
+<search-table />
+
+::: tip
+If an extension you need is missing, you can create a [Feature Request](https://github.com/crazywhalecc/static-php-cli/issues).
+
+Some extensions or libraries that the extension depends on will have some optional features. 
+For example, the gd library optionally supports libwebp, freetype, etc. 
+If you only use `bin/spc build gd --build-cli` they will not be included (static-php-cli defaults to the minimum dependency principle).
+
+For more information about optional libraries, see [Extensions, Library Dependency Map](./deps-map). 
+For optional libraries, you can also select an extension from the [Command Generator](./cli-generator) and then select optional libraries.
+:::

docs/en/guide/index.md

@@ -0,0 +1,50 @@
+# Guide
+
+Static php cli is a tool used to build statically compiled PHP binaries, 
+currently supporting Linux and macOS systems.
+
+In the guide section, you will learn how to use static php cli to build standalone PHP programs.
+
+- [Build (local)](./manual-build)
+- [Build (GitHub Actions)](./action-build)
+- [Supported Extensions](./extensions)
+
+## Compilation Environment
+
+The following is the architecture support situation, where :gear: represents support for GitHub Action build, 
+:computer: represents support for local manual build, and empty represents temporarily not supported.
+
+|         | x86_64            | aarch64           |
+|---------|-------------------|-------------------|
+| macOS   | :gear: :computer: | :gear: :computer: |
+| Linux   | :gear: :computer: | :gear: :computer: |
+| Windows | :gear: :computer: |                   |
+| FreeBSD | :computer:        | :computer:        |
+
+Current supported PHP versions for compilation:
+
+> :warning: Partial support, there may be issues with new beta versions and old versions.
+>
+> :heavy_check_mark: Supported
+>
+> :x: Not supported
+
+| PHP Version | Status             | Comment                                                                                                                 |
+|-------------|--------------------|-------------------------------------------------------------------------------------------------------------------------|
+| 7.2         | :x:                |                                                                                                                         |
+| 7.3         | :x:                | phpmicro and many extensions do not support 7.3, 7.4 versions                                                           |
+| 7.4         | :x:                | phpmicro and many extensions do not support 7.3, 7.4 versions                                                           |
+| 8.0         | :warning:          | PHP official has stopped maintaining 8.0, we no longer handle 8.0 related backport support                              |
+| 8.1         | :warning:          | PHP official only provides security updates for 8.1, we no longer handle 8.1 related backport support after 8.5 release |
+| 8.2         | :heavy_check_mark: |                                                                                                                         |
+| 8.3         | :heavy_check_mark: |                                                                                                                         |
+| 8.4         | :heavy_check_mark: |                                                                                                                         |
+| 8.5 (beta)  | :warning:          | PHP 8.5 is currently in beta stage                                                                                      |
+
+> This table shows the support status of static-php-cli for building corresponding versions, not the PHP official support status for that version.
+
+## PHP Support Versions
+
+Currently, static-php-cli supports PHP versions 8.2 ~ 8.5, and theoretically supports PHP 8.1 and earlier versions, just select the earlier version when downloading.
+However, due to some extensions and special components that have stopped supporting earlier versions of PHP, static-php-cli will not explicitly support earlier versions.
+We recommend that you compile the latest PHP version possible for a better experience.

docs/en/guide/manual-build.md

@@ -0,0 +1,705 @@
+---
+outline: 'deep'
+---
+
+# Build (Linux, macOS, FreeBSD)
+
+This section covers the build process for Linux, macOS, and FreeBSD. If you want to build on Windows, 
+also need to read [Build on Windows](./build-on-windows).
+
+### Build locally (using SPC binary) (recommended)
+
+This project provides a binary file of static-php-cli.
+You can directly download the binary file of the corresponding platform and then use it to build static PHP.
+Currently, the platforms supported by `spc` binary are Linux and macOS.
+
+Here's how to download from self-hosted server:
+
+```bash
+# Download from self-hosted nightly builds (sync with main branch)
+# For Linux x86_64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+# For Linux aarch64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
+# macOS x86_64 (Intel)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
+# macOS aarch64 (Apple)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
+# Windows (x86_64, win10 build 17063 or later)
+curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
+
+# Add execute perm (Linux and macOS only)
+chmod +x ./spc
+
+# Run (Linux and macOS)
+./spc --version
+# Run (Windows powershell)
+.\spc.exe --version
+```
+
+> If you are using the packaged `spc` binary, you will need to replace the leading `bin/spc` with `./spc` in all the commands below.
+
+### Build locally (using source code)
+
+If you have problems using the spc binary, or if you need to modify the static-php-cli source code, download static-php-cli from the source code.
+
+Currently, it supports building on macOS and Linux. 
+macOS supports the latest version of the operating system and two architectures, 
+while Linux supports Debian and derivative distributions, as well as Alpine Linux.
+
+Because this project itself is developed using PHP, 
+it is also necessary to install PHP on the system during compilation. 
+This project also provides static binary PHP suitable for this project, 
+which can be selected and used according to actual situations.
+
+```bash
+# clone repo
+git clone https://github.com/crazywhalecc/static-php-cli.git --depth=1
+cd static-php-cli
+
+# You need to install the PHP environment first before running Composer and this project. The installation method can be referred to below.
+composer update
+```
+
+### Use Precompiled Static PHP Binaries
+
+If you don't want to use Docker and install PHP in the system, 
+you can directly download the php binary cli program compiled by this project itself. The usage process is as follows:
+
+Deploy the environment using the command, the command will download a static php-cli binary from [self-hosted server](https://dl.static-php.dev/static-php-cli/).
+Next, it will automatically download Composer from [getcomposer](https://getcomposer.org/download/latest-stable/composer.phar) or [Aliyun mirror](https://mirrors.aliyun.com/composer/composer.phar).
+
+::: tip
+Using precompiled static PHP binaries is currently only supported on Linux and macOS.
+The FreeBSD environment is currently not supported due to the lack of an automated build environment.
+:::
+
+```bash
+bin/setup-runtime
+
+# For users with special network environments such as mainland China, you can use mirror sites (aliyun) to speed up the download speed
+bin/setup-runtime --mirror china
+```
+
+This script will download two files in total: `bin/php` and `bin/composer`. After the download is complete, there are two ways to use it:
+
+1. Add the `bin/` directory to the PATH: `export PATH="/path/to/your/static-php-cli/bin:$PATH"`, after adding the path, 
+it is equivalent to installing PHP in the system, you can directly Use commands such as `composer`, `php -v`, or directly use `bin/spc`.
+2. Direct call, such as executing static-php-cli command: `bin/php bin/spc --help`, executing Composer: `bin/php bin/composer update`.
+
+### Use Docker
+
+If you don't want to install PHP and Composer runtime environment on your system, you can use the built-in Docker environment build script.
+
+```bash
+# To use directly, replace `bin/spc` with `bin/spc-alpine-docker` in all used commands
+bin/spc-alpine-docker
+```
+
+The first time the command is executed, `docker build` will be used to build a Docker image.
+The default built Docker image is the `x86_64` architecture, and the image name is `cwcc-spc-x86_64`.
+
+If you want to build `aarch64` static-php-cli in `x86_64` environment,
+you can use qemu to emulate the arm image to run Docker, but the speed will be very slow.
+Use command: `SPC_USE_ARCH=aarch64 bin/spc-alpine-docker`.
+
+If it prompts that sudo is required to run after running,
+execute the following command once to grant static-php-cli permission to execute sudo:
+
+```bash
+export SPC_USE_SUDO=yes
+```
+
+### Use System PHP
+
+Below are some example commands for installing PHP and Composer in the system.
+It is recommended to search for the specific installation method yourself or ask the AI search engine to obtain the answer,
+which will not be elaborated here.
+
+```bash
+# [macOS], need install Homebrew first. See https://brew.sh/
+# Remember change your composer executable path. For M1/M2 Chip mac, "/opt/homebrew/bin/", for Intel mac, "/usr/local/bin/". Or add it to your own path.
+brew install php wget
+wget https://getcomposer.org/download/latest-stable/composer.phar -O /path/to/your/bin/composer && chmod +x /path/to/your/bin/composer
+
+# [Debian], you need to make sure your php version >= 8.1 and composer >= 2.0
+sudo apt install php-cli composer php-tokenizer
+
+# [Alpine]
+apk add bash file wget xz php81 php81-common php81-pcntl php81-tokenizer php81-phar php81-posix php81-xml composer
+```
+
+::: tip
+Currently, some versions of Ubuntu install older PHP versions,
+so no installation commands are provided. If necessary, it is recommended to add software sources such as ppa first,
+and then install the latest version of PHP and tokenizer, XML, and phar extensions.
+
+Older versions of Debian may have an older (<= 7.4) version of PHP installed by default, it is recommended to upgrade Debian first.
+:::
+
+## Build with craft (recommended)
+
+Using `bin/spc craft`, you can use a configuration file and a command to automatically check the environment, download source code, build dependency libraries, build PHP and extensions, etc.
+
+You need to write a `craft.yml` file and save it in the current working directory. `craft.yml` can be generated by [command generator](./cli-generator) or written manually.
+
+For manual writing, please refer to the comments in [craft.yml configuration](../develop/craft-yml.md) to write it. 
+Let's assume that you compile an extension combination and choose PHP 8.4, outputting `cli` and `fpm`:
+
+```yaml
+# path/to/craft.yml
+php-version: 8.4
+extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
+sapi:
+  - cli
+  - fpm
+```
+
+Then use the `bin/spc craft` command to compile:
+
+```bash
+bin/spc craft --debug
+```
+
+If the build is successful, you will see the `buildroot/bin` directory in the current directory, which contains the compiled PHP binary file, or the corresponding SAPI.
+
+- cli: The build result is `buildroot/bin/php.exe` on Windows and `buildroot/bin/php` on other platforms.
+- fpm: The build result is `buildroot/bin/php-fpm`.
+- micro: The build result is `buildroot/bin/micro.sfx`. If you need to further package it with PHP code, please refer to [Packaging micro binary](./manual-build#command-micro-combine).
+- embed: See [Using embed](./manual-build#embed-usage).
+- frankenphp: The build result is `buildroot/bin/frankenphp`.
+
+If the build fails, you can use the `--debug` parameter to view detailed error information, 
+or use the `--with-clean` to clear the old compilation results and recompile.
+
+If the build still fails to use the above method, please submit an issue and attach your `craft.yml` and `./log` archive.
+
+## Step-by-step build command
+
+If you have customized requirements, or the need to download and compile PHP and dependent libraries separately, you can use the `bin/spc` command to execute step by step.
+
+### Command download - Download dependency packages
+
+Use the command `bin/spc download` to download the source code required for compilation, 
+including php-src and the source code of various dependent libraries.
+
+```bash
+# Download all dependencies, defaults to php 8.4
+bin/spc download --all
+
+# Download all dependent packages, and specify the main version of PHP to download, optional: 8.1, 8.2, 8.3, 8.4
+# Also supports specific version of php release: 8.3.10, 8.2.22, etc.
+bin/spc download --all --with-php=8.3
+
+# Show download progress bar while downloading (curl)
+bin/spc download --all --debug
+
+# Delete old download data
+bin/spc download --clean
+
+# Download specified dependencies
+bin/spc download php-src,micro,zstd,ext-zstd
+
+# Download only extensions and libraries to be compiled (use extensions, including suggested libraries)
+bin/spc download --for-extensions=openssl,swoole,zip,pcntl,zstd
+
+# Download resources, prefer to download dependencies with pre-built packages (reduce the time to compile dependencies)
+bin/spc download --for-extensions="curl,pcntl,xml,mbstring" --prefer-pre-built
+
+# Download only the extensions and dependent libraries to be compiled (use extensions, excluding suggested libraries)
+bin/spc download --for-extensions=openssl,swoole,zip,pcntl --without-suggestions
+
+# Download only libraries to be compiled (use libraries, including suggested libraries and required libraries, can use --for-extensions together)
+bin/spc download  --for-libs=liblz4,libevent --for-extensions=pcntl,rar,xml
+
+# Download only libraries to be compiled (use libraries, excluding suggested libraries)
+bin/spc download --for-libs=liblz4,libevent --without-suggestions
+
+# When downloading sources, ignore some source caches (always force download, e.g. switching PHP version)
+bin/spc download --for-extensions=curl,pcntl,xml --ignore-cache-sources=php-src --with-php=8.3.10
+
+# Set retry times (default is 0)
+bin/spc download --all --retry=2
+```
+
+If the network in your area is not good, or the speed of downloading the dependency package is too slow, 
+you can download `download.zip` which is packaged regularly every week from GitHub Action, 
+and use the command to directly use the zip archive as a dependency.
+
+Dependent packages can be downloaded locally from [Action](https://github.com/static-php/static-php-cli-hosted/actions/workflows/download-cache.yml).
+Enter Action and select the latest Workflow that has been successfully run, and download `download-files-x.y`.
+
+```bash
+bin/spc download --from-zip=/path/to/your/download.zip
+```
+
+If a source cannot be downloaded all the time, or you need to download some specific version of the package, 
+such as downloading the beta version of PHP, the old version of the library, etc., 
+you can use the parameter `-U` or `--custom-url` to rewrite the download link,
+Make the downloader force the link you specify to download packages from this source. 
+The method of use is `{source-name}:{url}`, which can rewrite the download URLs of multiple libraries at the same time.
+Also, it is available when downloading with the `--for-extensions` option.
+
+
+```bash
+# Specifying to download a alpha version of PHP 8.5
+bin/spc download --all -U "php-src:https://downloads.php.net/~edorian/php-8.5.0alpha2.tar.xz"
+
+# Specifying to download an older version of the curl library
+bin/spc download --all -U "curl:https://curl.se/download/curl-7.88.1.tar.gz"
+```
+
+If the source you download is not a link, but a git repository, you can use `-G` or `--custom-git` to rewrite the download link,
+so that the downloader can force the use of the specified git repository to download packages from this source.
+The usage method is `{source-name}:{branch}:{url}`, which can rewrite the download link of multiple libraries at the same time. 
+It is also available when downloading with the `--for-extensions` option.
+
+```bash
+# Specifying to download the source code of the PHP extension from the specified branch of the git repository
+bin/spc download --for-extensions=redis -G "php-src:master:https://github.com/php/php-src.git"
+
+# Download the latest code from the master branch of the swoole-src repository instead of PECL release version
+bin/spc download --for-extensions=swoole -G "swoole:master:https://github.com/swoole/swoole-src.git"
+```
+
+### Command - doctor
+
+If you can run `bin/spc` normally but cannot compile static PHP or dependent libraries normally, 
+you can run `bin/spc doctor` first to check whether the system itself lacks dependencies.
+
+```bash
+# Quick check
+bin/spc doctor
+
+# Quickly check and fix when it can be automatically repaired (use package management to install dependent packages, only support the above-mentioned operating systems and distributions)
+bin/spc doctor --auto-fix
+```
+
+### Command - build
+
+Use the build command to start building the static php binary. 
+Before executing the `bin/spc build` command, be sure to use the `download` command to download sources. 
+It is recommended to use `doctor` to check the environment.
+
+#### Basic build
+
+You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add, 
+and then use the command `bin/spc build` to compile. 
+You need to specify a compilation target, choose from the following parameters:
+
+- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
+- `--build-fpm`: Build a fpm sapi (php-fpm, used in conjunction with other traditional fpm architecture software such as nginx)
+- `--build-cgi`: Build a cgi sapi (cgi, rarely used)
+- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
+- `--build-embed`: Build an embed sapi (used to embed into other C language programs)
+- `--build-frankenphp`: Build a [FrankenPHP](https://github.com/php/frankenphp) executable
+- `--build-all`: build all above sapi
+
+```bash
+# Compile PHP with bcmath,curl,openssl,ftp,posix,pcntl extensions, the compilation target is cli
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+
+# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro
+bin/spc build phar,curl,posix,pcntl,tokenizer --build-micro
+```
+
+::: tip
+If you need to repeatedly build and debug, you can delete the `buildroot/` and `source/` directories so that you can re-extract and build all you need from the downloaded source code package:
+
+```shell
+# remove
+rm -rf buildroot source
+# build again
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+```
+:::
+
+::: tip
+If you want to build multiple versions of PHP and don't want to build other dependent libraries repeatedly each time, 
+you can use `switch-php-version` to quickly switch to another version and compile after compiling one version:
+
+```shell
+# switch to 8.4
+bin/spc switch-php-version 8.4
+# build
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+# switch to 8.1
+bin/spc switch-php-version 8.1
+# build
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+```
+:::
+
+#### Build Options
+
+During the compilation process, in some special cases, 
+the compiler and the content of the compilation directory need to be intervened. 
+You can try to use the following commands:
+
+- `--cc=XXX`: Specifies the execution command of the C language compiler (Linux default `musl-gcc` or `gcc`, macOS default `clang`)
+- `--cxx=XXX`: Specifies the execution command of the C++ language compiler (Linux defaults to `g++`, macOS defaults to `clang++`)
+- `--with-clean`: clean up old make files before compiling PHP
+- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
+- `--no-strip`: Do not run `strip` after compiling the PHP library to trim the binary file to reduce its size
+- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extended optional functions (such as libavif of the gd library, etc.)
+- `--with-config-file-path=XXX`: Set the path in which to look for `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
+- `--with-config-file-scan-dir=XXX`: Set the directory to scan for `.ini` files after reading `php.ini` (Check [here](../faq/index.html#what-is-the-path-of-php-ini) for default paths)
+- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
+- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
+- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
+- `-P xxx.php`: Inject external scripts during static-php-cli compilation (see **Inject external scripts** below for details)
+- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
+- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
+- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
+- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
+- `--build-shared=XXX,YYY`: compile the specified extension into a shared library (the default is to compile into a static library)
+
+For hardcoding INI options, it works for cli, micro, embed sapi. Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
+
+```bash
+bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
+```
+
+## Debug
+
+If you encounter problems during the compilation process, or want to view each executing shell command,
+you can use `--debug` to enable debug mode and view all terminal logs:
+
+```bash
+bin/spc build mysqlnd,pdo_mysql --build-all --debug
+```
+
+## Command - micro:combine
+
+Use the `micro:combine` command to build the compiled `micro.sfx` and your code (`.php` or `.phar` file) into an executable binary.
+You can also use this command to directly build a micro binary injected with ini configuration.
+
+::: tip
+Injecting ini configuration refers to adding a special structure after micro.sfx to save ini configuration items before combining micro.sfx with PHP source code.
+
+micro.sfx can identify the INI file header through a special byte, and the micro can be started with INI through the INI file header.
+
+The original wiki of this feature is in [phpmicro - Wiki](https://github.com/easysoft/phpmicro/wiki/INI-settings), and this feature may change in the future.
+:::
+
+The following is the general usage, directly packaging the php source code into a file:
+
+```bash
+# Before doing the packaging process, you should use `build --build-micro` to compile micro.sfx
+echo "<?php echo 'hello';" > a.php
+bin/spc micro:combine a.php
+
+# Just use it
+./my-app
+```
+
+You can use the following options to specify the file name to be output, and you can also specify micro.sfx in other paths for packaging.
+
+```bash
+# specify the output filename
+bin/spc micro:combine a.php --output=custom-bin
+# Use absolute path
+bin/spc micro:combine a.php -O /tmp/my-custom-app
+
+# Specify micro.sfx in other locations for packaging
+bin/spc micro:combine a.app --with-micro=/path/to/your/micro.sfx
+```
+
+If you want to inject ini configuration items, you can use the following parameters to add ini to the executable file from a file or command line option.
+
+```bash
+# Specified using command-line options (-I is shorthand for --with-ini-set)
+bin/spc micro:combine a.php -I "a=b" -I "foo=bar"
+
+# Use ini file specification (-N is shorthand for --with-ini-file)
+bin/spc micro:combine a.php -N /path/to/your/custom.ini
+```
+
+::: warning
+Note, please do not directly use the PHP source code or the `php.ini` file in the system-installed PHP, 
+it is best to manually write an ini configuration file that you need, for example:
+
+```ini
+; custom.ini
+curl.cainfo=/path/to/your/cafile.pem
+memory_limit=1G
+```
+
+The ini injection of this command is achieved by appending a special structure after micro.sfx, 
+which is different from the function of inserting hard-coded INI during compilation.
+:::
+
+If you want to package phar, just replace `a.php` with the packaged phar file. 
+But please note that micro.sfx under phar needs extra attention to the path problem, see [Developing - Phar directory issue](../develop/structure#phar-application-directory-issue).
+
+## Command - extract
+
+Use the command `bin/spc extract` to unpack and copy the source code required for compilation, 
+including php-src and the source code of various dependent libraries (you need to specify the name of the library to be unpacked).
+
+For example, after we have downloaded sources, we want to distribute and execute the build process, 
+manually unpack and copy the package to a specified location, and we can use commands.
+
+```bash
+# Unzip the downloaded compressed package of php-src and libxml2, and store the decompressed source code in the source directory
+bin/spc extract php-src,libxml2
+```
+
+## Command - dump-extensions
+
+Use the command `bin/spc dump-extensions` to export required extensions of the current project.
+
+```bash
+# Print the extension list of the project, pass in the root directory of the project containing composer.json
+bin/spc dump-extensions /path/to/your/project/
+
+# Print the extension list of the project, excluding development dependencies
+bin/spc dump-extensions /path-to/tour/project/ --no-dev
+
+# Output in the extension list format acceptable to the spc command (comma separated)
+bin/spc dump-extensions /path-to/tour/project/ --format=text
+
+# Output as a JSON list
+bin/spc dump-extensions /path-to/tour/project/ --format=json
+
+# When the project does not have any extensions, output the specified extension combination instead of returning failure
+bin/spc dump-extensions /path-to/your/project/ --no-ext-output=mbstring,posix,pcntl,phar
+
+# Do not exclude extensions not supported by spc when outputting
+bin/spc dump-extensions /path/to/your/project/ --no-spc-filter
+```
+It should be noted that the project directory must contain the `vendor/installed.json` and `composer.lock` files, otherwise they cannot be found normally.
+
+## Dev Command - dev
+
+Debug commands refer to a collection of commands that can assist in outputting some information 
+when you use static-php-cli to build PHP or modify and enhance the static-php-cli project itself.
+
+- `dev:extensions`: output all currently supported extension names, or output the specified extension information
+- `dev:php-version`: output the currently compiled PHP version (by reading `php_version.h`)
+- `dev:sort-config`: Sort the list of configuration files in the `config/` directory in alphabetical order
+- `dev:lib-ver <lib-name>`: Read the version from the source code of the dependency library (only available for specific dependency libraries)
+- `dev:ext-ver <ext-name>`: Read the corresponding version from the source code of the extension (only available for specific extensions)
+- `dev:pack-lib <lib-name>`: Package the specified library into a tar.gz file (maintainer only)
+- `dev:gen-ext-docs`: Generate extension documentation (maintainer only)
+
+```bash
+# output all extensions information
+bin/spc dev:extensions
+
+# Output the meta information of the specified extension
+bin/spc dev:extensions mongodb,curl,openssl
+
+# Output the specified columns
+# Available column name: lib-depends, lib-suggests, ext-depends, ext-suggests, unix-only, type
+bin/spc dev:extensions --columns=lib-depends,type,ext-depends
+
+# Output the currently compiled PHP version
+# You need to decompress the downloaded PHP source code to the source directory first
+# You can use `bin/spc extract php-src` to decompress the source code separately
+bin/spc dev:php-version
+
+# Sort the configuration files in the config/ directory in alphabetical order (e.g. ext.json)
+bin/spc dev:sort-config ext
+```
+
+## Command - install-pkg
+
+Use the command `bin/spc install-pkg` to download some precompiled or closed source tools and install them into the `pkgroot` directory.
+
+When `bin/spc doctor` automatically repairs the Windows environment, tools such as nasm and perl will be downloaded, and the installation process of `install-pkg` will also be used.
+
+Here is an example of installing the tool:
+
+- Download and install UPX (Linux and Windows only): `bin/spc install-pkg upx`
+- Download and install nasm (Windows only): `bin/spc install-pkg nasm`
+- Download and install go-xcaddy: `bin/spc install-pkg go-xcaddy`
+
+## Command - del-download
+
+In some cases, you need to delete single or multiple specified download source files and re-download them, such as switching PHP versions. 
+The `bin/spc del-download` command is provided after the `2.1.0-beta.4` version. Specified source files can be deleted.
+
+Deletes downloaded source files containing precompiled packages and source code named as keys in `source.json` or `pkg.json`. Here are some examples:
+
+- Delete the old PHP source code and switch to download the 8.3 version: `bin/spc del-download php-src && bin/spc download php-src --with-php=8.3`
+- Delete the download file of redis extension: `bin/spc del-download redis`
+- Delete the downloaded musl-toolchain x86_64: `bin/spc del-download musl-toolchain-x86_64-linux`
+
+## Inject External Script
+
+Injecting external scripts refers to inserting one or more scripts during the static-php-cli compilation process
+to more flexibly support parameter modifications and source code patches in different environments.
+
+Under normal circumstances, this function mainly solves the problem that the patch cannot be modified
+by modifying the static-php-cli code when compiling with `spc` binary.
+
+There is another situation: your project directly depends on the `crazywhalecc/static-php-cli` repository and is synchronized with main branch, 
+but some proprietary modifications are required, and these feature are not suitable for merging into the main branch.
+
+In view of the above situation, in the official version 2.0.0, static-php-cli has added multiple event trigger points. 
+You can write an external `xx.php` script and pass it in through the command line parameter `-P` and execute.
+
+When writing to inject external scripts, the methods you will use are `builder()` and `patch_point()`. 
+Among them, `patch_point()` obtains the name of the current event, and `builder()` obtains the BuilderBase object.
+
+Because the incoming patch point does not distinguish between events, 
+you must write the code you want to execute in `if(patch_point() === 'your_event_name')`, 
+otherwise it will be executed repeatedly in other events.
+
+The following are the supported `patch_point` event names and corresponding locations:
+
+| Event name                      | Event description                                                                                  |
+|---------------------------------|----------------------------------------------------------------------------------------------------|
+| before-libs-extract             | Triggered before the dependent libraries extracted                                                 |
+| after-libs-extract              | Triggered after the compiled dependent libraries extracted                                         |
+| before-php-extract              | Triggered before PHP source code extracted                                                         |
+| after-php-extract               | Triggered after PHP source code extracted                                                          |
+| before-micro-extract            | Triggered before phpmicro extract                                                                  |
+| after-micro-extract             | Triggered after phpmicro extracted                                                                 |
+| before-exts-extract             | Triggered before the extension (to be compiled) extracted to the PHP source directory              |
+| after-exts-extract              | Triggered after the extension extracted to the PHP source directory                                |
+| before-library[*name*]-build    | Triggered before the library named `name` is compiled (such as `before-library[postgresql]-build`) |
+| after-library[*name*]-build     | Triggered after the library named `name` is compiled                                               |
+| after-shared-ext[*name*]-build  | Triggered after the shared extension named `name` is compiled                                      |
+| before-shared-ext[*name*]-build | Triggered before the shared extension named `name` is compiled                                     |
+| before-php-buildconf            | Triggered before compiling PHP command `./buildconf`                                               |
+| before-php-configure            | Triggered before compiling PHP command `./configure`                                               |
+| before-php-make                 | Triggered before compiling PHP command `make`                                                      |
+| before-sanity-check             | Triggered after compiling PHP but before running extended checks                                   |
+
+The following is a simple example of temporarily modifying the PHP source code. 
+Enable the CLI function to search for the `php.ini` configuration in the current working directory:
+
+```php
+// a.php
+<?php
+// patch it before `./buildconf` executed
+if (patch_point() === 'before-php-buildconf') {
+    \SPC\store\FileSystem::replaceFileStr(
+        SOURCE_PATH . '/php-src/sapi/cli/php_cli.c',
+        'sapi_module->php_ini_ignore_cwd = 1;',
+        'sapi_module->php_ini_ignore_cwd = 0;'
+    );
+}
+```
+
+```bash
+bin/spc build mbstring --build-cli -P a.php
+# Write in ./
+echo 'memory_limit=8G' > ./php.ini
+```
+
+```
+$ buildroot/bin/php -i | grep Loaded
+Loaded Configuration File => /Users/jerry/project/git-project/static-php-cli/php.ini
+
+$ buildroot/bin/php -i | grep memory
+memory_limit => 8G => 8G
+```
+
+For the objects, methods and interfaces supported by static-php-cli, you can read the source code. Most methods and objects have corresponding comments.
+
+Commonly used objects and functions using the `-P` function are:
+
+- `SPC\store\FileSystem`: file management class
+    - `::replaceFileStr(string $filename, string $search, $replace)`: Replace file string content
+    - `::replaceFileStr(string $filename, string $pattern, $replace)`: Regularly replace file content
+    - `::replaceFileUser(string $filename, $callback)`: User-defined function replaces file content
+    - `::copyDir(string $from, string $to)`: Recursively copy a directory to another location
+    - `::convertPath(string $path)`: Convert the path delimiter to the current system delimiter
+    - `::scanDirFiles(string $dir, bool $recursive = true, bool|string $relative = false, bool $include_dir = false)`: Traverse directory files
+- `SPC\builder\BuilderBase`: Build object
+    - `->getPatchPoint()`: Get the current injection point name
+    - `->getOption(string $key, $default = null)`: Get command line and compile-time options
+    - `->getPHPVersionID()`: Get the currently compiled PHP version ID
+    - `->getPHPVersion()`: Get the currently compiled PHP version number
+    - `->setOption(string $key, $value)`: Set options
+    - `->setOptionIfNotExists(string $key, $value)`: Set option if option does not exist
+
+::: tip
+static-php-cli has many open methods, which cannot be listed in the docs, 
+but as long as it is a `public function` and is not marked as `@internal`, it theoretically can be called.
+:::
+
+## Multiple builds
+
+If you need to build multiple times locally, the following method can save you time downloading resources and compiling.
+
+- If you only switch the PHP version without changing the dependent libraries, you can use `bin/spc switch-php-version` to quickly switch the PHP version, and then re-run the same `build` command.
+- If you want to rebuild once, but do not re-download the source code, you can first `rm -rf buildroot source` to delete the compilation directory and source code directory, and then rebuild.
+- If you want to update a version of a dependency, you can use `bin/spc del-download <source-name>` to delete the specified source code, and then use `download <source-name>` to download it again.
+- If you want to update all dependent versions, you can use `bin/spc download --clean` to delete all downloaded sources, and then download them again.
+
+## embed usage
+
+If you want to embed static-php into other C language programs, you can use `--build-embed` to build an embed version of PHP.
+
+```bash
+bin/spc build {your extensions} --build-embed --debug
+```
+
+Under normal circumstances, PHP embed will generate `php-config` after compilation. 
+For static-php, we provide `spc-config` to obtain the parameters during compilation.
+In addition, when using embed SAPI (libphp.a), you need to use the same compiler as libphp, otherwise there will be a link error.
+
+Here is the basic usage of spc-config:
+
+```bash
+# output all flags and options
+bin/spc spc-config curl,zlib,phar,openssl
+
+# output libs
+bin/spc spc-config curl,zlib,phar,openssl --libs
+
+# output includes
+bin/spc spc-config curl,zlib,phar,openssl --includes
+```
+
+By default, static-php uses the following compilers on different systems:
+
+- macOS: `clang`
+- Linux (Alpine Linux): `gcc`
+- Linux (glibc based distros, x86_64): `/usr/local/musl/bin/x86_64-linux-musl-gcc`
+- Linux (glibc based distros, aarch64): `/usr/local/musl/bin/aarch64-linux-musl-gcc`
+- FreeBSD: `clang`
+
+Here is an example of using embed SAPI:
+
+```c
+// embed.c
+#include <sapi/embed/php_embed.h>
+
+int main(int argc,char **argv){
+
+    PHP_EMBED_START_BLOCK(argc,argv)
+
+    zend_file_handle file_handle;
+
+    zend_stream_init_filename(&file_handle,"embed.php");
+
+    if(php_execute_script(&file_handle) == FAILURE){
+        php_printf("Failed to execute PHP script.\n");
+    }
+
+    PHP_EMBED_END_BLOCK()
+    return 0;
+}
+```
+
+
+```php
+<?php 
+// embed.php
+echo "Hello world!\n";
+```
+
+```bash
+# compile in debian/ubuntu x86_64
+/usr/local/musl/bin/x86_64-linux-musl-gcc embed.c $(bin/spc spc-config bcmath,zlib) -static -o embed
+# compile in macOS/FreeBSD
+clang embed.c $(bin/spc spc-config bcmath,zlib) -o embed
+
+./embed
+# out: Hello world!
+```

docs/en/guide/troubleshooting.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+Various failures may be encountered in the process of using static-php-cli, 
+here will describe how to check the errors by yourself and report Issue.
+
+## Download Failure
+
+Problems with downloading resources are one of the most common problems with spc. 
+The main reason is that the addresses used for SPC download resources are generally the official website of the corresponding project or GitHub, etc.,
+and these websites may occasionally go down and block IP addresses.
+After encountering a download failure, 
+you can try to call the download command multiple times. 
+
+When downloading extensions, you may eventually see errors like `curl: (56) The requested URL returned error: 403` which are often caused by github rate limiting.
+You can verify this by adding `--debug` to the command and will see something like `[DEBU] Running command (no output) : curl -sfSL   "https://api.github.com/repos/openssl/openssl/releases"`.
+
+To fix this, [create](https://github.com/settings/tokens) a personal access token on GitHub and set it as an environment variable `GITHUB_TOKEN=<XXX>`.
+
+If you confirm that the address is indeed inaccessible, 
+you can submit an Issue or PR to update the url or download type.
+
+## Doctor Can't Fix Something
+
+In most cases, the doctor module can automatically repair and install missing system environments, 
+but there are also special circumstances where the automatic repair function cannot be used normally.
+
+Due to system limitations (for example, software such as Visual Studio cannot be automatically installed under Windows),
+the automatic repair function cannot be used for some projects.
+When encountering a function that cannot be automatically repaired, 
+if you encounter the words `Some check items can not be fixed`,
+it means that it cannot be automatically repaired.
+Please submit an issue according to the method displayed on the terminal or repair the environment yourself.
+
+## Compile Error
+
+When you encounter a compilation error, if the `--debug` log is not enabled, please enable the debug log first,
+and then determine the command that reported the error.
+The error terminal output is very important for fixing compilation errors.
+When submitting an issue, please upload the last error fragment of the terminal log (or the entire terminal log output),
+and include the `spc` command and parameters used.
+
+If you are rebuilding, please refer to the [Local Build - Multiple Builds](./manual-build#multiple-builds) section.

docs/en/index.md

@@ -0,0 +1,142 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Static PHP"
+  tagline: "Build standalone PHP binary on Linux, macOS, FreeBSD, Windows, with PHP project together, with popular extensions included."
+  image:
+    src: /images/static-php_nobg.png
+    alt: Static PHP CLI Logo
+  actions:
+    - theme: brand
+      text: Get Started
+      link: ./guide/
+
+features:
+  - title: Static CLI Binary
+    details: You can easily compile a standalone php binary for general use. Including CLI, FPM sapi.
+  - title: Micro Self-Extracted Executable
+    details: You can compile a self-extracted executable and build with your php source code.
+  - title: Dependency Management
+    details: static-php-cli comes with dependency management and supports installation of different types of PHP extensions.
+---
+
+<script setup>
+import {VPSponsors} from "vitepress/theme";
+import Contributors from '../.vitepress/components/Contributors.vue';
+
+const sponsors = [
+  { name: 'Beyond Code', img: '/images/beyondcode-seeklogo.png', url: 'https://beyondco.de/' },
+  { name: 'NativePHP', img: '/images/nativephp-logo.svg', url: 'https://nativephp.com/' },
+];
+</script>
+
+<div class="sponsors-section">
+  <div class="sponsors-header">
+    <h2>Special Sponsors</h2>
+    <p class="sponsors-description">
+      Thank you to our amazing sponsors for supporting this project!
+    </p>
+  </div>
+  <VPSponsors :data="sponsors"/>
+</div>
+
+<style scoped>
+.sponsors-section {
+  margin: 48px auto;
+  padding: 32px 24px;
+  max-width: 1152px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-bg) 100%);
+  border-radius: 16px;
+  border: 1px solid var(--vp-c-divider);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+  transition: all 0.3s ease;
+}
+
+.sponsors-section:hover {
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+  transform: translateY(-2px);
+}
+
+.sponsors-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.sponsors-header h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin: 0 0 8px 0;
+  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.sponsors-description {
+  font-size: 0.95rem;
+  color: var(--vp-c-text-2);
+  margin: 0;
+  line-height: 1.5;
+}
+
+@media (max-width: 768px) {
+  .sponsors-section {
+    margin: 32px 16px;
+    padding: 24px 16px;
+  }
+  
+  .sponsors-header h2 {
+    font-size: 1.25rem;
+  }
+  
+  .sponsors-description {
+    font-size: 0.9rem;
+  }
+}
+
+/* Hero logo styling */
+:deep(.VPImage.image-src) {
+  border-radius: 20px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-default-soft) 100%);
+  padding: 40px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+  transition: all 0.3s ease;
+}
+
+:deep(.VPImage.image-src:hover) {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15);
+}
+
+/* Dark mode adjustments for logo */
+.dark :deep(.VPImage.image-src) {
+  background: linear-gradient(135deg, rgba(255, 255, 255, 0.05) 0%, rgba(255, 255, 255, 0.02) 100%);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
+  opacity: 0.9;
+}
+
+.dark :deep(.VPImage.image-src:hover) {
+  opacity: 1;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.7);
+}
+
+/* Additional styling for the logo image itself */
+:deep(.VPImage.image-src img) {
+  max-height: 280px;
+  width: auto;
+}
+
+@media (max-width: 768px) {
+  :deep(.VPImage.image-src) {
+    padding: 24px;
+  }
+  
+  :deep(.VPImage.image-src img) {
+    max-height: 200px;
+  }
+}
+</style>
+
+<Contributors />

docs/extensions.md

@@ -0,0 +1 @@
+> This file is dynamically generated by `bin/spc dev:gen-ext-docs` command.

docs/index.md

@@ -0,0 +1,147 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Static PHP"
+  tagline: "Build standalone PHP binary on Linux, macOS, FreeBSD, Windows, with PHP project together, with popular extensions included."
+  image:
+    src: /images/static-php_nobg.png
+    alt: Static PHP CLI Logo
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /en/guide/
+    - theme: alt
+      text: 中文文档
+      link: /zh/
+
+features:
+  - title: Static CLI Binary
+    details: You can easily compile a standalone php binary for general use. Including CLI, FPM sapi.
+  - title: Micro Self-Extracted Executable
+    details: You can compile a self-extracted executable and build with your php source code.
+  - title: Dependency Management
+    details: static-php-cli comes with dependency management and supports installation of different types of PHP extensions.
+---
+
+<script setup>
+import {VPSponsors} from "vitepress/theme";
+import Contributors from './.vitepress/components/Contributors.vue';
+
+const sponsors = [
+  { name: 'Beyond Code', img: '/images/beyondcode-seeklogo.png', url: 'https://beyondco.de/' },
+  { name: 'NativePHP', img: '/images/nativephp-logo.svg', url: 'https://nativephp.com/' },
+];
+</script>
+
+<div class="sponsors-section">
+  <div class="sponsors-header">
+    <h2>Special Sponsors</h2>
+    <p class="sponsors-description">
+      Thank you to our amazing sponsors for supporting this project!
+    </p>
+  </div>
+  <VPSponsors :data="sponsors"/>
+</div>
+
+<style scoped>
+.sponsors-section {
+  margin: 48px auto;
+  padding: 32px 24px;
+  max-width: 1152px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-bg) 100%);
+  border-radius: 16px;
+  border: 1px solid var(--vp-c-divider);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+  transition: all 0.3s ease;
+}
+
+.sponsors-section:hover {
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+  transform: translateY(-2px);
+}
+
+.sponsors-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.sponsors-header h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin: 0 0 8px 0;
+  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.sponsors-description {
+  font-size: 0.95rem;
+  color: var(--vp-c-text-2);
+  margin: 0;
+  line-height: 1.5;
+}
+
+@media (max-width: 768px) {
+  .sponsors-section {
+    margin: 32px 16px;
+    padding: 24px 16px;
+  }
+  
+  .sponsors-header h2 {
+    font-size: 1.25rem;
+  }
+  
+  .sponsors-description {
+    font-size: 0.9rem;
+  }
+}
+
+/* Hero logo styling */
+:deep(.VPImage.image-src) {
+  border-radius: 20px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-default-soft) 100%);
+  padding: 40px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+  transition: all 0.3s ease;
+}
+
+:deep(.VPImage.image-src:hover) {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15);
+}
+
+/* Dark mode adjustments for logo */
+.dark :deep(.VPImage.image-src) {
+  background: linear-gradient(135deg, rgba(255, 255, 255, 0.05) 0%, rgba(255, 255, 255, 0.02) 100%);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
+  opacity: 0.9;
+}
+
+.dark :deep(.VPImage.image-src:hover) {
+  opacity: 1;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.7);
+}
+
+/* Additional styling for the logo image itself */
+:deep(.VPImage.image-src img) {
+  max-height: 280px;
+  width: auto;
+}
+
+@media (max-width: 768px) {
+  :deep(.VPImage.image-src) {
+    padding: 24px;
+  }
+  
+  :deep(.VPImage.image-src img) {
+    max-height: 200px;
+  }
+}
+
+</style>
+
+<Contributors />
+

docs/public/CNAME

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

docs/public/images/nativephp-logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 764 100">
+    <path fill="#505b93" d="M29.5,98.4H0V1.2h29.5V98.4z"/>
+    <path fill="#00aaa6" d="M96.7,98.4H67.2V1.2h29.5V98.4z"/>
+    <path fill="#272d48" d="M96.7,98.4H29.5V1.2L96.7,98.4z"/>
+    <path fill="#272d48" d="M102.6,54.5c0-6.2,1.3-11.8,4.1-16.7c2.7-5,6.7-8.8,11.9-11.6c5.2-2.8,11.4-4.2,18.6-4.2c1.1,0,2.8,0.1,5.2,0.3 c4.9,0.4,9.1,1.3,12.5,2.8c3.4,1.5,6.4,3.4,9.1,5.9v-7.2h25.8v74.7h-25.8v-7.2c-2.5,2.6-5.6,4.6-9.4,6.1c-3.8,1.5-7.9,2.4-12.1,2.6 c-0.9,0.1-2.3,0.1-4.1,0.1c-7.2,0-13.4-1.4-18.8-4.1c-5.4-2.7-9.5-6.6-12.4-11.5c-2.9-4.9-4.3-10.5-4.3-16.6V54.5z M128.4,63.9 c0,9.2,5.9,13.8,17.7,13.8c11.8,0,17.7-4.6,17.7-13.8v-5.6c0-9.3-5.9-14-17.7-14c-11.8,0-17.7,4.7-17.7,14V63.9z M208.3,98.4V47h-12.8V23.7l12.8-0.2V1.2h25.9l0.1,22.4h18.3V47h-18.4v51.4 M287.3,98.4h-25.9V23.6h25.9V98.4z M351,98.4H325l-31-74.8H320L338,68l18-44.5h25.9L351,98.4z M454.9,87.6c-4.1,4.2-8.8,7.3-14.1,9.3c-5.3,2-11.8,2.9-19.5,2.9c-8,0-15.1-1.4-21.3-4.2 c-6.2-2.8-11.1-6.7-14.7-11.6c-3.5-5-5.3-10.6-5.3-17V54.6c0-6.5,1.7-12.2,5.2-17.1c3.4-4.9,8.2-8.7,14.2-11.3c6-2.7,12.7-4,20-4 c8,0,15,1.5,21.2,4.3c6.1,2.9,10.9,7,14.4,12.4c3.4,5.4,5.2,11.6,5.2,18.7c0,1.7-0.2,4.2-0.7,7.7l-54.2,0.1v2.1 c0,4.1,1.5,7.3,4.4,9.4c2.9,2.2,6.9,3.2,11.8,3.2c4.6,0,8.5-0.6,11.8-1.8c3.2-1.2,6.4-3.5,9.4-6.8L454.9,87.6z M434.4,51.4 c0-3.1-1.4-5.5-4.2-7.1c-2.8-1.6-6.4-2.4-10.8-2.4s-7.9,0.8-10.5,2.4c-2.6,1.6-3.8,4-3.8,7.1H434.4z M466,98.4V1.2h56c9.9,0,17.8,1.9,23.7,5.6c5.9,3.7,10,8.2,12.2,13.3c2.3,5.1,3.4,10.1,3.4,15 c0,4.8-1.2,9.7-3.5,14.7c-2.3,5-6.4,9.2-12.2,12.8c-5.8,3.6-13.7,5.4-23.7,5.4h-30.2v30.5H466z M522,44.6c9,0,13.6-3.3,13.6-9.9 c0-6.9-4.6-10.3-13.7-10.3h-30.1v20.2H522z M593,98.4h-25.8V1.2H593v38h43.9v-38h25.8v97.2h-25.8V59.9H593V98.4z M668.6,98.4V1.2h56c9.9,0,17.8,1.9,23.7,5.6c5.9,3.7,10,8.2,12.2,13.3c2.3,5.1,3.4,10.1,3.4,15 c0,4.8-1.2,9.7-3.5,14.7c-2.3,5-6.4,9.2-12.2,12.8c-5.8,3.6-13.7,5.4-23.7,5.4h-30.2v30.5H668.6z M724.6,44.6c9,0,13.6-3.3,13.6-9.9 c0-6.9-4.6-10.3-13.7-10.3h-30.1v20.2H724.6z M291.1,20.2h-33.5V0h33.5V20.2z"/>
+</svg>

docs/zh/contributing/index.md

@@ -0,0 +1,51 @@
+# 贡献指南
+
+感谢你能够看到这里，本项目非常欢迎你的贡献！
+
+## 贡献方法
+
+如果你有代码或文档要贡献，以下是你需要首先了解的内容。
+
+1. 你要贡献什么类型的代码？（新扩展、修复 Bug、安全问题、项目框架优化、文档）
+2. 如果你贡献了新文件或新片段，你的代码是否经过 `php-cs-fixer` 和 `phpstan` 的检查？
+3. 在贡献代码前是否充分阅读了 [开发指南](../develop/)？
+
+如果你能回答上述问题并对代码进行了修改，可以及时在项目 GitHub 仓库发起 Pull Request。
+代码审查完成后，可以根据建议修改代码，或直接合并到主分支。
+
+## 贡献类型
+
+本项目的主要目的是编译静态链接的 PHP 二进制文件，命令行处理功能基于 `symfony/console` 编写。
+在开发之前，如果你对它不够熟悉，请先查看 [symfony/console 文档](https://symfony.com/doc/current/components/console.html)。
+
+### 安全更新
+
+因为本项目基本上是一个本地运行的 PHP 项目，一般来说不会有远程攻击。
+但如果你发现此类问题，请**不要**在 GitHub 仓库提交 PR 或 Issue，
+你需要通过 [邮件](mailto:admin@zhamao.me) 联系项目维护者（crazywhalecc）。
+
+### 修复 Bug
+
+修复 Bug 一般不涉及项目结构和框架的修改，所以如果你能定位到错误代码并直接修复它，请直接提交 PR。
+
+### 新扩展
+
+对于添加新扩展，你需要了解项目的一些基本结构以及如何根据现有逻辑添加新扩展。
+这将在本页的下一节中详细介绍。
+总的来说，你需要：
+
+1. 评估扩展是否可以内联编译到 PHP 中。
+2. 评估扩展的依赖库（如果有）是否可以静态编译。
+3. 编写不同平台的库编译命令。
+4. 验证扩展及其依赖项与现有扩展和依赖项兼容。
+5. 验证扩展在 `cli`、`micro`、`fpm`、`embed` SAPIs 中正常工作。
+6. 编写文档并添加你的扩展。
+
+### 项目框架优化
+
+如果你已经熟悉 `symfony/console` 的工作原理，并同时要对项目的框架进行一些修改或优化，请先了解以下事情：
+
+1. 添加扩展不属于项目框架优化，但如果你在添加新扩展时发现必须优化框架，则需要先修改框架本身，然后再添加扩展。
+2. 对于一些大规模逻辑修改（例如涉及 LibraryBase、Extension 对象等的修改），建议先提交 Issue 或 Draft PR 进行讨论。
+3. 在项目早期，它是一个纯私有开发项目，代码中有一些中文注释。项目国际化后，你可以提交 PR 将这些注释翻译为英语。
+4. 请不要在代码中提交更多无用的代码片段，例如大量未使用的变量、方法、类以及多次重写的代码。

docs/zh/develop/craft-yml.md

@@ -0,0 +1,7 @@
+---
+aside: false
+---
+
+# craft.yml 配置
+
+<!--@include: ../../deps-craft-yml.md-->

docs/zh/develop/doctor-module.md

@@ -0,0 +1,60 @@
+# Doctor 模块
+
+Doctor 模块是一个较为独立的用于检查系统环境的模块，可使用命令 `bin/spc doctor` 进入，入口的命令类在 `DoctorCommand.php` 中。
+
+Doctor 模块是一个检查单，里面有一系列的检查项目和自动修复项目。这些项目都存放在 `src/SPC/doctor/item/` 目录中，
+并且使用了两种 Attribute 用作检查项标记和自动修复项目标记：`#[AsCheckItem]` 和 `#[AsFixItem]`。
+
+以现有的检查项 `if necessary tools are installed`，它是用于检查编译必需的包是否安装在 macOS 系统内，下面是它的源码：
+
+```php
+use SPC\doctor\AsCheckItem;
+use SPC\doctor\AsFixItem;
+use SPC\doctor\CheckResult;
+
+#[AsCheckItem('if necessary tools are installed', limit_os: 'Darwin', level: 997)]
+public function checkCliTools(): ?CheckResult
+{
+    $missing = [];
+    foreach (self::REQUIRED_COMMANDS as $cmd) {
+        if ($this->findCommand($cmd) === null) {
+            $missing[] = $cmd;
+        }
+    }
+    if (!empty($missing)) {
+        return CheckResult::fail('missing system commands: ' . implode(', ', $missing), 'build-tools', [$missing]);
+    }
+    return CheckResult::ok();
+}
+```
+
+属性的第一个参数就是检查项目的名称，后面的 `limit_os` 参数是限制了该检查项仅在指定的系统下触发，`level` 是执行该检查项的优先级，数字越大，优先级越高。
+
+里面用到的 `$this->findCommand()` 方法为 `SPC\builder\traits\UnixSystemUtilTrait` 的方法，用途是查找系统命令所在位置，找不到时返回 NULL。
+
+每个检查项的方法都应该返回一个 `SPC\doctor\CheckResult`：
+
+- 在返回 `CheckResult::fail()` 时，第一个参数用于输出终端的错误提示，第二个参数是在这个检查项可自动修复时的修复项目名称。
+- 在返回 `CheckResult::ok()` 时，表明检查通过。你也可以传递一个参数，用于返回检查结果，例如：`CheckResult::ok('OS supported')`。
+- 在返回 `CheckResult::fail()` 时，如果包含了第三个参数，第三个参数的数组将被当作 `AsFixItem` 的参数。
+
+下面是这个检查项对应的自动修复项的方法：
+
+```php
+#[AsFixItem('build-tools')]
+public function fixBuildTools(array $missing): bool
+{
+    foreach ($missing as $cmd) {
+        try {
+            shell(true)->exec('brew install ' . escapeshellarg($cmd));
+        } catch (RuntimeException) {
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+`#[AsFixItem()]` 属性传入的参数即修复项的名称，该方法必须返回 True 或 False。当返回 False 时，表明自动修复失败，需要手动处理。
+
+此处的代码中 `shell()->exec()` 是项目的执行命令的方法，用于替代 `exec()`、`system()`，同时提供了 debug、获取执行状态、进入目录等特性。

docs/zh/develop/index.md

@@ -0,0 +1,27 @@
+# 开发简介
+
+开发本项目需要安装部署 PHP 环境，以及一些 PHP 项目常用的扩展和 Composer。
+
+项目的开发环境和运行环境几乎完全一致。你可以参照 **手动构建** 部分安装系统 PHP 或使用本项目预构建的静态 PHP 作为环境。这里不再赘述。
+
+抛开用途，本项目本身其实就是一个 `php-cli` 程序，你可以将它当作一个正常的 PHP 项目进行编辑和开发，同时你需要了解不同系统的 Shell 命令行。
+
+本项目目前的目的就是为了编译静态编译的独立 PHP，但主体部分也包含编译很多依赖库的静态版本，所以你可以复用这套编译逻辑，用于构建其他程序的独立二进制版本，例如 Nginx 等。
+
+## 环境准备
+
+开发本项目需要 PHP 环境。你可以使用系统自带的 PHP，也可以使用本项目构建的静态 PHP。
+
+无论是使用哪种 PHP，在开发环境，你需要安装这些扩展：
+
+```
+curl,dom,filter,mbstring,openssl,pcntl,phar,posix,sodium,tokenizer,xml,xmlwriter
+```
+
+static-php-cli 项目本身不需要这么多扩展，但在开发过程中，你会用到 Composer 和 PHPUnit 等工具，它们需要这些扩展。
+
+> 对于 static-php-cli 自身构建的 micro 自执行二进制，仅需要 `pcntl,posix,mbstring,tokenizer,phar`。
+
+## 开始开发
+
+继续向下查看项目结构文档，你可以学习 `static-php-cli` 是如何工作的。

docs/zh/develop/php-src-changes.md

@@ -0,0 +1,51 @@
+# 对 PHP 源码的修改
+
+由于 static-php-cli 在静态编译过程中为了实现良好的兼容性、性能和安全性，对 PHP 源码进行了一些修改。下面是目前对 PHP 源码修改的说明。
+
+## micro 相关补丁
+
+基于 phpmicro 项目提供的补丁，static-php-cli 对 PHP 源码进行了一些修改，以适应静态编译的需求。[补丁列表](https://github.com/easysoft/phpmicro/tree/master/patches) 包含：
+
+目前 static-php-cli 在编译时用到的补丁有：
+
+- static_opcache
+- static_extensions_win32
+- cli_checks
+- disable_huge_page
+- vcruntime140
+- win32
+- zend_stream
+- cli_static
+- macos_iconv
+- phar
+
+## PHP <= 8.1 libxml 补丁
+
+因为 PHP 官方仅对 8.1 进行安全更新，旧版本停止更新，所以 static-php-cli 对 PHP 8.1 及以下版本应用了在新版本 PHP 中已经应用的 libxml 编译补丁。
+
+## gd 扩展 Windows 补丁
+
+在 Windows 下编译 gd 扩展需要大幅改动 `config.w32` 文件，static-php-cli 对 gd 扩展进行了一些修改，使其在 Windows 下编译更加方便。
+
+## yaml 扩展 Windows 补丁
+
+yaml 扩展在 Windows 下编译需要修改 `config.w32` 文件，static-php-cli 对 yaml 扩展进行了一些修改，使其在 Windows 下编译更加方便。
+
+## static-php-cli 版本信息插入
+
+static-php-cli 在编译时会在 PHP 版本信息中插入 static-php-cli 的版本信息，以便于识别。
+
+## 加入硬编码 INI 的选项
+
+在使用 `-I` 参数硬编码 INI 到静态 PHP 的功能中，static-php-cli 会修改 PHP 源码以插入硬编码内容。
+
+## Linux 系统修复补丁
+
+部分编译环境可能缺少一些头文件或库，static-php-cli 会在编译时自动修复这些问题，如：
+
+- HAVE_STRLCAT missing problem
+- HAVE_STRLCPY missing problem
+
+## Windows 系统下 Fiber 问题修复补丁
+
+在 Windows 下编译 PHP 时，Fiber 扩展会出现一些问题，static-php-cli 会在编译时自动修复这些问题（修改 php-src 的 `config.w32`）。

docs/zh/develop/source-module.md

@@ -0,0 +1,350 @@
+# 资源模块
+
+static-php-cli 的下载资源模块是一个主要的功能，它包含了所依赖的库、外部扩展、PHP 源码的下载方式和资源解压方式。
+下载的配置文件主要涉及 `source.json` 和 `pkg.json` 文件，这个文件记录了所有可下载的资源的下载方式。
+
+下载功能主要涉及的命令有 `bin/spc download` 和 `bin/spc extract`。其中 `download` 命令是一个下载器，它会根据配置文件下载资源；
+`extract` 命令是一个解压器，它会根据配置文件解压资源。
+
+一般来说，下载资源可能会比较慢，因为这些资源来源于各个官网、GitHub 等不同位置，同时它们也占用了较大空间，所以你可以在一次下载资源后，可重复使用。
+
+下载器的配置文件是 `source.json`，它包含了所有资源的下载方式，你可以在其中添加你需要的资源下载方式，也可以修改已有的资源下载方式。
+
+每个资源的下载配置结构如下，下面是 `libevent` 扩展对应的资源下载配置：
+
+```json
+{
+  "libevent": {
+    "type": "ghrel",
+    "repo": "libevent/libevent",
+    "match": "libevent.+\\.tar\\.gz",
+    "provide-pre-built": true,  
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+这里最主要的字段是 `type`，目前它支持的类型有：
+
+- `url`: 直接使用 URL 下载，例如：`https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz`。
+- `pie`: 使用 PIE（PHP Installer for Extensions）标准从 Packagist 下载 PHP 扩展。
+- `ghrel`: 使用 GitHub Release API 下载，即从 GitHub 项目发布的最新版本中上传的附件下载。
+- `ghtar`: 使用 GitHub Release API 下载，与 `ghrel` 不同的是，`ghtar` 是从项目的最新 Release 中找 `source code (tar.gz)` 下载的。
+- `ghtagtar`: 使用 GitHub Release API 下载，与 `ghtar` 相比，`ghtagtar` 可以从 `tags` 列表找最新的，并下载 `tar.gz` 格式的源码（因为有些项目只使用了 `tag` 发布版本）。
+- `bitbuckettag`: 使用 BitBucket API 下载，基本和 `ghtagtar` 相同，只是这个适用于 BitBucket。
+- `git`: 直接从一个 Git 地址克隆项目来下载资源，适用于任何公开 Git 仓库。
+- `filelist`: 使用爬虫爬取提供文件索引的 Web 下载站点，并获取最新版本的文件名并下载。
+- `custom`: 如果以上下载方式都不能满足，你可以编写 `custom` 后，在 `src/SPC/store/source/` 下新建一个类，并继承 `CustomSourceBase`，自己编写下载脚本。
+
+## source.json 通用参数
+
+source.json 中每个源文件拥有以下字段：
+
+- `license`: 源代码的开源许可证，见下方 **开源许可证** 章节
+- `type`: 必须为上面提到的类型之一
+- `path`（可选）: 释放源码到指定目录而非 `source/{name}`
+- `provide-pre-built`（可选）: 是否提供预编译的二进制文件，如果为 `true`，则会在 `bin/spc download` 时尝试自动下载预编译的二进制文件
+
+::: tip
+`source.json` 中的 `path` 参数可指定相对路径或绝对路径。当指定为相对路径时，路径基于 `source/`。
+:::
+
+## 下载类型 - url
+
+url 类型的资源指的是从 URL 直接下载文件。
+
+包含的参数有：
+
+- `url`: 文件的下载地址，如 `https://example.com/file.tgz`
+- `filename`（可选）: 保存到本地的文件名，如不指定，则使用 url 的文件名
+
+例子（下载 imagick 扩展，并解压缩到 php 源码的扩展存放路径）：
+
+```json
+{
+  "ext-imagick": {
+    "type": "url",
+    "url": "https://pecl.php.net/get/imagick",
+    "path": "php-src/ext/imagick",
+    "filename": "imagick.tgz",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+## 下载类型 - pie
+
+PIE（PHP Installer for Extensions）类型的资源是从 Packagist 下载遵循 PIE 标准的 PHP 扩展。
+该方法会自动从 Packagist 仓库获取扩展信息，并下载相应的分发文件。
+
+包含的参数有：
+
+- `repo`: Packagist 的 vendor/package 名称，如 `vendor/package-name`
+
+例子（使用 PIE 从 Packagist 下载 PHP 扩展）：
+
+```json
+{
+  "ext-example": {
+    "type": "pie",
+    "repo": "vendor/example-extension",
+    "path": "php-src/ext/example",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+::: tip
+PIE 下载类型会自动从 Packagist 元数据中检测扩展信息，包括下载 URL、版本和分发类型。
+扩展必须在其 Packagist 包定义中标记为 `type: php-ext` 或包含 `php-ext` 元数据。
+:::
+
+## 下载类型 - ghrel
+
+ghrel 会从 GitHub Release 中上传的 Assets 下载文件。首先使用 GitHub Release API 获取最新版本，然后根据正则匹配方式下载相应的文件。
+
+包含的参数有：
+
+- `repo`: GitHub 仓库名称
+- `match`: 匹配 Assets 文件的正则表达式
+- `prefer-stable`: 是否优先下载稳定版本（默认为 `false`）
+
+例子（下载 libsodium 库，匹配 Release 中的 libsodium-x.y.tar.gz 文件）：
+
+```json
+{
+  "libsodium": {
+    "type": "ghrel",
+    "repo": "jedisct1/libsodium",
+    "match": "libsodium-\\d+(\\.\\d+)*\\.tar\\.gz",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+## 下载类型 - ghtar
+
+ghtar 会从 GitHub Release Tag 下载文件，与 `ghrel` 不同的是，`ghtar` 是从项目的最新 Release 中找 `source code (tar.gz)` 下载的。
+
+包含的参数有：
+
+- `repo`: GitHub 仓库名称
+- `prefer-stable`: 是否优先下载稳定版本（默认为 `false`）
+
+例子（brotli 库）：
+
+```json
+{
+  "brotli": {
+    "type": "ghtar",
+    "repo": "google/brotli",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+## 下载类型 - ghtagtar
+
+使用 GitHub Release API 下载，与 `ghtar` 相比，`ghtagtar` 可以从 `tags` 列表找最新的，并下载 `tar.gz` 格式的源码（因为有些项目只使用了 `tag` 发布版本）。
+
+包含的参数有：
+
+- `repo`: GitHub 仓库名称
+- `prefer-stable`: 是否优先下载稳定版本（默认为 `false`）
+
+例子（gmp 库）：
+
+```json
+{
+  "gmp": {
+    "type": "ghtagtar",
+    "repo": "alisw/GMP",
+    "license": {
+      "type": "text",
+      "text": "EXAMPLE LICENSE"
+    }
+  }
+}
+```
+
+## 下载类型 - bitbuckettag
+
+使用 BitBucket API 下载，基本和 `ghtagtar` 相同，只是这个适用于 BitBucket。
+
+包含的参数有：
+
+- `repo`: BitBucket 仓库名称
+
+## 下载类型 - git
+
+直接从一个 Git 地址克隆项目来下载资源，适用于任何公开 Git 仓库。
+
+包含的参数有：
+
+- `url`: Git 链接（仅限 HTTPS）
+- `rev`: 分支名称
+
+```json
+{
+  "imap": {
+    "type": "git",
+    "url": "https://github.com/static-php/imap.git",
+    "rev": "master",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+## 下载类型 - filelist
+
+使用爬虫爬取提供文件索引的 Web 下载站点，并获取最新版本的文件名并下载。
+
+注意，该方法仅限于镜像站、GNU 官网等具有页面 index 功能的静态站点使用。
+
+包含的参数有：
+
+- `url`: 要爬取文件最新版本的页面 URL
+- `regex`: 匹配文件名及下载链接的正则表达式
+
+例子（从 GNU 官网下载 libiconv 库）：
+
+```json
+{
+  "libiconv": {
+    "type": "filelist",
+    "url": "https://ftp.gnu.org/gnu/libiconv/",
+    "regex": "/href=\"(?<file>libiconv-(?<version>[^\"]+)\\.tar\\.gz)\"/",
+    "license": {
+      "type": "file",
+      "path": "COPYING"
+    }
+  }
+}
+```
+
+## 下载类型 - custom
+
+如果以上下载方式都不能满足，你可以编写 `custom` 后，在 `src/SPC/store/source/` 下新建一个类，并继承 `CustomSourceBase`，自己编写下载脚本。
+
+这里不再赘述，你可以查看 `src/SPC/store/source/PhpSource.php` 或 `src/SPC/store/source/PostgreSQLSource.php` 作为例子。
+
+## pkg.json 通用参数
+
+pkg.json 存放的是非源码类型的文件资源，例如 musl-toolchain、UPX 等预编译的工具。它的使用包含：
+
+- `type`: 与 `source.json` 相同的类型及不同种类的参数。
+- `extract`（可选）: 下载后解压缩的路径，默认为 `pkgroot/{pkg_name}`。
+- `extract-files`（可选）: 下载后仅解压指定的文件到指定位置。
+
+需要注意的是，`pkg.json` 不涉及源代码的编译和修改分发，所以没有 `license` 开源许可证字段。并且你不能同时使用 `extract` 和 `extract-files` 参数。
+
+例子（下载 nasm 到本地，并只提取程序文件到 PHP SDK）：
+
+```json
+{
+  "nasm-x86_64-win": {
+    "type": "url",
+    "url": "https://www.nasm.us/pub/nasm/releasebuilds/2.16.01/win64/nasm-2.16.01-win64.zip",
+    "extract-files": {
+      "nasm-2.16.01/nasm.exe": "{php_sdk_path}/bin/nasm.exe",
+      "nasm-2.16.01/ndisasm.exe": "{php_sdk_path}/bin/ndisasm.exe"
+    }
+  }
+}
+```
+
+`extract-files` 中的键名为源文件夹下的文件，键值为存放的路径。存放的路径可以使用以下变量：
+
+- `{php_sdk_path}`: （仅限 Windows）PHP SDK 路径
+- `{pkg_root_path}`: `pkgroot/`
+- `{working_dir}`: 当前工作目录
+- `{download_path}`: 下载目录
+- `{source_path}`: 源码解压缩目录
+
+当 `extract-files` 不使用变量且为相对路径时，相对路径的目录为 `{working_dir}`。
+
+## 开源许可证
+
+对于 `source.json` 而言，每个源文件都应包含开源许可证。`license` 字段存放了开源许可证的信息。
+
+每个 `license` 包含的参数有：
+
+- `type`: `file` 或 `text`
+- `path`: 源代码目录中的许可证文件（当 `type` 为 `file` 时，此项必填）
+- `text`: 许可证文本（当 `type` 为 `text` 时，此项必填）
+
+例子（yaml 扩展的源代码中带有 LICENSE 文件）：
+
+```json
+{
+  "yaml": {
+    "type": "git",
+    "path": "php-src/ext/yaml",
+    "rev": "php7",
+    "url": "https://github.com/php/pecl-file_formats-yaml",
+    "license": {
+      "type": "file",
+      "path": "LICENSE"
+    }
+  }
+}
+```
+
+当开源项目拥有多个许可证时，可指定多个文件：
+
+```json
+{
+  "libuv": {
+    "type": "ghtar",
+    "repo": "libuv/libuv",
+    "license": [
+      {
+        "type": "file",
+        "path": "LICENSE"
+      },
+      {
+        "type": "file",
+        "path": "LICENSE-extra"
+      }
+    ]
+  }
+}
+```
+
+当一个开源项目的许可证在不同版本间使用不同的文件，`path` 参数可以使用数组将可能的许可证文件列出：
+
+```json
+{
+  "redis": {
+    "type": "git",
+    "path": "php-src/ext/redis",
+    "rev": "release/6.0.2",
+    "url": "https://github.com/phpredis/phpredis",
+    "license": {
+      "type": "file",
+      "path": [
+        "LICENSE",
+        "COPYING"
+      ]
+    }
+  }
+}
+```

docs/zh/develop/structure.md

@@ -0,0 +1,163 @@
+# 项目结构简介
+
+static-php-cli 主要包含三种逻辑组件：资源、依赖库、扩展。这三种组件四个配置文件：`source.json`、`lib.json`、`ext.json`、`pkg.json`。
+
+一个完整的构建静态 PHP 流程是：
+
+1. 使用资源下载模块 `Downloader` 下载指定或所有资源，这些资源包含 PHP 源码、依赖库源码、扩展源码。
+2. 使用资源解压模块 `SourceExtractor` 解压下载的资源到编译目录。
+3. 使用依赖工具计算出当前加入的扩展的依赖扩展、依赖库，然后对每个需要编译的依赖库进行编译，按照依赖顺序。
+4. 使用对应操作系统下的 `Builder` 构建每个依赖库后，将其安装到 `buildroot` 目录。
+5. 如果包含外部扩展（源码没有包含在 PHP 内的扩展），将外部扩展拷贝到 `source/php-src/ext/` 目录。
+6. 使用 `Builder` 构建 PHP 源码，将其安装到 `buildroot` 目录。
+
+项目主要分为几个文件夹：
+
+- `bin/`: 用于存放程序入口文件，包含 `bin/spc`、`bin/spc-alpine-docker`、`bin/setup-runtime`。
+- `config/`: 包含了所有项目支持的扩展、依赖库以及这些资源下载的地址、下载方式等，：`lib.json`、`ext.json`、`source.json`、`pkg.json`、`pre-built.json`。
+- `src/SPC/`: 项目的核心代码，包含了整个框架以及编译各种扩展和库的命令。
+- `src/globals/`: 项目的全局方法和常量、运行时需要的测试文件（例如：扩展的可用性检查代码）。
+- `vendor/`: Composer 依赖的目录，你无需对它做出任何修改。
+
+其中运行原理就是启动一个 `symfony/console` 的 `ConsoleApplication`，然后解析用户在终端输入的命令。
+
+## 基本命令行结构
+
+`bin/spc` 是一个 PHP 代码入口文件，包含了 Unix 通用的 `#!/usr/bin/env php` 用来让系统自动以系统安装好的 PHP 解释器执行。
+在项目执行了 `new ConsoleApplication()` 后，框架会自动使用反射的方式，解析 `src/SPC/command` 目录下的所有类，并将其注册成为命令。
+
+项目并没有直接使用 Symfony 推荐的 Command 注册方式和命令执行方式，这里做出了一点小变动：
+
+1. 每个命令都使用 `#[AsCommand()]` Attribute 来注册名称和简介。
+2. 将 `execute()` 抽象化，让所有命令基于 `BaseCommand`（它基于 `Symfony\Component\Console\Command\Command`），每个命令本身的执行代码写到了 `handle()` 方法中。
+3. `BaseCommand` 添加了变量 `$no_motd`，用于是否在该命令执行时显示 Figlet 欢迎词。
+4. `BaseCommand` 将 `InputInterface` 和 `OutputInterface` 保存为成员变量，你可以在命令的类内使用 `$this->input` 和 `$this->output`。
+
+## 基本源码结构
+
+项目的源码位于 `src/SPC` 目录，支持 PSR-4 标准的自动加载，包含以下子目录和类：
+
+- `src/SPC/builder/`: 用于不同操作系统下构建依赖库、PHP 及相关扩展的核心编译命令代码，还包含了一些编译的系统工具方法。
+- `src/SPC/command/`: 项目的所有命令都在这里。
+- `src/SPC/doctor/`: Doctor 模块，它是一个较为独立的用于检查系统环境的模块，可使用命令 `bin/spc doctor` 进入。
+- `src/SPC/exception/`: 异常类。
+- `src/SPC/store/`: 有关存储、文件和资源的类都在这里。
+- `src/SPC/util/`: 一些可以复用的工具方法都在这里。
+- `src/SPC/ConsoleApplication.php`: 命令行程序入口文件。
+
+如果你阅读过源码，你可能会发现还有一个 `src/globals/` 目录，它是用于存放一些全局变量、全局方法、构建过程中依赖的非 PSR-4 标准的 PHP 源码，例如测试扩展代码等。
+
+## Phar 应用目录问题
+
+和其他 php-cli 项目一样，spc 自身对路径有额外的考虑。
+因为 spc 可以在 `php-cli directly`、`micro SAPI`、`php-cli with Phar`、`vendor with Phar` 等多种模式下运行，各类根目录存在歧义。这里会进行一个完整的说明。
+此问题一般常见于 PHP 项目中存取文件的基类路径选择问题，尤其是在配合 `micro.sfx` 使用时容易出现路径问题。
+
+注意，此处仅对你在开发 Phar 项目或 PHP 框架时可能有用。
+
+> 接下来我们都将 `static-php-cli`（也就是 spc）当作一个普通的 `php` 命令行程序来看，你可以将 spc 理解为你自己的任何 php-cli 应用以参考。
+
+下面主要有三个基本的常量理论值，我们建议你在编写 php 项目时引入这三种常量：
+
+- `WORKING_DIR`：执行 PHP 脚本时的工作目录
+- `SOURCE_ROOT_DIR` 或 `ROOT_DIR`：项目文件夹的根目录，一般为 `composer.json` 所在目录
+- `FRAMEWORK_ROOT_DIR`：使用框架的根目录，自行开发的框架可能会用到，一般框架目录为只读
+
+你可以在你的框架或者 cli 应用程序入口中定义这些常量，以方便在你的项目中使用路径。
+
+下面是 PHP 内置的常量值，在 PHP 解释器内部已被定义：
+
+- `__DIR__`：当前执行脚本的文件所在目录
+- `__FILE__`：当前执行脚本的文件路径
+
+### Git 项目模式（source）
+
+Git 项目模式指的是一个框架或程序本身在当前文件夹以纯文本形式存放，运行通过 `php path/to/entry.php` 方式。
+
+假设你的项目存放在 `/home/example/static-php-cli/` 目录下，或你的项目就是框架本身，里面包含 `composer.json` 等项目文件：
+
+```
+composer.json
+src/App/MyCommand.app
+vendor/*
+bin/entry.php
+```
+
+我们假设从 `src/App/MyCommand.php` 中获取以上常量：
+
+| Constant             | Value                                                |
+|----------------------|------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/static-php-cli`                       |
+| `SOURCE_ROOT_DIR`    | `/home/example/static-php-cli`                       |
+| `FRAMEWORK_ROOT_DIR` | `/home/example/static-php-cli`                       |
+| `__DIR__`            | `/home/example/static-php-cli/src/App`               |
+| `__FILE__`           | `/home/example/static-php-cli/src/App/MyCommand.php` |
+
+这种情况下，`WORKING_DIR`、`SOURCE_ROOT_DIR`、`FRAMEWORK_ROOT_DIR` 的值是完全一致的：`/home/example/static-php-cli`。
+框架的源码和应用的源码都在当前路径下。
+
+### Vendor 库模式（vendor）
+
+Vendor 库模式一般是指你的项目为框架类或者被其他应用作为 composer 依赖项安装到项目中，存放位置在 `vendor/author/XXX` 目录。
+
+假设你的项目是 `crazywhalecc/static-php-cli`，你或其他人在另一个项目使用 `composer require` 安装了这个项目。
+
+我们假设 static-php-cli 中包含同 `Git 模式` 的除 `vendor` 目录外的所有文件，并从 `src/App/MyCommand` 中获取常量值，
+目录常量应该是：
+
+| Constant             | Value                                                                                |
+|----------------------|--------------------------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/another-app`                                                          |
+| `SOURCE_ROOT_DIR`    | `/home/example/another-app`                                                          |
+| `FRAMEWORK_ROOT_DIR` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli`                       |
+| `__DIR__`            | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App`               |
+| `__FILE__`           | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |
+
+
+这里的 `SOURCE_ROOT_DIR` 就指的是使用 `static-php-cli` 的项目的根目录。
+
+### Git 项目 Phar 模式（source-phar）
+
+Git 项目 Phar 模式指的是将 Git 项目模式的项目目录打包为一个 `phar` 文件的模式。我们假设 `/home/example/static-php-cli` 将打包为一个 Phar 文件，目录有以下文件：
+
+```
+composer.json
+src/App/MyCommand.app
+vendor/*
+bin/entry.php
+```
+
+打包为 `app.phar` 并存放到 `/home/example/static-php-cli` 目录下时，此时执行 `app.phar`，假设执行了 `src/App/MyCommand` 代码，常量在该文件内获取：
+
+| Constant             | Value                                                                |
+|----------------------|----------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/static-php-cli`                                       |
+| `SOURCE_ROOT_DIR`    | `phar:///home/example/static-php-cli/app.phar/`                      |
+| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/static-php-cli/app.phar/`                      |
+| `__DIR__`            | `phar:///home/example/static-php-cli/app.phar/src/App`               |
+| `__FILE__`           | `phar:///home/example/static-php-cli/app.phar/src/App/MyCommand.php` |
+
+因为在 phar 内读取自身 phar 的文件需要 `phar://` 协议进行，所以项目根目录和框架目录将会和 `WORKING_DIR` 不同。
+
+### Vendor 库 Phar 模式（vendor-phar）
+
+Vendor 库 Phar 模式指的是你的项目作为框架安装在其他项目内，存储于 `vendor` 目录下。
+
+我们假设你的项目目录结构如下：
+
+```
+composer.json # 当前项目的 Composer 配置文件
+box.json # 打包 Phar 的配置文件
+another-app.php # 另一个项目的入口文件
+vendor/crazywhalecc/static-php-cli/* # 你的项目被作为依赖库
+```
+
+将该目录 `/home/example/another-app/` 下的这些文件打包为 `app.phar` 时，对于你的项目而言，下面常量的值应为：
+
+| Constant             | Value                                                                                                |
+|----------------------|------------------------------------------------------------------------------------------------------|
+| `WORKING_DIR`        | `/home/example/another-app`                                                                          |
+| `SOURCE_ROOT_DIR`    | `phar:///home/example/another-app/app.phar/`                                                         |
+| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli`                       |
+| `__DIR__`            | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App`               |
+| `__FILE__`           | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |

docs/zh/develop/system-build-tools.md

@@ -0,0 +1,204 @@
+# 系统编译工具
+
+static-php-cli 在构建静态 PHP 时使用了许多系统编译工具，这些工具主要包括：
+
+- `autoconf`: 用于生成 `configure` 脚本。
+- `make`: 用于执行 `Makefile`。
+- `cmake`: 用于执行 `CMakeLists.txt`。
+- `pkg-config`: 用于查找依赖库的安装路径。
+- `gcc`: 用于在 Linux 下编译 C/C++ 语言代码。
+- `clang`: 用于在 macOS 下编译 C/C++ 语言代码。
+
+对于 Linux 和 macOS 操作系统，这些工具通常可以通过包管理安装，这部分在 doctor 模块中编写了。
+理论上我们也可以通过编译和手动下载这些工具，但这样会增加编译的复杂度，所以我们不推荐这样做。
+
+## Linux 环境编译工具
+
+对于 Linux 系统来说，不同发行版的编译工具安装方式不同。而且对于静态编译来说，某些发行版的包管理无法安装用于纯静态编译的库和工具，
+所以对于 Linux 平台及其不同发行版，我们目前提供了多种编译环境的部署措施。
+
+### glibc 环境
+
+glibc 环境指的是系统底层的 `libc` 库（即所有 C 语言编写的程序动态链接的 C 标准库）使用的是 `glibc`，这是大多数发行版的默认环境。
+例如：Ubuntu、Debian、CentOS、RHEL、openSUSE、Arch Linux 等。
+
+而 glibc 环境下，我们使用的包管理、编译器都是默认指向 glibc 的，glibc 不能被良好地静态链接。它不能被静态链接的原因之一是它的网络库 `nss` 无法静态编译。
+
+对于 glibc 环境，在 2.0 RC8 及以后的 static-php-cli 及 spc 中，你可以选择两种方式来构建静态 PHP：
+
+1. 使用 Docker 构建，这是最简单的方式，你可以使用 `bin/spc-alpine-docker` 来构建，它会在 Alpine Linux 环境下构建。
+2. 使用 `bin/spc doctor` 安装 musl-wrapper 和 musl-cross-make 套件，然后直接正常构建。（[相关源码](https://github.com/crazywhalecc/static-php-cli/blob/main/src/SPC/doctor/item/LinuxMuslCheck.php)）
+
+一般来说，这两种构建方式的构建结果是一致的，你可以根据实际需求选择。
+
+在 doctor 模块中，static-php-cli 会先检测当前的 Linux 发行版。如果当前发行版是 glibc 环境，会提示需要安装 musl-wrapper 和 musl-cross-make 套件。
+
+在 glibc 环境下安装 musl-wrapper 的过程如下：
+
+1. 从 musl 官网下载特定版本的 [musl-wrapper 源码](https://musl.libc.org/releases/)。
+2. 使用从包管理安装的 `gcc` 编译 musl-wrapper 源码，生成 `musl-libc` 等库：`./configure --disable-gcc-wrapper && make -j && sudo make install`。
+3. musl-wrapper 相关库将被安装在 `/usr/local/musl` 目录。
+
+在 glibc 环境下安装 musl-cross-make 的过程如下：
+
+1. 从 dl.static-php.dev 下载预编译好的 [musl-cross-make](https://dl.static-php.dev/static-php-cli/deps/musl-toolchain/) 压缩包。
+2. 解压到 `/usr/local/musl` 目录。
+
+::: tip
+在 glibc 环境下，静态编译可以通过直接安装 musl-wrapper 来实现，但是 musl-wrapper 仅包含了 `musl-gcc`，而没有 `musl-g++`，这也就意味着无法编译 C++ 代码。
+所以我们需要 musl-cross-make 来提供 `musl-g++`。
+
+而 musl-cross-make 套件无法在本地直接编译的原因是它的编译环境要求比较高（需要 36GB 以上内存，Alpine Linux 下编译），所以我们提供了预编译好的二进制包，可用于所有 Linux 发行版。
+
+同时，部分发行版的包管理提供了 musl-wrapper，但 musl-cross-make 需要匹配对应的 musl-wrapper 版本，所以我们不使用包管理安装 musl-wrapper。
+
+对于如何编译 musl-cross-make，将在本章节内的 **编译 musl-cross-make** 小节中介绍。
+:::
+
+### musl 环境
+
+musl 环境指的是系统底层的 `libc` 库使用的是 `musl`，这是一种轻量级的 C 标准库，它的特点是可以被良好地静态链接。
+
+对于目前流行的 Linux 发行版，Alpine Linux 使用的就是 musl 环境，所以 static-php-cli 在 Alpine Linux 下可以直接构建静态 PHP，仅需直接从包管理安装基础编译工具（如 gcc、cmake 等）即可。
+
+对于其他发行版，如果你的发行版使用的是 musl 环境，那么你也可以在安装必要的编译工具后直接使用 static-php-cli 构建静态 PHP。
+
+::: tip
+在 musl 环境下，static-php-cli 会自动跳过 musl-wrapper 和 musl-cross-make 的安装。
+:::
+
+### Docker 环境
+
+Docker 环境指的是使用 Docker 容器来构建静态 PHP，你可以使用 `bin/spc-alpine-docker` 来构建。
+执行这个命令前需要先安装 Docker，然后在项目根目录执行 `bin/spc-alpine-docker` 即可。
+
+在执行 `bin/spc-alpine-docker` 后，static-php-cli 会自动下载 Alpine Linux 镜像，然后构建一个 `cwcc-spc-x86_64` 或 `cwcc-spc-aarch64` 的镜像。
+然后一切的构建都在这个镜像内进行，相当于在 Alpine Linux 内编译。总的来说，Docker 环境就是 musl 环境。
+
+## musl-cross-make 工具链编译
+
+在 Linux 中，尽管你不需要手动编译 musl-cross-make 工具，但是如果你想了解它的编译过程，可以参考这里。
+还有一个重要的原因就是，这个可能无法使用 CI、Actions 等自动化工具编译，因为现有的 CI 服务编译环境不满足 musl-cross-make 的编译要求，满足要求的配置价格太高。
+
+musl-cross-make 的编译过程如下：
+
+准备一个 Alpine Linux 环境（直接安装或使用 Docker 均可），编译的过程需要 36GB 以上内存，所以你需要在内存较大的机器上编译。如果没有这么多内存，可能会导致编译失败。
+
+然后将以下内容写入 `config.mak` 文件内：
+
+```makefile
+STAT = -static --static
+FLAG = -g0 -Os -Wno-error
+
+ifneq ($(NATIVE),)
+COMMON_CONFIG += CC="$(HOST)-gcc ${STAT}" CXX="$(HOST)-g++ ${STAT}"
+else
+COMMON_CONFIG += CC="gcc ${STAT}" CXX="g++ ${STAT}"
+endif
+
+COMMON_CONFIG += CFLAGS="${FLAG}" CXXFLAGS="${FLAG}" LDFLAGS="${STAT}"
+
+BINUTILS_CONFIG += --enable-gold=yes --enable-gprofng=no
+GCC_CONFIG += --enable-static-pie --disable-cet --enable-default-pie  
+#--enable-default-pie
+
+CONFIG_SUB_REV = 888c8e3d5f7b
+GCC_VER = 13.2.0
+BINUTILS_VER = 2.40
+MUSL_VER = 1.2.4
+GMP_VER = 6.2.1
+MPC_VER = 1.2.1
+MPFR_VER = 4.2.0
+LINUX_VER = 6.1.36
+```
+
+同时，你需要新建一个 `gcc-13.2.0.tar.xz.sha1` 文件，文件内容如下：
+
+```
+5f95b6d042fb37d45c6cbebfc91decfbc4fb493c  gcc-13.2.0.tar.xz
+```
+
+如果你使用的是 Docker 构建，新建一个 `Dockerfile` 文件，写入以下内容：
+
+```dockerfile
+FROM alpine:edge
+
+RUN apk add --no-cache \
+gcc g++ git make curl perl \
+rsync patch wget libtool \
+texinfo autoconf automake \
+bison tar xz bzip2 zlib \
+file binutils flex \
+linux-headers libintl \
+gettext gettext-dev icu-libs pkgconf \
+pkgconfig icu-dev bash \
+ccache libarchive-tools zip
+
+WORKDIR /opt
+
+RUN git clone https://git.zv.io/toolchains/musl-cross-make.git
+WORKDIR /opt/musl-cross-make
+COPY config.mak /opt/musl-cross-make
+COPY gcc-13.2.0.tar.xz.sha1 /opt/musl-cross-make/hashes
+
+RUN make TARGET=x86_64-linux-musl -j || :
+RUN sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
+RUN make TARGET=x86_64-linux-musl -j
+RUN make TARGET=x86_64-linux-musl install -j
+RUN tar cvzf x86_64-musl-toolchain.tgz output/*
+```
+
+如果你使用的是非 Docker 环境的 Alpine Linux，可以直接执行 Dockerfile 中的命令，例如：
+
+```bash
+apk add --no-cache \
+gcc g++ git make curl perl \
+rsync patch wget libtool \
+texinfo autoconf automake \
+bison tar xz bzip2 zlib \
+file binutils flex \
+linux-headers libintl \
+gettext gettext-dev icu-libs pkgconf \
+pkgconfig icu-dev bash \
+ccache libarchive-tools zip
+
+git clone https://git.zv.io/toolchains/musl-cross-make.git
+# 将 config.mak 拷贝到 musl-cross-make 的工作目录内，你需要将 /path/to/config.mak 替换为你的 config.mak 文件路径
+cp /path/to/config.mak musl-cross-make/
+cp /path/to/gcc-13.2.0.tar.xz.sha1 musl-cross-make/hashes
+
+make TARGET=x86_64-linux-musl -j || :
+sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
+make TARGET=x86_64-linux-musl -j
+make TARGET=x86_64-linux-musl install -j
+tar cvzf x86_64-musl-toolchain.tgz output/*
+```
+
+::: tip
+以上所有脚本都适用于 x86_64 架构的 Linux。如果你需要构建 ARM 环境的 musl-cross-make，只需要将上方所有 `x86_64` 替换为 `aarch64` 即可。
+:::
+
+这个编译过程可能会因为内存不足、网络问题等原因导致编译失败，你可以多尝试几次，或者使用更大内存的机器来编译。
+如果遇到了问题，或者你有更好的改进方案，可以在 [讨论](https://github.com/crazywhalecc/static-php-cli-hosted/issues/1) 中提出。
+
+## macOS 环境编译工具
+
+对于 macOS 系统来说，我们使用的编译工具主要是 `clang`，它是 macOS 系统默认的编译器，同时也是 Xcode 的编译器。
+
+在 macOS 下编译，主要依赖于 Xcode 或 Xcode Command Line Tools，你可以在 App Store 下载 Xcode，或者在终端执行 `xcode-select --install` 来安装 Xcode Command Line Tools。
+
+此外，在 `doctor` 环境检查模块中，static-php-cli 会检查 macOS 系统是否安装了 Homebrew、编译工具等，如果没有，会提示你安装，这里不再赘述。
+
+## FreeBSD 环境编译工具
+
+FreeBSD 也是 Unix 系统，它的编译工具和 macOS 类似，你可以直接使用包管理 `pkg` 安装 `clang` 等编译工具，通过 `doctor` 命令。
+
+## pkg-config 编译
+
+如果你在使用 static-php-cli 构建静态 PHP 时仔细观察编译的日志，你会发现无论编译什么，都会先编译 `pkg-config`，这是因为 `pkg-config` 是一个用于查找依赖库的工具。
+在早期的 static-php-cli 版本中，我们直接使用了包管理安装的 `pkg-config` 工具，但是这样会导致一些问题，例如：
+
+- 即使指定了 `PKG_CONFIG_PATH`，`pkg-config` 也会尝试从系统路径中查找依赖包。
+- 由于 `pkg-config` 会从系统路径中查找依赖包，所以如果系统中存在同名的依赖包，可能会导致编译失败。
+
+为了避免以上问题，我们将 `pkg-config` 编译到用户态的 `buildroot/bin` 内并使用，使用了 `--without-sysroot` 等参数来避免从系统路径中查找依赖包。

docs/zh/faq/index.md

@@ -0,0 +1,96 @@
+# 常见问题
+
+这里将会编写一些你容易遇到的问题。目前有很多，但是我需要花时间来整理一下。
+
+## php.ini 的路径是什么？
+
+在 Linux、macOS 和 FreeBSD 上，`php.ini` 的路径是 `/usr/local/etc/php/php.ini`。
+在 Windows 中，路径是 `C:\windows\php.ini` 或 `php.exe` 所在的当前目录。
+可以在 *nix 系统中使用手动构建选项 `--with-config-file-path` 来更改查找 `php.ini` 的目录。
+
+此外，在 Linux、macOS 和 FreeBSD 上，`/usr/local/etc/php/conf.d` 目录中的 `.ini` 文件也会被加载。
+在 Windows 中，该路径默认为空。
+可以使用手动构建选项 `--with-config-file-scan-dir` 更改该目录。
+
+PHP 默认也会从 [其他标准位置](https://www.php.net/manual/zh/configuration.file.php) 中搜索 `php.ini`。
+
+## 静态编译的 PHP 可以安装扩展吗？
+
+因为传统架构下的 PHP 安装扩展的原理是使用 `.so` 类型的动态链接的库方式安装新扩展，而使用本项目编译的静态链接的 PHP。但是静态链接在不同操作系统有不同的定义。
+
+首先，对于 Linux 系统，静态链接的二进制文件不会链接系统的动态链接库。纯静态链接的二进制文件（`-all-static`）无法加载动态库，因此无法添加新扩展。
+同时，在纯静态模式下，你也不能使用 `ffi` 等扩展来加载外部 `.so` 模块。
+
+你可以使用命令 `ldd buildroot/bin/php` 来检查你在 Linux 下构建的二进制文件是否为纯静态链接。
+
+如果你 [构建基于 GNU libc 的 PHP](../guide/build-with-glibc)，你可以使用 `ffi` 扩展来加载外部 `.so` 模块，并加载具有相同 ABI 的 `.so` 扩展。
+
+例如，你可以使用以下命令构建一个与 glibc 动态链接的静态 PHP 二进制文件，支持 FFI 扩展并加载相同 PHP 版本和相同 TS 类型的 `xdebug.so` 扩展：
+
+```bash
+bin/spc-gnu-docker download --for-extensions=ffi,xml --with-php=8.4
+bin/spc-gnu-docker build ffi,xml --build-cli --debug
+
+buildroot/bin/php -d "zend_extension=/path/to/php{PHP_VER}-{ts/nts}/xdebug.so" --ri xdebug
+```
+
+对于 macOS 平台，macOS 下的几乎所有二进制文件都无法真正纯静态链接，几乎所有二进制文件都会链接 macOS 系统库：`/usr/lib/libresolv.9.dylib` 和 `/usr/lib/libSystem.B.dylib`。
+因此，在 macOS 上，你可以**直接**使用 SPC 构建具有动态链接扩展的静态编译 PHP 二进制文件：
+
+1. 使用 `--build-shared=XXX` 选项构建共享扩展 `xxx.so`。例如：`bin/spc build bcmath,zlib --build-shared=xdebug --build-cli`
+2. 你将获得 `buildroot/modules/xdebug.so` 和 `buildroot/bin/php`。
+3. `xdebug.so` 文件可用于版本和线程安全相同的 php。
+
+对于 Windows 平台，由于官方构建的扩展（如 `php_yaml.dll`）强制使用了 `php8.dll` 动态库作为链接，静态构建的 PHP 不包含任何系统库以外的动态库，
+所以 Windows 下无法加载官方构建的动态扩展。 由于 static-php-cli 还暂未支持构建动态扩展，所以目前还没有让 static-php 加载动态扩展的方法。
+
+不过，Windows 可以正常使用 `FFI` 扩展加载其他的 dll 文件并调用。
+
+## 可以支持 Oracle 数据库扩展吗？
+
+部分依赖库闭源的扩展，如 `oci8`、`sourceguardian` 等，它们没有提供纯静态编译的依赖库文件（`.a`），仅提供了动态依赖库文件（`.so`），
+这些扩展无法使用源码的形式编译到 static-php-cli 中，所以本项目可能永远也不会支持这些扩展。不过，理论上你可以根据上面的问题在 macOS 和 Linux 下接入和使用这类扩展。
+
+如果你对此类扩展有需求，或者大部分人都对这些闭源扩展使用有需求，
+可以看看有关 [standalone-php-cli](https://github.com/crazywhalecc/static-php-cli/discussions/58) 的讨论。欢迎留言。
+
+## 支持 Windows 吗？
+
+该项目目前支持 Windows，但支持的扩展数量较少。Windows 支持并不完美。主要有以下问题：
+
+1. Windows 的编译过程与 *nix 不同，使用的工具链也不同。用于编译每个扩展依赖库的编译工具也几乎完全不同。
+2. Windows 版本的需求也会根据所有使用本项目的人的需求推进。如果很多人需要，我会尽快支持相关扩展。
+
+## 我可以使用 micro 保护我的源代码吗？
+
+不可以。micro.sfx 本质上是将 php 和 php 代码合并为一个文件，没有编译或加密 PHP 代码的过程。
+
+首先，php-src 是 PHP 代码的官方解释器，市场上没有与主流分支兼容的 PHP 编译器。
+我在网上看到一个名为 BPC（Binary PHP Compiler？）的项目可以将 PHP 编译为二进制，但有很多限制。
+
+加密和保护代码的方向与编译不同。编译后，也可以通过逆向工程等方法获得代码。真正的保护仍然通过打包和加密代码等手段进行。
+
+因此，本项目（static-php-cli）和相关项目（lwmbs、swoole-cli）都提供了 php-src 源代码的便捷编译工具。
+本项目和相关项目引用的 phpmicro 只是 PHP 的 sapi 接口封装，而不是 PHP 代码的编译工具。
+PHP 代码的编译器是一个完全不同的项目，因此不考虑额外的情况。
+如果你对加密感兴趣，可以考虑使用现有的加密技术，如 Swoole Compiler、Source Guardian 等。
+
+## 无法使用 ssl
+
+**更新：该问题已在最新版本的 static-php-cli 中修复，现在默认读取系统的证书文件。如果你仍然遇到问题，请尝试下面的解决方案。**
+
+使用 curl、pgsql 等请求 HTTPS 网站或建立 SSL 连接时，可能会出现 `error:80000002:system library::No such file or directory` 错误。
+此错误是由于静态编译的 PHP 未通过 `php.ini` 指定 `openssl.cafile` 导致的。
+
+你可以通过在使用 PHP 前指定 `php.ini` 并在 INI 中添加 `openssl.cafile=/path/to/your-cert.pem` 来解决此问题。
+
+对于 Linux 系统，你可以从 curl 官方网站下载 [cacert.pem](https://curl.se/docs/caextract.html) 文件，也可以使用系统自带的证书文件。
+有关不同发行版的证书位置，请参考 [Golang 文档](https://go.dev/src/crypto/x509/root_linux.go)。
+
+> INI 配置 `openssl.cafile` 不能使用 `ini_set()` 函数动态设置，因为 `openssl.cafile` 是 `PHP_INI_SYSTEM` 类型的配置，只能在 `php.ini` 文件中设置。
+
+## 为什么不支持旧版本的 PHP？
+
+因为旧版本的 PHP 有很多问题，如安全问题、性能问题和功能问题。此外，许多旧版本的 PHP 与最新的依赖库不兼容，这也是不支持旧版本 PHP 的原因之一。
+
+你可以使用 static-php-cli 早期编译的旧版本，如 PHP 8.0，但不会明确支持早期版本。

docs/zh/guide/action-build.md

@@ -0,0 +1,28 @@
+# Action 构建
+
+Action 构建指的是直接使用 GitHub Action 进行编译。
+
+如果你不想自行编译，可以从本项目现有的 Action 下载 Artifact，也可以从自托管的服务器下载：[进入](https://dl.static-php.dev/static-php-cli/common/)
+
+> 自托管的二进制也是由 Action 构建而来，[项目仓库地址](https://github.com/static-php/static-php-cli-hosted)。
+> 包含的扩展有：bcmath,bz2,calendar,ctype,curl,dom,exif,fileinfo,filter,ftp,gd,gmp,iconv,xml,mbstring,mbregex,mysqlnd,openssl,pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,redis,session,simplexml,soap,sockets,sqlite3,tokenizer,xmlwriter,xmlreader,zlib,zip
+
+## 构建方法
+
+使用 GitHub Action 可以方便地构建一个静态编译的 PHP 和 phpmicro，同时可以自行定义要编译的扩展。
+
+1. Fork 本项目。
+2. 进入项目的 Actions，选择 CI 开头的 Workflow（根据你需要的操作系统选择）。
+3. 选择 `Run workflow`，填入你要编译的 PHP 版本、目标类型、扩展列表。（扩展列表使用英文逗号分割，例如 `bcmath,curl,mbstring`）
+4. 如果需要共享扩展（例如 `xdebug`），请设置 `shared-extensions`（使用英文逗号分割，例如 `xdebug`）。
+5. 如果需要 FrankenPHP，请启用 `build-frankenphp`，同时也需要启用 `enable-zts`。
+6. 等待大约一段时间后，进入对应的任务中，获取 `Artifacts`。
+
+如果你选择了 `debug`，则会在构建时输出所有日志，包括编译的日志，以供排查错误。
+
+> 如果你需要在其他环境构建，可以使用 [手动构建](./manual-build)。
+
+## 扩展选择
+
+你可以到 [扩展列表](./extensions) 中查看目前你需要的扩展是否均支持，
+然后到 [在线命令生成](./cli-generator) 中选择你需要编译的扩展，复制扩展字符串到 Action 的 `extensions` 中，编译即可。

docs/zh/guide/build-on-windows.md

@@ -0,0 +1,204 @@
+# 在 Windows 上构建
+
+因为 Windows 系统是 NT 内核，与类 Unix 的操作系统使用的编译工具及操作系统接口几乎完全不同，所以在 Windows 上的构建流程会与 Unix 系统有些许不同。
+
+## GitHub Actions 构建
+
+现在已支持从 Actions 构建 Windows 版本的 static-php 了。
+和 Linux、macOS 一样，你需要先 Fork static-php-cli 仓库到你的 GitHub 账户中，然后你可以进入 [扩展列表](./extensions) 选择要编译的扩展，然后进入自己仓库的 `CI on Windows` 选择 PHP 版本、填入扩展列表（逗号分割），点击 Run 即可。
+
+如果你要在本地开发或构建，请继续向下阅读。
+
+## 环境准备
+
+在 Windows 上构建静态 PHP 所需要的工具与 PHP 官方的 Windows 构建工具是相同的。你可以阅读 [官方文档](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2)。
+
+总结下来，你需要以下环境及工具：
+
+- Windows 10（需要 build 17063 或以后的更新）
+- Visual Studio 2019/2022（推荐 2022）
+- Visual Studio 的 C++ 桌面开发
+- Git for Windows
+- static-php-cli 仓库
+- PHP 和 Composer（static-php-cli 需要它们，可使用 `bin/setup-runtime` 自动安装）
+- [php-sdk-binary-tools](https://github.com/php/php-sdk-binary-tools)（可使用 doctor 自动安装）
+- strawberry-perl（可使用 doctor 自动安装）
+- nasm（可使用 doctor 自动安装）
+
+::: tip
+static-php-cli 在 Windows 上的构建指的是使用 MSVC 构建 PHP，不基于 MinGW、Cygwin、WSL 等环境。
+
+如果你更倾向使用 WSL，请参考在 Linux 上构建的章节。
+:::
+
+在安装 Visual Studio 后，选择 C++ 桌面开发的工作负荷后，可能会下载 8GB 左右的编译工具，下载速度取决于你的网络状况。
+
+### 安装 Git
+
+Git for Windows 可以从 [这里](https://git-scm.com/download/win) 下载并安装 `Standalone Installer 64-bit` 版本，安装在默认位置（`C:\Program Files\Git\`）。
+如果不想手动下载和安装，你也可以使用 Visual Studio Installer，在**单个组件**的选择列表中，勾选 Git。
+
+### 准备 static-php-cli
+
+static-php-cli 项目的下载方式很简单，只需要使用 git clone 即可。推荐将项目放在 `C:\spc-build\` 或类似目录，路径最好不要有空格。
+
+```shell
+mkdir "C:\spc-build"
+cd C:\spc-build
+git clone https://github.com/crazywhalecc/static-php-cli.git
+cd static-php-cli
+```
+
+static-php-cli 自身需要 PHP 环境，是有点奇怪，但现在可以通过脚本快速安装 PHP 环境。 
+一般你的电脑不会安装 Windows 版本的 PHP，所以我们建议你在下载 static-php-cli 后，直接使用 `bin/setup-runtime`，在当前目录安装 PHP 和 Composer。
+
+```shell
+# 安装 PHP 和 Composer 到 ./runtime/ 目录
+bin/setup-runtime
+
+# 安装后，如需在全局命令中使用 PHP 和 Composer，使用下面的命令将 runtime/ 目录添加到 PATH
+bin/setup-runtime -action add-path
+# 删除 PATH 中的 runtime/ 目录
+bin/setup-runtime -action remove-path
+```
+
+在准备好 PHP 和 Composer 环境后，使用 `composer` 安装 static-php-cli 的依赖：
+
+```shell
+cd C:\spc-build\static-php-cli
+runtime/composer install --no-dev
+```
+
+### 自动安装其他依赖
+
+对于 `php-sdk-binary-tools`、`strawberry-perl`、`nasm`，我们更建议你直接使用命令 `bin/spc doctor --auto-fix` 检查并安装。
+
+如果 doctor 成功自动安装，请**跳过**下方手动安装上述工具的步骤。
+
+如果自动安装无法成功的话，再参考下方手动安装的方式。
+
+### 手动安装 php-sdk-binary-tools
+
+```bat
+cd C:\spc-build\static-php-cli
+git clone https://github.com/php/php-sdk-binary-tools.git
+```
+
+> 你也可以在 Windows 设置中设置全局变量 `PHP_SDK_PATH`，并将该项目克隆至变量对应的路径。一般情况下，默认即可。
+
+### 手动安装 strawberry-perl
+
+> 如果你不需要编译 openssl 扩展，可不安装 perl。
+
+1. 从 [GitHub](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/) 下载 strawberry-perl 最新版。
+2. 安装到 `C:\spc-build\static-php-cli\pkgroot\perl\` 目录。
+
+> 你可以下载 `-portable` 版本，并直接解压到上述目录。
+> 最后的 `perl.exe` 应该位于 `C:\spc-build\static-php-cli\pkgroot\perl\perl\bin\perl.exe`。
+
+### 手动安装 nasm
+
+> 如果你不需要编译 openssl 扩展，可不安装 nasm。
+
+1. 从 [官网](https://www.nasm.us/pub/nasm/releasebuilds/) 下载 nasm 工具（x64）。
+2. 将 `nasm.exe`、`ndisasm.exe` 放在 `C:\spc-build\static-php-cli\php-sdk-binary-tools\bin\` 目录。
+
+
+## 下载源码
+
+见 [本地构建 - download](./manual-build.html#命令-download-下载依赖包)
+
+## 编译 PHP
+
+使用 build 命令可以开始构建静态 php 二进制，在执行 `bin/spc build` 命令前，务必先使用 `download` 命令下载资源，建议使用 `doctor` 检查环境。
+
+### 基本用法
+
+你需要先到 [扩展列表](./extensions) 或 [命令生成器](./cli-generator) 选择你要加入的扩展，然后使用命令 `bin/spc build` 进行编译。你需要指定编译目标，从如下参数中选择：
+
+- `--build-cli`: 构建一个 cli sapi（命令行界面，可在命令行执行 PHP 代码）
+- `--build-micro`: 构建一个 micro sapi（用于构建一个包含 PHP 代码的独立可执行二进制）
+
+```shell
+# 编译 PHP，附带 bcmath,openssl,zlib 扩展，编译目标为 cli
+bin/spc build "bcmath,openssl,zlib" --build-cli
+
+# 编译 PHP，附带 bcmath,openssl,zlib 扩展，编译目标为 micro 和 cli
+bin/spc build "bcmath,openssl,zlib" --build-micro --build-cli
+```
+
+::: warning
+在Windows中，最好使用双引号包裹包含逗号的参数，例如 `"bcmath,openssl,mbstring"`
+:::
+
+### 调试
+
+如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
+
+```shell
+bin/spc build "openssl" --build-cli --debug
+```
+
+### 编译运行选项
+
+在编译过程中，有些特殊情况需要对编译器、编译目录的内容进行干预，可以尝试使用以下命令：
+
+- `--with-clean`: 编译 PHP 前先清理旧的 make 产生的文件
+- `--enable-zts`: 让编译的 PHP 为线程安全版本（默认为 NTS 版本）
+- `--with-libs=XXX,YYY`: 编译 PHP 前先编译指定的依赖库，激活部分扩展的可选功能
+- `--with-config-file-scan-dir=XXX`： 读取 `php.ini` 后扫描 `.ini` 文件的目录（在 [这里](../faq/index.html#php-ini-的路径是什么) 查看默认路径）
+- `-I xxx=yyy`: 编译前将 INI 选项硬编译到 PHP 内（支持多个选项，别名是 `--with-hardcoded-ini`）
+- `--with-micro-fake-cli`: 在编译 micro 时，让 micro 的 SAPI 伪装为 `cli`（用于兼容一些检查 `PHP_SAPI` 的程序）
+- `--disable-opcache-jit`: 禁用 opcache jit（默认启用）
+- `--without-micro-ext-test`: 在构建 micro.sfx 后，禁用测试不同扩展在 micro.sfx 的运行结果
+- `--with-suggested-exts`: 编译时将 `ext-suggests` 也作为编译依赖加入
+- `--with-suggested-libs`: 编译时将 `lib-suggests` 也作为编译依赖加入
+- `--with-upx-pack`: 编译后使用 UPX 减小二进制文件体积（需先使用 `bin/spc install-pkg upx` 安装 upx）
+- `--with-micro-logo=XXX.ico`: 自定义 micro 构建组合后的 `exe` 可执行文件的图标（格式为 `.ico`）
+
+有关硬编码 INI 选项，下面是一个简单的例子，我们预设一个更大的 `memory_limit`，并且禁用 `system` 函数：
+
+```shell
+bin/spc build "bcmath,openssl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
+```
+
+另一个例子：自定义 micro 构建后的 `exe` 程序图标：
+
+```shell
+bin/spc build "ffi,bcmath" --build-micro --with-micro-logo=mylogo.ico --debug
+bin/spc micro:combine hello.php
+# Then we got `my-app.exe` with custom logo!
+my-app.exe
+```
+
+## 使用 php.exe
+
+php.exe 编译后位于 `buildroot\bin\` 目录，你可以将其拷贝到任意位置使用。
+
+```shell
+.\php -v
+```
+
+## 使用 micro
+
+> phpmicro 是一个提供自执行二进制 PHP 的项目，本项目依赖 phpmicro 进行编译自执行二进制。详见 [dixyes/phpmicro](https://github.com/dixyes/phpmicro)。
+
+最后编译结果会输出一个 `./micro.sfx` 的文件，此文件需要配合你的 PHP 源码使用。
+该文件编译后会存放在 `buildroot/bin/` 目录中。
+
+使用时应准备好你的项目源码文件，可以是单个 PHP 文件，也可以是 Phar 文件。
+
+> 如果要结合 phar 文件，编译时必须包含 phar 扩展！
+
+```shell
+# code.php "<?php echo 'Hello world' . PHP_EOL;"
+bin/spc micro:combine code.php -O my-app.exe
+# Run it!!! Copy it to another computer!!!
+./my-app.exe
+```
+
+如果打包 PHAR 文件，仅需把 code.php 更换为 phar 文件路径即可。
+你可以使用 [box-project/box](https://github.com/box-project/box) 将你的 CLI 项目打包为 Phar，
+然后将它与 phpmicro 结合，生成独立可执行的二进制文件。
+
+有关 `micro:combine` 命令的更多细节，请参考 Unix 系统上的 [命令](./manual-build)。

docs/zh/guide/build-with-glibc.md

@@ -0,0 +1,54 @@
+# 构建 glibc 兼容的 Linux 二进制
+
+## 为什么要构建 glibc 兼容的二进制
+
+目前，static-php-cli 在默认条件下在 Linux 系统构建的二进制都是基于 musl-libc（静态链接）的。
+musl-libc 是一个轻量级的 libc 实现，它的目标是与 glibc 兼容，并且提供良好的纯静态链接支持。
+这意味着，编译出来的静态 PHP 可执行文件在几乎任何 Linux 发行版都可以使用，而不需要考虑 libc、libstdc++ 等库的版本问题。
+
+但是，Linux 系统的纯静态链接 musl-libc 二进制文件存在以下问题：
+
+- 无法使用 PHP 的 `dl()` 函数加载动态链接库和外部 PHP 扩展。
+- 无法使用 PHP 的 FFI 扩展。
+- 部分极端情况下，可能会出现性能问题，参见 [musl-libc 的性能问题](https://github.com/php/php-src/issues/13648)。
+
+对于不同的 Linux 发行版，它们使用的默认 libc 可能不同，比如 Alpine Linux 使用 musl libc，而大多数 Linux 发行版使用 glibc。
+但即便如此，我们也不能直接使用任意的发行版和 glibc 构建便携的静态二进制文件，因为 glibc 有一些问题：
+
+- 基于新版本的发行版在使用 gcc 等工具构建的二进制，无法在旧版本的发行版上运行。
+- glibc 不推荐被静态链接，因为它的一些特性需要动态链接库的支持。
+
+但是，我们可以使用 Docker 容器来解决这个问题，最终输出的结果是一个动态链接 glibc 和一些必要库的二进制，但它静态链接所有其他依赖。
+
+1. 使用一个旧版本的 Linux 发行版（如 CentOS 7.x），它的 glibc 版本比较旧，但是可以在大多数现代 Linux 发行版上运行。
+2. 在这个容器中构建 PHP 的静态二进制文件，这样就可以在大多数现代 Linux 发行版上运行了。
+
+> 使用 glibc 的静态二进制文件，可以在大多数现代 Linux 发行版上运行，但是不能在 musl libc 的发行版上运行，如 CentOS 6、Alpine Linux 等。
+
+## 构建 glibc 兼容的 Linux 二进制
+
+最新版的 static-php-cli 内置了 `bin/spc-gnu-docker` 脚本，可以一键创建一个 CentOS 7.x (glibc-2.17) 的 Docker 容器，并在容器中构建 glibc 兼容的 PHP 静态二进制文件。
+
+然后，先运行一次以下命令。首次运行时时间较长，因为需要下载 CentOS 7.x 的镜像和一些编译工具。
+
+```bash
+bin/spc-gnu-docker
+```
+
+构建镜像完成后，你将看到和 `bin/spc` 一样的命令帮助菜单，这时说明容器已经准备好了。
+
+在容器准备好后，你可以参考 [本地构建](./manual-build) 章节的内容，构建你的 PHP 静态二进制文件。仅需要把 `bin/spc` 或 `./spc` 替换为 `bin/spc-gnu-docker` 即可。
+
+```bash
+bin/spc-gnu-docker build bcmath,ctype,openssl,pdo,phar,posix,session,tokenizer,xml,zip --build-cli --debug
+```
+
+## 注意事项
+
+极少数情况下，基于 glibc 的静态 PHP 可能会出现 segment fault 等错误，但目前例子较少，如果遇到问题请提交 issue。
+
+glibc 构建为扩展的特性，不属于默认 static-php 的支持范围。如果有相关问题或需求，请在提交 Issue 时注明你是基于 glibc 构建的。
+
+如果你需要不使用 Docker 构建基于 glibc 的二进制，请参考 `bin/spc-gnu-docker` 脚本，手动构建一个类似的环境。
+
+请注意，我们仅支持使用 bin/spc-gnu-docker 构建的 glibc 版本。已在 RHEL 9 和 10 上进行了编译测试并验证其稳定性，但如果您遇到问题，我们可能不会进行修复。

docs/zh/guide/cli-generator.md

@@ -0,0 +1,15 @@
+---
+aside: false
+---
+
+<script setup lang="ts">
+import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
+</script>
+
+# CLI 编译命令生成器
+
+::: tip
+下面选择扩展可能包含所选操作系统不支持的扩展，这可能导致编译失败。请先查阅 [支持的扩展](./extensions)。
+:::
+
+<cli-generator lang="zh" />

docs/zh/guide/deps-map.md

@@ -0,0 +1,22 @@
+---
+outline: 'deep'
+---
+
+# 依赖关系图表
+
+在编译 PHP 时，每个扩展、库都有依赖关系，这些依赖关系可能是必需的，也可能是可选的。在编译 PHP 时，可以选择是否包含这些可选的依赖关系。
+
+例如，在 Linux 下编译 `gd` 扩展时，会强制编译 `zlib,libpng` 库和 `zlib` 扩展，而 `libavif,libwebp,libjpeg,freetype` 库都是可选的库，默认不会编译，除非通过 `--with-libs=avif,webp,jpeg,freetype` 选项指定。
+
+- 对于可选扩展（扩展的可选特性），需手动在编译时指定，例如启用 Redis 的 igbinary 支持：`bin/spc build redis,igbinary`。
+- 对于可选库，需通过 `--with-libs=XXX` 选项编译指定。
+- 如果想启用所有的可选扩展，可以使用 `bin/spc build redis --with-suggested-exts` 参数。
+- 如果想启用所有的可选库，可以使用 `--with-suggested-libs` 参数。
+
+## 扩展的依赖图
+
+<!--@include: ../../deps-map-ext.md-->
+
+## 库的依赖表
+
+<!--@include: ../../deps-map-lib.md-->

docs/zh/guide/env-vars.md

@@ -0,0 +1,112 @@
+# 环境变量
+
+本页面的环境变量列表中所提到的所有环境变量都具有默认值，除非另有说明。你可以通过设置这些环境变量来覆盖默认值。
+
+## 环境变量列表
+
+在 2.3.5 版本之后，我们将环境变量集中到了 `config/env.ini` 文件中，你可以通过修改这个文件来设置环境变量。
+
+我们将 static-php-cli 支持的环境变量分为三种：
+
+- 全局内部环境变量：在 static-php-cli 启动后即声明，你可以在 static-php-cli 的内部使用 `getenv()` 来获取他们，也可以在启动 static-php-cli 前覆盖。
+- 固定环境变量：在 static-php-cli 启动后声明，你仅可使用 `getenv()` 获取，但无法通过 shell 脚本对其覆盖。
+- 配置文件环境变量：在 static-php-cli 构建前声明，你可以通过修改 `config/env.ini` 文件或通过 shell 脚本来设置这些环境变量。
+
+你可以阅读 [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/main/config/env.ini) 中每项参数的注释来了解其作用（仅限英文版）。
+
+## 自定义环境变量
+
+一般情况下，你不需要修改任何以下环境变量，因为它们已经被设置为最佳值。
+但是，如果你有特殊需求，你可以通过设置这些环境变量来满足你的需求（比如你需要调试不同编译参数下的 PHP 性能表现）。
+
+如需使用自定义环境变量，你可以在终端中使用 `export` 命令或者在命令前直接设置环境变量，例如：
+
+```shell
+# export 方式
+export SPC_CONCURRENCY=4
+bin/spc build mbstring,pcntl --build-cli
+
+# 直接设置方式
+SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli
+```
+
+或者，如果你需要长期修改某个环境变量，你可以通过修改 `config/env.ini` 文件来实现。
+
+`config/env.ini` 分为三段，其中 `[global]` 全局有效，`[windows]`、`[macos]`、`[linux]` 仅对应的操作系统有效。
+
+例如，你需要修改编译 PHP 的 `./configure` 命令，你可以在 `config/env.ini` 文件中找到 `SPC_CMD_PREFIX_PHP_CONFIGURE` 环境变量，然后修改其值即可。
+
+但如果你的构建条件比较复杂，需要多种 env.ini 进行切换，我们推荐你使用 `config/env.custom.ini` 文件，这样你可以在不修改默认的 `config/env.ini` 文件的情况下，
+通过写入额外的重载项目指定你的环境变量。
+
+```ini
+; This is an example of `config/env.custom.ini` file, 
+; we modify the `SPC_CONCURRENCY` and linux default CFLAGS passing to libs and PHP
+[global]
+SPC_CONCURRENCY=4
+
+[linux]
+SPC_DEFAULT_C_FLAGS="-O3"
+```
+
+## 编译依赖库的环境变量（仅限 Unix 系统）
+
+从 2.2.0 开始，static-php-cli 对所有 macOS、Linux、FreeBSD 等 Unix 系统的编译依赖库的命令均支持自定义环境变量。
+
+这样你就可以随时通过环境变量来调整编译依赖库的行为。例如你可以通过 `xxx_CFLAGS=-O0` 来设置编译 xxx 库的优化参数。
+
+当然，不是每个依赖库都支持注入环境变量，我们目前提供了三个通配的环境变量，后缀分别为：
+
+- `_CFLAGS`: C 编译器的参数
+- `_LDFLAGS`: 链接器的参数
+- `_LIBS`: 额外的链接库
+
+前缀为依赖库的名称，具体依赖库的名称以 `lib.json` 为准。其中，带有 `-` 的依赖库名称需要将 `-` 替换为 `_`。
+
+下面是一个替换 openssl 库编译的优化选项示例：
+
+```shell
+openssl_CFLAGS="-O0"
+```
+
+库名称使用同 `lib.json` 中列举的名称，区分大小写。
+
+::: tip
+当未指定相关环境变量时，除以下变量外，其余值均默认为空：
+
+| var name              | var default value                                                                               |
+|-----------------------|-------------------------------------------------------------------------------------------------|
+| `pkg_config_CFLAGS`   | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
+| `pkg_config_LDFLAGS`  | Linux: `--static`, Other: empty                                                                 |
+| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty                                                                  |
+| `imagemagick_LIBS`    | macOS: `-liconv`, Other: empty                                                                  |
+| `ldap_LDFLAGS`        | `-L$BUILD_LIB_PATH`                                                                             |
+| `openssl_CFLAGS`      | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty                                                     |
+| others...             | empty                                                                                           |
+
+:::
+
+下表是支持自定义以上三种变量的依赖库名称列表：
+
+| lib name    |
+|-------------|
+| brotli      |
+| bzip        |
+| curl        |
+| freetype    |
+| gettext     |
+| gmp         |
+| imagemagick |
+| ldap        |
+| libargon2   |
+| libavif     |
+| libcares    |
+| libevent    |
+| openssl     |
+
+::: tip
+因为给每个库适配自定义环境变量是一项特别繁琐的工作，且大部分情况下你都不需要这些库的自定义环境变量，所以我们目前只支持了部分库的自定义环境变量。
+
+如果你需要自定义环境变量的库不在上方列表，可以通过 [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues)
+来提出需求。
+:::

docs/zh/guide/extension-notes.md

@@ -0,0 +1,158 @@
+# 扩展注意事项
+
+因为是静态编译，扩展不会 100% 完美编译，而且不同扩展对 PHP、环境都有不同的要求，这里将一一列举。
+
+## curl
+
+HTTP3 支持默认未启用，需在编译时添加 `--with-libs="nghttp2,nghttp3,ngtcp2"` 以启用 PHP 8.4 及以上版本的 HTTP3 支持。
+
+使用 curl 请求 HTTPS 时，可能存在 `error:80000002:system library::No such file or directory` 错误，
+解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
+
+## phpmicro
+
+1. phpmicro SAPI 仅支持 PHP >= 8.0 版本。
+
+## swoole
+
+1. swoole >= 5.0 版本仅支持 PHP >= 8.0 版本。
+2. swoole 目前不支持 PHP 8.0 版本 curl 的 hook（后续有可能会修复）。
+3. 编译时只包含 `swoole` 扩展时不会完整开启支持的 Swoole 数据库协程 hook，如需使用请加入对应的 `swoole-hook-xxx` 扩展。
+4. swoole 在部分扩展组合下可能出现 `zend_mm_heap corrupted` 问题，暂未找到是什么原因导致的。
+
+## swoole-hook-pgsql
+
+swoole-hook-pgsql 不是一个扩展，而是 Swoole 的 Hook 特性。
+如果你在编译时添加了 `swoole,swoole-hook-pgsql`，你将启用 Swoole 的 PostgreSQL 客户端和 `pdo_pgsql` 扩展的协程模式。
+
+swoole-hook-pgsql 与 `pdo_pgsql` 扩展冲突。如需使用 Swoole 和 `pdo_pgsql`，请删除 pdo_pgsql 扩展，启用 `swoole` 和 `swoole-hook-pgsql` 即可。
+该扩展包含了 `pdo_pgsql` 的协程环境的实现。
+
+在 macOS 系统，`pdo_pgsql` 可能无法正常连接到 postgresql 服务器，请谨慎使用。
+
+## swoole-hook-mysql
+
+swoole-hook-mysql 不是一个扩展，而是 Swoole 的 Hook 特性。
+如果你在编译时添加了 `swoole,swoole-hook-mysql`，你将启用 Swoole 的 `mysqlnd` 和 `pdo_mysql` 的协程模式。
+
+## swoole-hook-sqlite
+
+swoole-hook-sqlite 不是一个扩展，而是 Swoole 的 Hook 特性。
+如果你在编译时添加了 `swoole,swoole-hook-sqlite`，你将启用 Swoole 的 `pdo_sqlite` 的协程模式（Swoole 必须为 5.1 以上）。
+
+swoole-hook-sqlite 与 `pdo_sqlite` 扩展冲突。如需使用 Swoole 和 `pdo_sqlite`，请删除 pdo_sqlite 扩展，启用 `swoole` 和 `swoole-hook-sqlite` 即可。
+该扩展包含了 `pdo_sqlite` 的协程环境的实现。
+
+## swoole-hook-odbc
+
+swoole-hook-odbc 不是一个扩展，而是 Swoole 的 Hook 特性。
+如果你在编译时添加了 `swoole,swoole-hook-odbc`，你将启用 Swoole 的 `odbc` 扩展的协程模式。
+
+swoole-hook-odbc 与 `pdo_odbc` 扩展冲突。如需使用 Swoole 和 `pdo_odbc`，请删除 `pdo_odbc` 扩展，启用 `swoole` 和 `swoole-hook-odbc` 即可。
+该扩展包含了 `pdo_odbc` 的协程环境的实现。
+
+## swow
+
+1. swow 仅支持 PHP 8.0+ 版本。
+
+## imagick
+
+1. OpenMP 支持已被禁用，这是维护者推荐的做法，系统软件包也是如此配置。
+
+## imap
+
+1. 该扩展目前不支持 Kerberos。
+2. 由于底层的 c-client、ext-imap 不是线程安全的。 无法在 `--enable-zts` 构建中使用它。
+3. 该扩展已在 PHP 8.4 中被移除，因此我们建议您寻找替代实现，例如 [Webklex/php-imap](https://github.com/Webklex/php-imap)。
+
+## gd
+
+1. gd 扩展依赖了较多的额外图形库，默认情况下，直接使用 `bin/spc build gd` 不会引入和支持部分图形库，例如 `libjpeg`、`libavif` 等，
+需要使用 `--with-libs` 参数补全。目前支持 `freetype,libjpeg,libavif,libwebp` 四个库的支持，所以这里可以使用以下命令来让 gd 库引入它们：
+
+```bash
+bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
+```
+
+## mcrypt
+
+1. 目前未支持，未来也不计划支持此扩展。[#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
+
+## oci8
+
+1. oci8 是 Oracle 数据库的扩展，因为 Oracle 提供的扩展所依赖的库未提供静态编译版本（`.a`）或源代码，无法使用静态链接的方式将此扩展编译到 php 内，故无法支持。
+
+## xdebug
+
+1. Xdebug 只能作为共享扩展进行构建。您需要使用除了 `musl-static` 外的其他 `SPC_TARGET` 构建目标。
+2. 使用 Linux/glibc 或 macOS 时，您可以使用 `--build-shared=xdebug` 将 Xdebug 编译为共享扩展。
+   编译后的 `./php` 二进制文件可以通过指定 INI 文件进行配置和运行，例如 `./php -d 'zend_extension=/path/to/xdebug.so' your-code.php`。
+
+## xml
+
+1. xml包括 xmlreader、xmlwriter、dom、simplexml 等，添加 xml 扩展时最好同时启用这些扩展。
+2. libxml 包含在 xml 扩展中。 启用 xml 相当于启用 libxml。
+
+## glfw
+
+1. glfw 扩展依赖 OpenGL，在 Linux 平台还依赖 X11 等环境，这些库都无法被轻易地动态链接。
+2. 在 macOS 系统下，我们可以动态链接系统的 OpenGL 和一些相关的库。
+
+## rar
+
+1. rar 扩展目前在 macOS x86_64 环境下与 `common` 扩展集合编译 phpmicro 存在问题。
+
+## pgsql
+
+~~pgsql ssl 连接与 openssl 3.2.0 不兼容。相关链接：~~
+
+- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
+- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
+- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
+
+pgsql 16.2 修复了这个 Bug，现在正常工作了。
+
+在 pgsql 使用 SSL 连接时，可能存在 `error:80000002:system library::No such file or directory` 错误，
+解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
+
+## openssl
+
+使用基于 openssl 的扩展（如 curl、pgsql 等网络库）时，可能存在 `error:80000002:system library::No such file or directory` 错误，
+解决办法详见 [FAQ - 无法使用 ssl](../faq/#无法使用-ssl)。
+
+## password-argon2
+
+1. password-argon2不是一个标准的扩展。`password_hash` 函数的 `PASSWORD_ARGON2ID` 算法需要 libsodium 或 libargon2 才能工作。
+2. 使用 password-argon2 可以为此启用多线程支持。
+
+## ffi
+
+1. 由于 musl libc 静态链接的限制，无法加载动态库，因此无法使用 ffi。
+   如果您需要使用 ffi 扩展，请参阅 [使用 GNU libc 编译 PHP](./build-with-glibc)。
+2. macOS 支持 ffi 扩展，但某些内核不包含调试符号时会出现错误。
+3. Windows x64 支持 ffi 扩展。
+
+## xhprof
+
+xhprof 扩展包含三部分：`xhprof_extension`、`xhprof_html`、`xhprof_libs`。编译的二进制中只包含 `xhprof_extension`。
+如果需要使用 xhprof，请到 [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) 下载源码，指定 `xhprof_libs` 和 `xhprof_html` 路径来使用。
+
+## event
+
+event 扩展在 macOS 系统下编译后暂无法使用 `openpty` 特性。相关 Issue：
+
+- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
+
+## parallel
+
+parallel 扩展只支持 PHP 8.0 及以上版本，并只支持 ZTS 构建（`--enable-zts`）。
+
+## spx
+
+1. SPX 目前不支持 Windows，且官方仓库也不支持静态编译，static-php-cli 使用了 [修改版本](https://github.com/static-php/php-spx)。
+
+## mimalloc
+
+1. 从技术上讲，这不是扩展，而是一个库。
+2. 在 Linux 或 macOS 上使用 `--with-libs="mimalloc"` 进行构建将覆盖默认分配器。
+3. 目前，这还处于实验阶段，但建议在线程环境中使用。

docs/zh/guide/extensions.md

@@ -0,0 +1,22 @@
+<script setup>
+import SearchTable from "../../.vitepress/components/SearchTable.vue";
+</script>
+
+# 扩展列表
+
+> - `yes`: 已支持
+> - 空白: 目前还不支持，或正在支持中
+> - `no` with issue link: 确定不支持或无法支持
+> - `partial` with issue link: 已支持，但是无法完美工作
+
+
+<search-table />
+
+::: tip
+如果缺少您需要的扩展，您可以创建 [功能请求](https://github.com/crazywhalecc/static-php-cli/issues)。
+
+有些扩展或扩展依赖的库会有一些可选的特性，例如 gd 库可选支持 libwebp、freetype 等。
+如果你只使用 `bin/spc build gd --build-cli` 是不会包含它们（static-php-cli 默认为最小依赖原则）。
+
+有关编译可选库，请参考 [扩展、库的依赖关系图表](./deps-map)。对于可选的库，你也可以从 [编译命令生成器](./cli-generator) 中选择扩展后展开选择可选库。
+:::

docs/zh/guide/index.md

@@ -0,0 +1,48 @@
+# 指南
+
+static-php-cli 是一个用于构建静态编译的 PHP 二进制的工具，目前支持 Linux 和 macOS 系统。
+
+在指南章节中，你将了解到如何使用 static-php-cli 构建独立的 php 程序。
+
+- [本地构建](./manual-build)
+- [Action 构建](./action-build)
+- [扩展列表](./extensions)
+
+## 编译环境
+
+下面是架构支持情况，:gear: 代表支持 GitHub Action 构建，:computer: 代表支持本地构建，空 代表暂不支持。
+
+|         | x86_64            | aarch64           |
+|---------|-------------------|-------------------|
+| macOS   | :gear: :computer: | :gear: :computer: |
+| Linux   | :gear: :computer: | :gear: :computer: |
+| Windows | :gear: :computer: |                   |
+| FreeBSD | :computer:        | :computer:        |
+
+当前支持编译的 PHP 版本：
+
+> :warning: 部分支持，对于新的测试版和旧版本可能存在问题。
+>
+> :heavy_check_mark: 支持
+>
+> :x: 不支持
+
+| PHP Version | Status             | Comment                                                 |
+|-------------|--------------------|---------------------------------------------------------|
+| 7.2         | :x:                |                                                         |
+| 7.3         | :x:                | phpmicro 和许多扩展不支持 7.3、7.4 版本                            |
+| 7.4         | :x:                | phpmicro 和许多扩展不支持 7.3、7.4 版本                            |
+| 8.0         | :warning:          | PHP 官方已停止 8.0 的维护，我们不再处理 8.0 相关的 backport 支持            |
+| 8.1         | :warning:          | PHP 官方仅对 8.1 提供安全更新，在 8.5 发布后我们不再处理 8.1 相关的 backport 支持 |
+| 8.2         | :heavy_check_mark: |                                                         |
+| 8.3         | :heavy_check_mark: |                                                         |
+| 8.4         | :heavy_check_mark: |                                                         |
+| 8.5 (beta)  | :warning:          | PHP 8.5 目前处于 beta 阶段                                    |
+
+> 这个表格的支持状态是 static-php-cli 对构建对应版本的支持情况，不是 PHP 官方对该版本的支持情况。
+
+## PHP 支持版本
+
+目前，static-php-cli 对 PHP 8.2 ~ 8.5 版本是支持的，对于 PHP 8.1 及更早版本理论上支持，只需下载时选择早期版本即可。
+但由于部分扩展和特殊组件已对早期版本的 PHP 停止了支持，所以 static-php-cli 不会明确支持早期版本。
+我们推荐你编译尽可能新的 PHP 版本，以获得更好的体验。

docs/zh/guide/manual-build.md

@@ -0,0 +1,640 @@
+---
+outline: 'deep'
+---
+
+# 本地构建（Linux、macOS、FreeBSD）
+
+本章节为 Linux、macOS、FreeBSD 的构建过程，如果你要在 Windows 上构建，请到 [在 Windows 上构建](./build-on-windows)。
+
+## 手动构建（使用 SPC 二进制）（推荐）
+
+本项目提供了一个 static-php-cli 的二进制文件，你可以直接下载对应平台的二进制文件，然后使用它来构建静态的 PHP。目前 `spc` 二进制支持的平台有 Linux 和 macOS。
+
+使用以下命令从自托管服务器下载：
+
+```bash
+# Download from self-hosted nightly builds (sync with main branch)
+# For Linux x86_64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
+# For Linux aarch64
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
+# macOS x86_64 (Intel)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
+# macOS aarch64 (Apple)
+curl -fsSL -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
+# Windows (x86_64, win10 build 17063 or later)
+curl.exe -fsSL -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
+
+# Add execute perm (Linux and macOS only)
+chmod +x ./spc
+
+# Run (Linux and macOS)
+./spc --version
+# Run (Windows powershell)
+.\spc.exe --version
+```
+
+> 如果你使用的是打包好的 `spc` 二进制，你需要将下面所有命令中 `bin/spc` 开头替换为 `./spc`。
+
+## 手动构建（使用源码）
+
+如果使用 spc 二进制出现问题，或你有修改 static-php-cli 源码需求，请从源码下载 static-php-cli。
+
+目前支持在 macOS、Linux 上构建，macOS 支持最新版操作系统和两种架构，Linux 支持 Debian、RHEL 及衍生发行版、Alpine Linux 等。
+
+因为本项目本身采用 PHP 开发，所以在编译时也需要系统安装 PHP。本项目本身也提供了适用于本项目的静态二进制 php，可以根据实际情况自行选择使用。
+
+### 下载本项目
+
+```bash
+git clone https://github.com/crazywhalecc/static-php-cli.git --depth=1
+cd static-php-cli
+
+# 你需要先安装 PHP 环境后再运行 Composer 和本项目，安装方式可参考下面。
+composer update
+```
+
+### 使用预编译静态 PHP 二进制运行 static-php-cli
+
+如果你不想使用 Docker、在系统内安装 PHP，可以直接下载本项目自身编译好的 php 二进制 cli 程序。使用流程如下：
+
+使用命令部署环境，此脚本会从 [自托管的服务器](https://dl.static-php.dev/static-php-cli/) 下载一个当前操作系统的 php-cli 包，
+并从 [getcomposer](https://getcomposer.org/download/latest-stable/composer.phar) 或 [Aliyun（镜像）](https://mirrors.aliyun.com/composer/composer.phar) 下载 Composer。
+
+::: tip
+使用预编译静态 PHP 二进制目前仅支持 Linux 和 macOS。FreeBSD 环境因为缺少自动化构建环境，所以暂不支持。
+:::
+
+```bash
+bin/setup-runtime
+
+# 对于中国大陆地区等网络环境特殊的用户，可使用镜像站加快下载速度
+bin/setup-runtime --mirror china
+```
+
+此脚本总共会下载两个文件：`bin/php` 和 `bin/composer`，下载完成后，有两种使用方式：
+
+1. 将 `bin/` 目录添加到 PATH 路径中：`export PATH="/path/to/your/static-php-cli/bin:$PATH"`，添加路径后，相当于系统安装了 PHP，可直接使用 `composer`、`php -v` 等命令，也可以直接使用 `bin/spc`。
+2. 直接调用，比如执行 static-php-cli 命令：`bin/php bin/spc --help`，执行 Composer：`bin/php bin/composer update`。
+
+### 使用 Docker 环境
+
+如果你不愿意在系统安装 PHP 和 Composer 运行环境，可以使用内置的 Docker 环境构建脚本。
+
+```bash
+# 直接使用，将所有使用的命令中 `bin/spc` 替换为 `bin/spc-alpine-docker` 即可
+bin/spc-alpine-docker
+```
+
+首次执行命令会使用 `docker build` 构建一个 Docker 镜像，默认构建的 Docker 镜像为 `x86_64` 架构，镜像名称为 `cwcc-spc-x86_64`。
+
+如果你想在 `x86_64` 环境下构建 `aarch64` 的 static-php-cli，可以使用 qemu 模拟 arm 镜像运行 Docker，但速度会非常慢。使用参数：`SPC_USE_ARCH=aarch64 bin/spc-alpine-docker`。
+
+如果运行后提示需要 sudo 才能运行，执行一次以下命令可授予 static-php-cli 执行 sudo 的权限：
+
+```bash
+export SPC_USE_SUDO=yes
+```
+
+### 使用系统 PHP 环境
+
+下面是系统安装 PHP、Composer 的一些示例命令。具体安装方式建议自行搜索或询问 AI 搜索引擎获取答案，这里不多赘述。
+
+```bash
+# [macOS], 需要先安装 Homebrew. See https://brew.sh/
+# Remember change your composer executable path. For M1/M2 Chip mac, "/opt/homebrew/bin/", for Intel mac, "/usr/local/bin/". Or add it to your own path.
+brew install php wget
+wget https://getcomposer.org/download/latest-stable/composer.phar -O /path/to/your/bin/composer && chmod +x /path/to/your/bin/composer
+
+# [Debian], you need to make sure your php version >= 8.4 and composer >= 2.0
+sudo apt install php-cli composer php-tokenizer
+```
+
+::: tip
+目前 Ubuntu 部分版本的 apt 安装的 php 版本较旧，故不提供安装命令。如有需要，建议先添加 ppa 等软件源后，安装最新版的 PHP 以及 tokenizer、xml、phar 扩展。
+
+较老版本的 Debian 默认安装的可能为旧版本（<= 8.3）版本的 PHP，建议先升级 Debian 或使用 Docker 或自带的静态二进制环境。
+:::
+
+## 使用 craft 构建（推荐）
+
+使用 `bin/spc craft` 可以使用一个配置文件，一个命令实现自动检查环境、下载源代码、构建依赖库、构建 PHP 及扩展等。
+
+你需要编写一个 `craft.yml` 文件，存放在当前工作目录下。`craft.yml` 可以由 [命令生成器](./cli-generator) 生成，或者手动编写。
+
+手动编写可参考 [craft.yml 配置](../develop/craft-yml.md) 中的注释来编写。我们下面假设你编译一个扩展组合，并选用 PHP 8.4，输出 `cli` 和 `fpm`：
+
+```yaml
+# path/to/craft.yml
+php-version: 8.4
+extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
+sapi:
+  - cli
+  - fpm
+```
+
+然后使用 `bin/spc craft` 命令来编译：
+
+```bash
+bin/spc craft --debug
+```
+
+如果构建成功，你会在当前目录下看到 `buildroot/bin` 目录，里面包含了编译好的 PHP 二进制文件，或相应的 SAPI。
+
+- cli: Windows 下构建结果为 `buildroot/bin/php.exe`，其他平台为 `buildroot/bin/php`。
+- fpm: 构建结果为 `buildroot/bin/php-fpm`。
+- micro: 构建结果为 `buildroot/bin/micro.sfx`，如需进一步与 PHP 代码打包，请查看 [打包 micro 二进制](./manual-build#命令-micro-combine-打包-micro-二进制)。
+- embed: 参见 [embed 使用](./manual-build#embed-使用)。
+- frankenphp: 构建结果为 `buildroot/bin/frankenphp`。
+
+如果中途构建出错，你可以使用 `--debug` 参数查看详细的错误信息，或者使用 `--with-clean` 参数清除旧的编译结果，重新编译。
+
+如使用以上方式仍构建失败，请提交一个 issue，附上你的 `craft.yml` 文件、`log/` 目录的压缩包。
+
+## 分步构建命令
+
+如果你有定制化需求，或分开下载、编译 PHP 和依赖库的需求，可以使用 `bin/spc` 命令分步执行。
+
+### 命令 download - 下载依赖包
+
+使用命令 `bin/spc download` 可以下载编译需要的源代码，包括 php-src 以及依赖的各种库的源码。
+
+```bash
+# 仅下载要编译的扩展及依赖库（使用扩展名，包含可选库）
+bin/spc download --for-extensions=openssl,swoole,zip,pcntl,zstd
+
+# 仅下载要编译的扩展及依赖库（使用扩展名，不包含可选库）
+bin/spc download --for-extensions=openssl,swoole,zip,pcntl --without-suggestions
+
+# 仅下载要编译的库（包括其依赖，使用库名，包含可选库，可以和 --for-extensions 组合使用）
+bin/spc download --for-libs=liblz4,libevent --for-extensions=pcntl,rar,xml
+
+# 仅下载要编译的库（包括其依赖，使用库名，不包含可选库）
+bin/spc download --for-libs=liblz4,libevent --without-suggestions
+
+# 下载资源时，忽略部分资源的缓存，强制下载（如切换特定 PHP 版本）
+bin/spc download --for-extensions=curl,pcntl,xml --ignore-cache-sources=php-src --with-php=8.3.10
+
+# 下载资源时，优先下载有预编译包的依赖库（减少编译依赖的时间）
+bin/spc download --for-extensions="curl,pcntl,xml,mbstring" --prefer-pre-built
+
+# 下载所有依赖包
+bin/spc download --all
+
+# 下载所有依赖包，并指定下载的 PHP 主版本，可选：8.1，8.2，8.3，8.4，也可以使用特定的版本，如 8.3.10。
+bin/spc download --all --with-php=8.3
+
+# 下载时显示下载进度条（curl）
+bin/spc download --all --debug
+
+# 删除旧的下载数据
+bin/spc download --clean
+
+# 仅下载指定的资源（使用资源名）
+bin/spc download php-src,micro,zstd,ext-zstd
+
+# 设置重试次数
+bin/spc download --all --retry=2
+```
+
+如果你所在地区的网络不好，或者下载依赖包速度过于缓慢，可以从 GitHub Action 下载每周定时打包的 `download.zip`，并使用命令直接使用 zip 压缩包作为依赖。
+依赖包可以从 [Action](https://github.com/static-php/static-php-cli-hosted/actions/workflows/download-cache.yml) 下载到本地。
+进入 Action 并选择一个最新成功运行的 Workflow，下载 `download-files-x.y` 即可。
+
+```bash
+bin/spc download --from-zip=/path/to/your/download.zip
+```
+
+如果某个 source 始终无法下载，或者你需要下载一些特定版本的包，例如下载测试版 PHP、旧版本库等，可以使用参数 `-U` 或 `--custom-url` 重写下载链接，
+让下载器强制使用你指定的链接下载此 source 的包。使用方法为 `{source-name}:{url}` 即可，可同时重写多个库的下载地址。在使用 `--for-extensions` 选项下载时同样可用。
+
+```bash
+# 例如：指定下载 Alpha 版的 PHP8.5
+bin/spc download --all -U "php-src:https://downloads.php.net/~edorian/php-8.5.0alpha2.tar.xz"
+
+# 指定下载旧版本的 curl 库
+bin/spc download --all -U "curl:https://curl.se/download/curl-7.88.1.tar.gz"
+```
+
+如果你下载的资源不是链接，而是一个 Git 仓库，你可以使用 `-G` 或 `--custom-git` 重写下载链接，让下载器强制使用你指定的 Git 仓库下载此 source 的包。
+使用方法为 `{source-name}:{branch}:{url}` 即可，可同时重写多个库的下载地址。在使用 `--for-extensions` 选项下载时同样可用。
+
+```bash
+# 例如：下载 master 分支的 php-src
+bin/spc download --for-extensions=redis,phar -G "php-src:master:https://github.com/php/php-src.git"
+
+# 从 swoole-src 仓库下载 master 分支的最新代码，而不是发行版
+bin/spc download --for-extensions=swoole -G "swoole:master:https://github.com/swoole/swoole-src.git"
+```
+
+### 命令 doctor - 环境检查
+
+如果你可以正常运行 `bin/spc` 但无法正常编译静态的 PHP 或依赖库，可以先运行 `bin/spc doctor` 检查系统自身是否缺少依赖。
+
+```bash
+# 快速检查
+bin/spc doctor
+
+# 快速检查，并在可以自动修复的时候修复（使用包管理安装依赖包，仅支持上述提到的操作系统及发行版）
+bin/spc doctor --auto-fix
+```
+
+### 命令 build - 编译 PHP
+
+使用 build 命令可以开始构建静态 php 二进制，在执行 `bin/spc build` 命令前，务必先使用 `download` 命令下载资源，建议使用 `doctor` 检查环境。
+
+#### 基本用法
+
+你需要先到 [扩展列表](./extensions) 或 [命令生成器](./cli-generator) 选择你要加入的扩展，然后使用命令 `bin/spc build` 进行编译。你需要指定一个编译目标，从如下参数中选择：
+
+- `--build-cli`: 构建一个 cli sapi（命令行界面，可在命令行执行 PHP 代码）
+- `--build-fpm`: 构建一个 fpm sapi（php-fpm，用于和其他传统的 fpm 架构的软件如 nginx 配合使用）
+- `--build-cgi`: 构建一个 cgi sapi（cgi，可用于传统的 cgi 架构的软件如 apache 配合使用）
+- `--build-micro`: 构建一个 micro sapi（用于构建一个包含 PHP 代码的独立可执行二进制）
+- `--build-embed`: 构建一个 embed sapi（用于嵌入到其他 C 语言程序中）
+- `--build-frankenphp`: 构建一个 [frankenphp](https://github.com/php/frankenphp) 二进制
+- `--build-all`: 构建以上所有 sapi
+
+```bash
+# 编译 PHP，附带 bcmath,curl,openssl,ftp,posix,pcntl 扩展，编译目标为 cli
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+
+# 编译 PHP，附带 phar,curl,posix,pcntl,tokenizer 扩展，编译目标为 micro
+bin/spc build phar,curl,posix,pcntl,tokenizer --build-micro
+```
+
+::: tip
+如果你需要重复构建、调试，你可以删除 `buildroot/` 和 `source/` 两个目录，这样你可以从已下载的源码压缩包重新解压并构建：
+
+```shell
+# remove
+rm -rf buildroot source
+# build again
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+```
+:::
+
+::: tip
+如果你想构建多个版本的 PHP，且不想每次都重复构建其他依赖库，可以使用 `switch-php-version` 在编译好一个版本后快速切换至另一个版本并编译：
+
+```shell
+# switch to 8.4
+bin/spc switch-php-version 8.4
+# build
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+# switch to 8.1
+bin/spc switch-php-version 8.1
+# build
+bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
+```
+:::
+
+#### 编译运行选项
+
+在编译过程中，有些特殊情况需要对编译器、编译目录的内容进行干预，可以尝试使用以下命令：
+
+- `--cc=XXX`: 指定 C 语言编译器的执行命令（Linux 默认 `musl-gcc` 或 `gcc`，macOS 默认 `clang`）
+- `--cxx=XXX`: 指定 C++ 语言编译器的执行命令（Linux 默认 `g++`，macOS 默认 `clang++`）
+- `--with-clean`: 编译 PHP 前先清理旧的 make 产生的文件
+- `--enable-zts`: 让编译的 PHP 为线程安全版本（默认为 NTS 版本）
+- `--no-strip`: 编译 PHP 库后不运行 `strip` 裁剪二进制文件缩小体积
+- `--with-libs=XXX,YYY`: 编译 PHP 前先编译指定的依赖库，激活部分扩展的可选功能（例如 gd 库的 libavif 等）
+- `--with-config-file-path=XXX`： 查找 `php.ini` 的路径（在 [这里](../faq/index.html#php-ini-的路径是什么) 查看默认路径）
+- `--with-config-file-scan-dir=XXX`： 读取 `php.ini` 后扫描 `.ini` 文件的目录（在 [这里](../faq/index.html#php-ini-的路径是什么) 查看默认路径）
+- `-I xxx=yyy`: 编译前将 INI 选项硬编译到 PHP 内（支持多个选项，别名是 `--with-hardcoded-ini`）
+- `--with-micro-fake-cli`: 在编译 micro 时，让 micro 的 SAPI 伪装为 `cli`（用于兼容一些检查 `PHP_SAPI` 的程序）
+- `--disable-opcache-jit`: 禁用 opcache jit（默认启用）
+- `-P xxx.php`: 在 static-php-cli 编译过程中注入外部脚本（详见下方 **注入外部脚本**）
+- `--without-micro-ext-test`: 在构建 micro.sfx 后，禁用测试不同扩展在 micro.sfx 的运行结果
+- `--with-suggested-exts`: 编译时将 `ext-suggests` 也作为编译依赖加入
+- `--with-suggested-libs`: 编译时将 `lib-suggests` 也作为编译依赖加入
+- `--with-upx-pack`: 编译后使用 UPX 减小二进制文件体积（需先使用 `bin/spc install-pkg upx` 安装 upx）
+- `--build-shared=XXX,YYY`: 编译时将指定的扩展编译为共享库（默认编译为静态库）
+
+硬编码 INI 选项适用于 cli、micro、embed。有关硬编码 INI 选项，下面是一个简单的例子，我们预设一个更大的 `memory_limit`，并且禁用 `system` 函数：
+
+```bash
+bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
+```
+
+## 命令 micro:combine - 打包 micro 二进制
+
+使用 `micro:combine` 命令可以将上面编译好的 `micro.sfx` 和你的代码（`.php` 或 `.phar` 文件）构建为一个可执行二进制。
+你也可以使用该命令直接构建一个注入了 ini 配置的 micro 自执行二进制文件。
+
+::: tip
+注入 ini 配置指的是，在将 micro.sfx 和 PHP 源码结合前，在 micro.sfx 后追加一段特殊的结构用于保存 ini 配置项。
+
+micro.sfx 可通过特殊的字节来标识 INI 文件头，通过 INI 文件头可以实现 micro 带 INI 启动。
+
+此特性的原说明地址在 [phpmicro - Wiki](https://github.com/easysoft/phpmicro/wiki/INI-settings)，这个特性也有可能在未来发生变化。
+:::
+
+下面是常规用法，直接打包 php 源码到一个文件中：
+
+```bash
+# 在做打包流程前，你应该先使用 `build --build-micro` 编译好 micro.sfx
+echo "<?php echo 'hello';" > a.php
+bin/spc micro:combine a.php
+
+# 使用
+./my-app
+```
+
+你可以使用以下参数指定要输出的文件名，你也可以指定其他路径的 micro.sfx 进行打包。
+
+```bash
+# 指定输出文件名
+bin/spc micro:combine a.php --output=custom-bin
+# 使用绝对路径，也可以使用简化参数名
+bin/spc micro:combine a.php -O /tmp/my-custom-app
+
+# 指定其他位置的 micro.sfx 进行打包
+bin/spc micro:combine a.app --with-micro=/path/to/your/micro.sfx
+```
+
+如果想注入 ini 配置项，可以使用下面的参数，从文件或命令行选项添加 ini 到可执行文件中。
+
+```bash
+# 使用命令行选项指定（-I 是 --with-ini-set 的简写）
+bin/spc micro:combine a.php -I "a=b" -I "foo=bar"
+
+# 使用 ini 文件指定（-N 是 --with-ini-file 的简写）
+bin/spc micro:combine a.php -N /path/to/your/custom.ini
+```
+
+::: warning
+注意，请不要直接使用 PHP 源码或系统安装的 PHP 中的 `php.ini` 文件，最好手动编写一个自己需要的参数配置文件，例如：
+
+```ini
+; custom.ini
+curl.cainfo=/path/to/your/cafile.pem
+memory_limit=1G
+```
+
+该命令的注入 ini 是通过在 micro.sfx 后追加一段特殊的结构来实现的，和编译时插入硬编码 INI 的功能不同。
+:::
+
+如果要打包 phar，只需要将 `a.php` 替换为打包好的 phar 文件即可。但要注意，phar 下的 micro.sfx 需要额外注意路径问题，见 [Developing - Phar 路径问题](../develop/structure#phar-应用目录问题)
+
+## 调试
+
+如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
+
+```bash
+bin/spc build mysqlnd,pdo_mysql --build-all --debug
+```
+
+## 命令 extract - 手动解压某个库
+
+使用命令 `bin/spc extract` 可以解包和拷贝编译需要的源代码，包括 php-src 以及依赖的各种库的源码（需要自己指定要解包的库名）。
+
+例如，我们在下载好资源后，想分布执行构建流程，手动解包和拷贝包到指定位置，可以使用命令。
+
+```bash
+# 解压 php-src 和 libxml2 的下载压缩包，解压的源码存放在 source 目录
+bin/spc extract php-src,libxml2
+```
+
+## 命令 dump-extensions - 导出项目扩展依赖
+
+使用命令 `bin/spc dump-extensions` 可以导出当前项目的扩展依赖。
+
+```bash
+# 打印项目的扩展列表，传入项目包含composer.json的根目录
+bin/spc dump-extensions /path/to/your/project/
+
+# 打印项目的扩展列表，不包含开发依赖
+bin/spc dump-extensions /path-to/tour/project/ --no-dev
+
+# 输出为 spc 命令可接受的扩展列表格式（逗号分割）
+bin/spc dump-extensions /path-to/tour/project/ --format=text
+
+# 输出为 JSON 列表
+bin/spc dump-extensions /path-to/tour/project/ --format=json
+
+# 当项目没有任何扩展时，输出指定扩展组合，而不是返回失败
+bin/spc dump-extensions /path-to/your/project/ --no-ext-output=mbstring,posix,pcntl,phar
+
+# 输出时不排除 spc 不支持的扩展
+bin/spc dump-extensions /path/to/your/project/ --no-spc-filter
+```
+
+需要注意的是，项目的目录下必须包含 `vendor/installed.json` 和 `composer.lock` 文件，否则无法正常获取。
+
+## 调试命令 dev - 调试命令集合
+
+调试命令指的是你在使用 static-php-cli 构建 PHP 或改造、增强 static-php-cli 项目本身的时候，可以辅助输出一些信息的命令集合。
+
+- `dev:extensions`: 输出目前所有支持的扩展信息，或者输出指定的扩展信息
+- `dev:php-version`: 输出当前编译的 PHP 版本（通过读取 `php_version.h` 实现）
+- `dev:sort-config`: 对 `config/` 目录下的配置文件的列表按照字母表排序
+- `dev:lib-ver <lib-name>`: 从依赖库的源码中读取版本（仅特定依赖库可用）
+- `dev:ext-ver <ext-name>`: 从扩展的源码中读取对应版本（仅特定扩展可用）
+- `dev:pack-lib <lib-name>`: 打包指定的依赖库（仅发布者可用）
+- `dev:gen-ext-docs`: 生成扩展文档（仅发布者可用）
+
+```bash
+# 输出所有扩展
+bin/spc dev:extensions
+
+# 输出指定扩展的信息
+bin/spc dev:extensions mongodb,curl,openssl
+
+# 输出指定列，可选：lib-depends, lib-suggests, ext-depends, ext-suggests, unix-only, type
+bin/spc dev:extensions --columns=lib-depends,type,ext-depends
+
+# 输出当前编译的 PHP 版本（需要先将下载好的 PHP 源码解压到 source 目录，你可以使用 `bin/spc extract php-src` 单独解压缩源码）
+bin/spc dev:php-version
+
+# 排序配置文件 ext.json（也可以排序 lib、source）
+bin/spc dev:sort-config ext
+```
+
+## 命令 install-pkg - 下载二进制包
+
+使用命令 `bin/spc install-pkg` 可以下载一些预编译或闭源的工具，并将其安装到 `pkgroot` 目录中。
+
+在 `bin/spc doctor` 自动修复 Windows 环境时会下载 nasm、perl 等工具，使用的也是 `install-pkg` 的安装过程。
+
+下面是安装工具的示例：
+
+- 下载安装 UPX（仅限 Linux 和 Windows）: `bin/spc install-pkg upx`
+- 下载安装 nasm（仅限 Windows）: `bin/spc install-pkg nasm`
+- 下载安装 go-xcaddy: `bin/spc install-pkg go-xcaddy`
+
+## 命令 del-download - 删除已下载的资源
+
+一些情况下，你需要删除单个或多个指定的下载源文件，并重新下载他们，例如切换 PHP 版本，`2.1.0-beta.4` 版本后提供了 `bin/spc del-download` 命令，可以删除指定源文件。
+
+删除已下载的源文件包含预编译的包以及源代码，名称是 `source.json` 或 `pkg.json` 中的键名。下面是一些例子：
+
+- 删除 PHP 8.2 源码并切换下载为 8.3 版本: `bin/spc del-download php-src && bin/spc download php-src --with-php=8.3`
+- 删除 redis 扩展的下载文件: `bin/spc del-download redis`
+- 删除下载好的 musl-toolchain x86_64: `bin/spc del-download musl-toolchain-x86_64-linux`
+
+## 注入外部脚本
+
+注入外部脚本指的是在 static-php-cli 编译过程中插入一个或多个脚本，用于更灵活地支持不同环境下的参数修改、源代码补丁。
+
+一般情况下，该功能主要解决使用 `spc` 二进制进行编译时无法通过修改 static-php-cli 代码来实现修改补丁的功能。
+还有一种情况：你的项目直接依赖了 `crazywhalecc/static-php-cli` 仓库并同步，但因为项目特性需要做出一些专有的修改，而这些特性并不适合合并到主分支。
+
+鉴于以上情况，在 2.0.1 正式版本中，static-php-cli 加入了多个事件的触发点，你可以通过编写外部的 `xx.php` 脚本，并通过命令行参数 `-P` 传入并执行。
+
+在编写注入外部脚本时，你一定会用到的方法是 `builder()` 和 `patch_point()`。其中，`patch_point()` 获取的是当前正在执行的事件名称，`builder()` 获取的是 BuilderBase 对象。
+
+因为传入的注入点不区分事件，所以你必须将你要执行的代码写在 `if(patch_point() === 'your_event_name')` 中，否则会重复在其他事件中执行。
+
+下面是支持的 patch_point 事件名称及对应位置：
+
+| 事件名称                         | 事件描述                                                      |
+|------------------------------|-----------------------------------------------------------|
+| before-libs-extract          | 在编译的依赖库解压前触发                                              |
+| after-libs-extract           | 在编译的依赖库解压后触发                                              |
+| before-php-extract           | 在 PHP 源码解压前触发                                             |
+| after-php-extract            | 在 PHP 源码解压后触发                                             |
+| before-micro-extract         | 在 phpmicro 解压前触发                                          |
+| after-micro-extract          | 在 phpmicro 解压后触发                                          |
+| before-exts-extract          | 在要编译的扩展解压到 PHP 源码目录前触发                                    |
+| after-exts-extract           | 在要编译的扩展解压到 PHP 源码目录后触发                                    |
+| before-library[*name*]-build | 在名称为 `name` 的库编译前触发（如 `before-library[postgresql]-build`） |
+| after-library[*name*]-build  | 在名称为 `name` 的库编译后触发                                       |
+| after-shared-ext[*name*]-build | 在名称为 `name` 的共享扩展编译后触发（如 `after-shared-ext[redis]-build`）   |
+| before-shared-ext[*name*]-build | 在名称为 `name` 的共享扩展编译前触发                                    |
+| before-php-buildconf         | 在编译 PHP 命令 `./buildconf` 前触发                              |
+| before-php-configure         | 在编译 PHP 命令 `./configure` 前触发                              |
+| before-php-make              | 在编译 PHP 命令 `make` 前触发                                     |
+| before-sanity-check          | 在编译 PHP 后，运行扩展检查前触发                                       |
+
+下面是一个简单的临时修改 PHP 源码的例子，开启 CLI 下在当前工作目录查找 `php.ini` 配置的功能：
+
+```php
+// a.php
+<?php
+if (patch_point() === 'before-php-buildconf') {
+    // replace php source code
+    \SPC\store\FileSystem::replaceFileStr(
+        SOURCE_PATH . '/php-src/sapi/cli/php_cli.c',
+        'sapi_module->php_ini_ignore_cwd = 1;',
+        'sapi_module->php_ini_ignore_cwd = 0;'
+    );
+}
+```
+
+```bash
+bin/spc build mbstring --build-cli -P a.php
+echo 'memory_limit=8G' > ./php.ini
+```
+
+```
+$ buildroot/bin/php -i | grep Loaded
+Loaded Configuration File => /Users/jerry/project/git-project/static-php-cli/php.ini
+
+$ buildroot/bin/php -i | grep memory
+memory_limit => 8G => 8G
+```
+
+对于 static-php-cli 支持的对象、方法及接口，可以阅读源码，大部分的方法和对象都有相应的注释。
+
+一般使用 `-P` 功能常用的对象及函数有：
+
+- `SPC\store\FileSystem`: 文件管理类
+  - `::replaceFileStr(string $filename, string $search, $replace)`: 替换文件字符串内容
+  - `::replaceFileStr(string $filename, string $pattern, $replace)`: 正则替换文件内容
+  - `::replaceFileUser(string $filename, $callback)`: 用户自定义函数替换文件内容
+  - `::copyDir(string $from, string $to)`: 递归拷贝某个目录到另一个位置
+  - `::convertPath(string $path)`: 转换路径的分隔符为当前系统分隔符
+  - `::scanDirFiles(string $dir, bool $recursive = true, bool|string $relative = false, bool $include_dir = false)`: 遍历目录文件
+- `SPC\builder\BuilderBase`: 构建对象
+  - `->getPatchPoint()`: 获取当前的注入点名称
+  - `->getOption(string $key, $default = null)`: 获取命令行和编译时的选项
+  - `->getPHPVersionID()`: 获取当前编译的 PHP 版本 ID
+  - `->getPHPVersion()`: 获取当前编译的 PHP 版本号
+  - `->setOption(string $key, $value)`: 设定选项
+  - `->setOptionIfNotExists(string $key, $value)`: 如果选项不存在则设定选项
+
+::: tip
+static-php-cli 开放的方法非常多，文档中无法一一列举，但只要是 `public function` 并且不被标注为 `@internal`，均可调用。
+:::
+
+## 多次构建
+
+如果你在本地要多次构建，以下方法可以为你节省下载资源、编译的时间。
+
+- 仅切换 PHP 版本，不更换依赖库版本时，可以使用 `bin/spc switch-php-version` 快速切换 PHP 版本，然后重新运行同样的 `build` 命令。
+- 如果你想重新构建一次，但不重新下载源码，可以先 `rm -rf buildroot source` 删除编译目录和源码目录，然后重新构建。
+- 如果你想更新某个依赖的版本，可以使用 `bin/spc del-download <source-name>` 删除指定的源码，然后使用 `download <source-name>` 重新下载。
+- 如果你想更新所有依赖的版本，可以使用 `bin/spc download --clean` 删除所有下载的源码，然后重新下载。
+
+## embed 使用
+
+如果你想将 static-php 嵌入到其他 C 语言程序中，可以使用 `--build-embed` 构建一个 embed 版本的 PHP。
+
+```bash
+bin/spc build {your extensions} --build-embed --debug
+```
+
+在通常的情况下，PHP embed 编译后会生成 `php-config`。对于 static-php，我们提供了 `spc-config`，用于获取编译时的参数。
+另外，在使用 embed SAPI（libphp.a）时，你需要使用和编译 libphp 相同的编译器，否则会出现链接错误。
+
+下面是 spc-config 的基本用法：
+
+```bash
+# output all flags and options
+bin/spc spc-config curl,zlib,phar,openssl
+
+# output libs
+bin/spc spc-config curl,zlib,phar,openssl --libs
+
+# output includes
+bin/spc spc-config curl,zlib,phar,openssl --includes
+```
+
+默认情况下，static-php 在不同系统使用的编译器分别是：
+
+- macOS: `clang`
+- Linux (Alpine Linux): `gcc`
+- Linux (glibc based distros, x86_64): `/usr/local/musl/bin/x86_64-linux-musl-gcc`
+- Linux (glibc based distros, aarch64): `/usr/local/musl/bin/aarch64-linux-musl-gcc`
+- FreeBSD: `clang`
+
+下面是一个使用 embed SAPI 的例子：
+
+```c
+// embed.c
+#include <sapi/embed/php_embed.h>
+
+int main(int argc,char **argv){
+
+    PHP_EMBED_START_BLOCK(argc,argv)
+
+    zend_file_handle file_handle;
+
+    zend_stream_init_filename(&file_handle,"embed.php");
+
+    if(php_execute_script(&file_handle) == FAILURE){
+        php_printf("Failed to execute PHP script.\n");
+    }
+
+    PHP_EMBED_END_BLOCK()
+    return 0;
+}
+```
+
+
+```php
+<?php 
+// embed.php
+echo "Hello world!\n";
+```
+
+```bash
+# compile in debian/ubuntu x86_64
+/usr/local/musl/bin/x86_64-linux-musl-gcc embed.c $(bin/spc spc-config bcmath,zlib) -static -o embed
+# compile in macOS/FreeBSD
+clang embed.c $(bin/spc spc-config bcmath,zlib) -o embed
+
+./embed
+# out: Hello world!
+```

docs/zh/guide/troubleshooting.md

@@ -0,0 +1,31 @@
+# 故障排除
+
+使用 static-php-cli 过程中可能会碰到各种各样的故障，这里将讲述如何自行查看错误并反馈 Issue。
+
+## 下载失败问题
+
+下载资源问题是 spc 最常见的问题之一。主要是由于 spc 下载资源使用的地址一般均为对应项目的官方网站或 GitHub 等，而这些网站可能偶尔会宕机、屏蔽 IP 地址。
+在遇到下载失败后，可以多次尝试调用下载命令。
+
+当下载资源时，你可能最终会看到类似 `curl: (56) The requested URL returned error: 403` 的错误，这通常是由于 GitHub 限制导致的。
+你可以通过在命令中添加 `--debug` 来验证，会看到类似 `[DEBU] Running command (no output) : curl -sfSL   "https://api.github.com/repos/openssl/openssl/releases"` 的输出。
+
+要解决这个问题，可以在 GitHub 上 [创建](https://github.com/settings/tokens) 一个个人访问令牌，并将其设置为环境变量 `GITHUB_TOKEN=<XXX>`。
+
+如果确认地址确实无法正常访问，可以提交 Issue 或 PR 更新地址或下载类型。
+
+## Doctor 无法修复某些问题
+
+在绝大部分情况下，doctor 模块都可以对缺失的系统环境进行自动修复和安装，但也存在特殊的环境无法正常使用自动修复功能。
+
+由于系统限制（例如，Windows 下无法自动安装 Visual Studio 等软件），自动修复功能无法用于某些项目。
+在遇到无法自动修复功能时，如果遇到 `Some check items can not be fixed` 字样，则表明无法自动修复。
+请根据终端显示的方法提交 Issue 或自行修复环境。
+
+## 编译错误
+
+遇到编译错误时，如果没有开启 `--debug` 日志，请先开启调试日志，然后确定报错的命令。
+报错的终端输出对于修复编译错误非常重要。
+在提交 Issue 时，请上传终端日志的最后报错片段（或整个终端日志输出），并且包含使用的 `spc` 命令和参数。
+
+如果你是重复构建，请参考 [本地构建 - 多次构建](./manual-build#多次构建) 章节。

docs/zh/index.md

@@ -0,0 +1,142 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Static PHP"
+  tagline: "在 Linux、macOS、FreeBSD、Windows 上与 PHP 项目一起构建独立的 PHP 二进制文件，并包含流行的扩展。"
+  image:
+    src: /images/static-php_nobg.png
+    alt: Static PHP CLI Logo
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: ./guide/
+
+features:
+  - title: 静态 CLI 二进制
+    details: 您可以轻松地编译一个独立的 PHP 二进制文件以供通用使用，包括 CLI、FPM SAPI。
+  - title: Micro 自解压可执行文件
+    details: 您可以编译一个自解压的可执行文件，并将 PHP 源代码与二进制文件打包在一起。
+  - title: 依赖管理
+    details: static-php-cli 附带依赖项管理，支持安装不同类型的 PHP 扩展。
+---
+
+<script setup>
+import {VPSponsors} from "vitepress/theme";
+import Contributors from '../.vitepress/components/Contributors.vue';
+
+const sponsors = [
+  { name: 'Beyond Code', img: '/images/beyondcode-seeklogo.png', url: 'https://beyondco.de/' },
+  { name: 'NativePHP', img: '/images/nativephp-logo.svg', url: 'https://nativephp.com/' },
+];
+</script>
+
+<div class="sponsors-section">
+  <div class="sponsors-header">
+    <h2>特别赞助商</h2>
+    <p class="sponsors-description">
+      感谢我们出色的赞助商对本项目的支持！
+    </p>
+  </div>
+  <VPSponsors :data="sponsors"/>
+</div>
+
+<style scoped>
+.sponsors-section {
+  margin: 48px auto;
+  padding: 32px 24px;
+  max-width: 1152px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-bg) 100%);
+  border-radius: 16px;
+  border: 1px solid var(--vp-c-divider);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
+  transition: all 0.3s ease;
+}
+
+.sponsors-section:hover {
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.1);
+  transform: translateY(-2px);
+}
+
+.sponsors-header {
+  text-align: center;
+  margin-bottom: 24px;
+}
+
+.sponsors-header h2 {
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin: 0 0 8px 0;
+  background: linear-gradient(120deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.sponsors-description {
+  font-size: 0.95rem;
+  color: var(--vp-c-text-2);
+  margin: 0;
+  line-height: 1.5;
+}
+
+@media (max-width: 768px) {
+  .sponsors-section {
+    margin: 32px 16px;
+    padding: 24px 16px;
+  }
+  
+  .sponsors-header h2 {
+    font-size: 1.25rem;
+  }
+  
+  .sponsors-description {
+    font-size: 0.9rem;
+  }
+}
+
+/* Hero logo styling */
+:deep(.VPImage.image-src) {
+  border-radius: 20px;
+  background: linear-gradient(135deg, var(--vp-c-bg-soft) 0%, var(--vp-c-default-soft) 100%);
+  padding: 40px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+  transition: all 0.3s ease;
+}
+
+:deep(.VPImage.image-src:hover) {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15);
+}
+
+/* Dark mode adjustments for logo */
+.dark :deep(.VPImage.image-src) {
+  background: linear-gradient(135deg, rgba(255, 255, 255, 0.05) 0%, rgba(255, 255, 255, 0.02) 100%);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
+  opacity: 0.9;
+}
+
+.dark :deep(.VPImage.image-src:hover) {
+  opacity: 1;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.7);
+}
+
+/* Additional styling for the logo image itself */
+:deep(.VPImage.image-src img) {
+  max-height: 280px;
+  width: auto;
+}
+
+@media (max-width: 768px) {
+  :deep(.VPImage.image-src) {
+    padding: 24px;
+  }
+  
+  :deep(.VPImage.image-src img) {
+    max-height: 200px;
+  }
+}
+</style>
+
+<Contributors />

package.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "vitepress": "^2.0.0-alpha.5",
+    "vue": "^3.2.47"
+  }
+}

phpstan.neon

@@ -4,15 +4,16 @@ parameters:
   paths:
     - ./src/
   ignoreErrors:
-    - '#Constant .* not found#'
     - '#Unsafe usage of new static#'
     - '#class Fiber#'
     - '#Attribute class JetBrains\\PhpStorm\\ArrayShape does not exist#'
     - '#Function Swoole\\Coroutine\\run not found.#'
+    - '#Static call to instance method ZM\\Logger\\ConsoleColor#'
+    - '#Constant GNU_ARCH not found#'
   dynamicConstantNames:
     - PHP_OS_FAMILY
   excludePaths:
       analyseAndScan:
-            - ./src/globals/tests/swoole.php
-            - ./src/globals/tests/swoole.phpt
-            - ./src/globals/test-extensions.php
+            - ./src/globals/ext-tests/swoole.php
+            - ./src/globals/ext-tests/swoole.phpt
+            - ./src/globals/test-extensions.php

phpunit.xml.dist

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpunit
+        bootstrap="tests/bootstrap.php"
+>
+    <php>
+        <env name="SPC_IGNORE_BAD_HASH" value="yes" force="true" />
+        <env name="SPC_SKIP_TOOLCHAIN_CHECK" value="yes" force="true" />
+    </php>
+</phpunit>

src/SPC/ConsoleApplication.php

@@ -4,37 +4,51 @@ declare(strict_types=1);
 
 namespace SPC;
 
-use SPC\command\BuildCliCommand;
 use SPC\command\BuildLibsCommand;
+use SPC\command\BuildPHPCommand;
+use SPC\command\CraftCommand;
 use SPC\command\DeleteDownloadCommand;
 use SPC\command\dev\AllExtCommand;
+use SPC\command\dev\EnvCommand;
+use SPC\command\dev\ExtVerCommand;
+use SPC\command\dev\GenerateExtDepDocsCommand;
+use SPC\command\dev\GenerateExtDocCommand;
+use SPC\command\dev\GenerateLibDepDocsCommand;
+use SPC\command\dev\LibVerCommand;
+use SPC\command\dev\PackLibCommand;
 use SPC\command\dev\PhpVerCommand;
 use SPC\command\dev\SortConfigCommand;
 use SPC\command\DoctorCommand;
 use SPC\command\DownloadCommand;
+use SPC\command\DumpExtensionsCommand;
 use SPC\command\DumpLicenseCommand;
 use SPC\command\ExtractCommand;
 use SPC\command\InstallPkgCommand;
 use SPC\command\MicroCombineCommand;
+use SPC\command\SPCConfigCommand;
+use SPC\command\SwitchPhpVersionCommand;
 use Symfony\Component\Console\Application;
-use Symfony\Component\Console\Command\HelpCommand;
-use Symfony\Component\Console\Command\ListCommand;
 
 /**
  * static-php-cli console app entry
  */
 final class ConsoleApplication extends Application
 {
-    public const VERSION = '2.1.7';
+    public const string VERSION = '2.8.4';
 
     public function __construct()
     {
         parent::__construct('static-php-cli', self::VERSION);
 
+        // Define internal env vars and constants
+        require_once ROOT_DIR . '/src/globals/internal-env.php';
+
         $this->addCommands(
             [
+                // Craft command
+                new CraftCommand(),
                 // Common commands
-                new BuildCliCommand(),
+                new BuildPHPCommand(),
                 new BuildLibsCommand(),
                 new DoctorCommand(),
                 new DownloadCommand(),
@@ -43,17 +57,22 @@ final class ConsoleApplication extends Application
                 new DumpLicenseCommand(),
                 new ExtractCommand(),
                 new MicroCombineCommand(),
+                new SwitchPhpVersionCommand(),
+                new SPCConfigCommand(),
+                new DumpExtensionsCommand(),
 
                 // Dev commands
                 new AllExtCommand(),
                 new PhpVerCommand(),
+                new LibVerCommand(),
+                new ExtVerCommand(),
                 new SortConfigCommand(),
+                new GenerateExtDocCommand(),
+                new GenerateExtDepDocsCommand(),
+                new GenerateLibDepDocsCommand(),
+                new PackLibCommand(),
+                new EnvCommand(),
             ]
         );
     }
-
-    protected function getDefaultCommands(): array
-    {
-        return [new HelpCommand(), new ListCommand()];
-    }
 }