frankenphp/docs/cn/CONTRIBUTING.md

贡献

编译 PHP

使用 Docker (Linux)

构建开发环境 Docker 镜像：

docker build -t frankenphp-dev -f dev.Dockerfile .
docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 8080:8080 -p 443:443 -p 443:443/udp -v $PWD:/go/src/app -it frankenphp-dev

该镜像包含常用的开发工具（Go、GDB、Valgrind、Neovim等）。

如果 docker 版本低于 23.0，则会因为 dockerignore pattern issue 而导致构建失败。将目录添加到 .dockerignore。

 !testdata/*.php
 !testdata/*.txt
+!caddy
+!internal

不使用 Docker (Linux 和 macOS)

按照说明从源代码编译 并传递 --debug 配置标志。

运行测试套件

go test -tags watcher -race -v ./...

Caddy 模块

使用 FrankenPHP Caddy 模块构建 Caddy：

cd caddy/frankenphp/
go build
cd ../../

使用 FrankenPHP Caddy 模块运行 Caddy：

cd testdata/
../caddy/frankenphp/frankenphp run

服务器正在监听 127.0.0.1:8080：

curl -vk https://localhost/phpinfo.php

最小测试服务器

构建最小测试服务器：

cd internal/testserver/
go build
cd ../../

运行测试服务器：

cd testdata/
../internal/testserver/testserver

服务器正在监听 127.0.0.1:8080：

curl -v http://127.0.0.1:8080/phpinfo.php

本地构建 Docker 镜像

打印 bake 计划:

docker buildx bake -f docker-bake.hcl --print

本地构建 amd64 的 FrankenPHP 镜像：

docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/amd64"

本地构建 arm64 的 FrankenPHP 镜像：

docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/arm64"

从头开始为 arm64 和 amd64 构建 FrankenPHP 镜像并推送到 Docker Hub：

docker buildx bake -f docker-bake.hcl --pull --no-cache --push

使用静态构建调试分段错误

1. 从 GitHub 下载 FrankenPHP 二进制文件的调试版本或创建包含调试符号的自定义静态构建：

   docker buildx bake \
       --load \
       --set static-builder.args.DEBUG_SYMBOLS=1 \
       --set "static-builder.platform=linux/amd64" \
       static-builder
   docker cp $(docker create --name static-builder dunglas/frankenphp:static-builder):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
   

2. 将当前版本的 frankenphp 替换为 debug FrankenPHP 可执行文件

3. 照常启动 FrankenPHP（或者，你可以直接使用 GDB 启动 FrankenPHP： gdb --args frankenphp run）

4. 使用 GDB 附加到进程：

   gdb -p `pidof frankenphp`
   

5. 如有必要，请在 GDB shell 中输入 continue

6. 使 FrankenPHP 崩溃

7. 在 GDB shell 中输入 bt

8. 复制输出

在 GitHub Actions 中调试分段错误

1. 打开 .github/workflows/tests.yml

2. 启用 PHP 调试符号

       - uses: shivammathur/setup-php@v2
         # ...
         env:
           phpts: ts
   +       debug: true
   

3. 启用 tmate 以连接到容器

       -
         name: Set CGO flags
         run: echo "CGO_CFLAGS=$(php-config --includes)" >> "$GITHUB_ENV"
   +   -
   +     run: |
   +       sudo apt install gdb
   +       mkdir -p /home/runner/.config/gdb/
   +       printf "set auto-load safe-path /\nhandle SIG34 nostop noprint pass" > /home/runner/.config/gdb/gdbinit
   +   -
   +     uses: mxschmitt/action-tmate@v3
   

4. 连接到容器

5. 打开 frankenphp.go

6. 启用 cgosymbolizer

   -   //_ "github.com/ianlancetaylor/cgosymbolizer"
   +   _ "github.com/ianlancetaylor/cgosymbolizer"
   

7. 下载模块： go get

8. 在容器中，可以使用 GDB 和以下：

   go test -tags watcher -c -ldflags=-w
   gdb --args frankenphp.test -test.run ^MyTest$
   

9. 当错误修复后，恢复所有这些更改

其他开发资源

• PHP 嵌入 uWSGI
• PHP 嵌入 NGINX Unit
• PHP 嵌入 Go (go-php)
• PHP 嵌入 Go (GoEmPHP)
• PHP 嵌入 C++
• 扩展和嵌入 PHP 作者：Sara Golemon
• TSRMLS_CC到底是什么？
• Mac 上的 PHP 嵌入
• SDL 绑定

Docker 相关资源

• Bake 文件定义
• docker buildx 构建

有用的命令

apk add strace util-linux gdb
strace -e 'trace=!futex,epoll_ctl,epoll_pwait,tgkill,rt_sigreturn' -p 1

翻译文档

要将文档和网站翻译成新语言，请按照下列步骤操作：

1. 在此存储库的 docs/ 目录中创建一个以语言的 2 个字符的 ISO 代码命名的新目录
2. 将 docs/ 目录根目录中的所有 .md 文件复制到新目录中（始终使用英文版本作为翻译源，因为它始终是最新的）
3. 将 README.md 和 CONTRIBUTING.md 文件从根目录复制到新目录
4. 翻译文件的内容，但不要更改文件名，也不要翻译以 > [! 开头的字符串（这是 GitHub 的特殊标记）
5. 创建翻译的拉取请求
6. 在 站点存储库 中，复制并翻译 content/、data/ 和 i18n/ 目录中的翻译文件
7. 转换创建的 YAML 文件中的值
8. 在站点存储库上打开拉取请求