docs: Add php-src modifications & Release SPC enhancement (#494)

* docs: Add php-src modifications

* Fix release-build.yml

.github/workflows/release-build.yml

@@ -8,22 +8,32 @@ on:
       - published
   workflow_dispatch:
 
+env:
+  PHP_VERSION: 8.2
+  MICRO_VERSION: 8.2.18
+
 jobs:
   build-release-artifacts:
-    name: "Build SPC Binary"
-    runs-on: macos-14
+    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.18"
         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-13"
+            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"
@@ -36,7 +46,7 @@ jobs:
         with:
           coverage: none
           tools: composer:v2
-          php-version: "${{ matrix.php-version }}"
+          php-version: "${{ env.PHP_VERSION }}"
           ini-values: memory_limit=-1
 
       - name: "Get Composer Cache Directory"
@@ -48,9 +58,9 @@ jobs:
         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,56 +68,52 @@ 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 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 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 }}" = "macos-aarch64" ] || [ "${{ matrix.operating-system }}" = "macos-x86_64" ]; then
+          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 }}" == "macos-aarch64" ]; 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'
@@ -125,4 +131,4 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           path: spc${{ env.SUFFIX }}
-          name: spc-${{ matrix.operating-system }}${{ env.SUFFIX }}
+          name: ${{ matrix.operating-system.filename }}${{ env.SUFFIX }}

.github/workflows/tests.yml

@@ -8,6 +8,14 @@ on:
       - 'src/globals/test-extensions.php'
   pull_request:
     branches: [ "main" ]
+    paths:
+      - 'src/**'
+      - 'config/**'
+      - '.github/workflows/tests.yml'
+      - 'bin/**'
+      - 'composer.json'
+      - 'box.json'
+      - '.php-cs-fixer.php'
 
 permissions:
   contents: read

docs/.vitepress/config.ts

@@ -13,7 +13,7 @@ export default {
       themeConfig: {
         nav: [
           {text: 'Guide', link: '/en/guide/',},
-          {text: 'Developing', link: '/en/develop/'},
+          {text: 'Advanced', link: '/en/develop/'},
           {text: 'Contributing', link: '/en/contributing/'},
           {text: 'FAQ', link: '/en/faq/'},
         ],
@@ -30,7 +30,7 @@ export default {
       themeConfig: {
         nav: [
           {text: '构建指南', link: '/zh/guide/'},
-          {text: '开发指南', link: '/zh/develop/'},
+          {text: '进阶', link: '/zh/develop/'},
           {text: '贡献', link: '/zh/contributing/'},
           {text: 'FAQ', link: '/zh/faq/'},
         ],

docs/.vitepress/sidebar.en.ts

@@ -25,6 +25,7 @@ export default {
       items: [
         {text: 'Get Started', link: '/en/develop/'},
         {text: 'Project Structure', link: '/en/develop/structure'},
+        {text: 'PHP Source Modification', link: '/en/develop/php-src-changes'},
       ],
     },
     {

docs/.vitepress/sidebar.zh.ts

@@ -25,6 +25,7 @@ export default {
       items: [
         { text: '开发简介', link: '/zh/develop/' },
         { text: '项目结构简介', link: '/zh/develop/structure' },
+        {text: '对 PHP 源码的修改', link: '/zh/develop/php-src-changes'},
       ],
     },
     {

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/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`）。