frankenphp/CONTRIBUTING.md

Contributing

Compiling PHP

With Docker (Linux)

Build the dev Docker image:

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

The image contains the usual development tools (Go, GDB, Valgrind, Neovim...).
If docker version is lower than 23.0, build is failed by dockerignore pattern issue. Add directories to .dockerignore.

 !testdata/*.php
 !testdata/*.txt
+!caddy
+!C-Thread-Pool
+!internal

Without Docker (Linux and macOS)

Follow the instructions to compile from sources and pass the --debug configuration flag.

Running the test suite

go test -race -v ./...

Caddy module

Build Caddy with the FrankenPHP Caddy module:

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

Run the Caddy with the FrankenPHP Caddy module:

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

The server is listening on 127.0.0.1:8080:

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

Minimal test server

Build the minimal test server:

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

Run the test server:

cd testdata/
../internal/testserver/testserver

The server is listening on 127.0.0.1:8080:

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

Building Docker Images Locally

Print bake plan:

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

Build FrankenPHP images for amd64 locally:

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

Build FrankenPHP images for arm64 locally:

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

Build FrankenPHP images from scratch for arm64 & amd64 and push to Docker Hub:

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

Debugging Segmentation Faults in GitHub Actions

1. Open .github/workflows/tests.yml
2. Enable PHP debug symbols

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

3. Enable tmate to connect to the container

       - name: Set include 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
   +     env:
   +       GOFLAGS: "-w -gcflags=all=-N -gcflags=all=-l"
   

4. Open frankenphp.go
5. Enable cgosymbolizer

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

6. Download the module: go get
7. In the container, you can use GDB and the like:

   sudo apt install gdb
   mkdir -p /home/runner/.config/gdb/
   go test -c -ldflags=-w
   gdb --args ./frankenphp.test -test.run ^MyTest$
   

8. When the bug is fixed, revert all these changes

Misc Dev Resources

• PHP embedding in uWSGI
• PHP embedding in NGINX Unit
• PHP embedding in Go (go-php)
• PHP embedding in Go (GoEmPHP)
• PHP embedding in C++
• Extending and Embedding PHP by Sara Golemon
• What the heck is TSRMLS_CC, anyway?
• PHP embedding on Mac
• SDL bindings

Docker-Related Resources

• Bake file definition
• docker buildx build

Useful Command

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