[3.0] Refactor windows extensions (#1073)

Author: crazywhalecc

.github/workflows/build-unix.yml

@@ -29,6 +29,9 @@ on:
         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
@@ -42,6 +45,14 @@ on:
       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
@@ -73,6 +84,9 @@ on:
         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
@@ -86,6 +100,14 @@ on:
       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
@@ -152,8 +174,19 @@ jobs:
               RUNS_ON="macos-15"
               ;;
           esac
-          DOWN_CMD="$DOWN_CMD --with-php=${{ inputs.php-version }} --for-extensions=${{ inputs.extensions }} --ignore-cache-sources=php-src"
-          BUILD_CMD="$BUILD_CMD ${{ inputs.extensions }}"
+          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 }}"
@@ -177,6 +210,12 @@ jobs:
           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"
@@ -199,6 +238,27 @@ jobs:
         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
@@ -245,7 +305,22 @@ jobs:
           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:

.gitignore

@@ -67,3 +67,6 @@ spc.exe
 
 # dumped files from StaticPHP v3
 /dump-*.json
+
+# config parse cache
+/.spc.cache.php

TODO.md

@@ -0,0 +1,57 @@
+# v3 TODO List
+
+Tracking items identified during the v2 → v3 migration audit.
+
+---
+
+## Commands
+
+- [ ] Implement `craft` command (drives full build from `craft.yml`; should be easier with v3 vendor/registry mode)
+- [x] Migrate `micro:combine` command (combine `micro.sfx` with PHP code + INI injection)
+- [ ] Implement `dump-extensions` command (extract required extensions from `composer.json` / `composer.lock`)
+- [ ] Design and implement v3 dev toolchain commands (WIP — needs design decision):
+  - [ ] `dev:extensions` / equivalent listing command
+  - [ ] `dev:php-version`, `dev:ext-version`, `dev:lib-version`
+  - [ ] Doc generation commands (`dev:gen-ext-docs`, `dev:gen-ext-dep-docs`, `dev:gen-lib-dep-docs`) — pending v3 doc design
+
+---
+
+## Source Patches (SourcePatcher → Artifact migration)
+
+The following v2 `SourcePatcher` hooks are not yet migrated to v3 `src/Package/Artifact/` classes:
+
+- [ ] Migrate `patchSQLSRVWin32` — removes `/sdl` compile flag to prevent Zend build failure on Windows
+- [ ] Migrate `patchSQLSRVPhp85` — fixes `pdo_sqlsrv` directory layout for PHP 8.5
+- [ ] Migrate `patchYamlWin32` — patches `config.w32` `_a.lib` detection logic for the `yaml` extension
+- [ ] Migrate `patchImagickWith84` — applies PHP 8.4 compatibility patch for `imagick` based on version detection
+
+---
+
+## Extension Package Classes (Unix)
+
+Extensions that had non-trivial v2 build logic and are missing a v3 `src/Package/Extension/` class:
+
+- [x] `gettext` — macOS: fix `config.m4` bracket syntax for cross-version compatibility + append frameworks to linker flags (critical for macOS linking; this is a Unix-side gap, not Windows-only)
+
+---
+
+## Windows Extensions (Early Stage)
+
+Windows extension support is still in early stage. The following extensions had Windows-specific configure args or patches in v2 and are pending v3 Windows implementation:
+
+- [ ] `amqp` — Windows configure args
+- [ ] `com_dotnet` — Windows-only extension
+- [ ] `dom` — remove `dllmain.c` from `config.w32`
+- [ ] `ev` — fix `PHP_EV_SHARED` in `config.w32`
+- [ ] `gmssl` — add `CHECK_LIB("gmssl.lib")` to `config.w32`
+- [ ] `intl` — fix `PHP_INTL_SHARED` in `config.w32`
+- [ ] `lz4` — Windows configure args
+- [ ] `mbregex` — Windows configure args
+- [ ] `sqlsrv` / `pdo_sqlsrv` — complex conditional build logic (independent `sqlsrv` without `pdo_sqlsrv`)
+- [ ] `xml` — remove `dllmain.c` from `config.w32`; handles `soap`, `xmlreader`, `xmlwriter`, `simplexml`
+
+---
+
+## Documentation
+
+- [ ] Write v3 user documentation (currently zero v3 docs)

bin/spc-debug

@@ -1,4 +1,12 @@
 #!/usr/bin/env bash
 
+# Use SPC_XDEBUG=profile to enable Xdebug profiling mode, which will generate profiling files in /tmp.
+# Otherwise, it will enable Xdebug debugging mode, which allows you to connect a debugger to port 9003.
+if [ "$SPC_XDEBUG" = "profile" ]; then
+    XDEBUG_PREFIX="-d xdebug.mode=profile -d xdebug.start_with_request=yes -d xdebug.output_dir=/tmp -d xdebug.output_name=spc-profile.%t.%p.%r"
+else
+    XDEBUG_PREFIX="-d xdebug.mode=debug -d xdebug.client_host=127.0.0.1 -d xdebug.client_port=9003 -d xdebug.start_with_request=yes"
+fi
+
 # This script runs the 'spc' command with Xdebug enabled for debugging purposes.
-php -d xdebug.mode=debug -d xdebug.client_host=127.0.0.1 -d xdebug.client_port=9003 -d xdebug.start_with_request=yes "$(dirname "$0")/../bin/spc" "$@"
+php $XDEBUG_PREFIX "$(dirname "$0")/../bin/spc" "$@"

composer.json

@@ -49,7 +49,7 @@
     "scripts": {
         "analyse": "phpstan analyse --memory-limit 300M",
         "cs-fix": "php-cs-fixer fix",
-        "lint-config": "bin/spc dev:lint-config",
+        "lint-config": "php bin/spc dev:lint-config",
         "test": "vendor/bin/phpunit tests/ --no-coverage",
         "build:phar": "vendor/bin/box compile"
     },
@@ -63,6 +63,9 @@
         "optimize-autoloader": true,
         "sort-packages": true
     },
+    "suggest": {
+        "ext-yaml": "Speeds up YAML config file parsing"
+    },
     "funding": [
         {
             "type": "other",