frankenphp/docs/ru/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. Добавьте в .dockerignore следующие директории:

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

Без Docker (Linux и macOS)

Следуйте инструкциям по компиляции из исходников и укажите флаг конфигурации --debug.

Запуск тестов

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

Модуль Caddy

Соберите Caddy с модулем FrankenPHP:

cd caddy/frankenphp/
go build -tags watcher,brotli,nobadger,nomysql,nopgx
cd ../../

Запустите Caddy с модулем FrankenPHP:

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

Соберите образы FrankenPHP для amd64 локально:

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

Соберите образы FrankenPHP для arm64 локально:

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

Соберите образы FrankenPHP с нуля для arm64 и amd64 и отправьте их в Docker Hub:

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

Отладка ошибок сегментации с использованием статических сборок

1. Скачайте отладочную версию бинарного файла FrankenPHP с GitHub или создайте собственную статическую сборку с включённым отладочным режимом:

   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-musl dunglas/frankenphp:static-builder-musl):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
   

2. Замените текущую версию frankenphp на бинарный файл с включенным отладочным режимом.

3. Запустите FrankenPHP как обычно (или сразу запустите FrankenPHP с GDB: gdb --args frankenphp run).

4. Подключитесь к процессу через GDB:

   gdb -p `pidof frankenphp`
   

5. При необходимости введите continue в консоли GDB.

6. Вызовите сбой FrankenPHP.

7. Введите bt в консоли GDB.

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++
• Книга "Extending and Embedding PHP" Сары Големан
• Статья: Что такое TSRMLS_CC?
• SDL bindings

Docker-ресурсы

• Определение файлов bake
• Документация по команде docker buildx build

Полезные команды

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

Перевод документации

Чтобы перевести документацию и сайт на новый язык, выполните следующие шаги:

1. Создайте новую директорию с 2-буквенным ISO-кодом языка в папке docs/.
2. Скопируйте все .md файлы из корня папки docs/ в новую директорию (используйте английскую версию как основу для перевода).
3. Скопируйте файлы README.md и CONTRIBUTING.md из корневой директории в новую папку.
4. Переведите содержимое файлов, но не изменяйте имена файлов. Не переводите строки, начинающиеся с > [!, это специальная разметка GitHub.
5. Создайте Pull Request с переводом.
6. В репозитории сайта скопируйте и переведите файлы в папках content/, data/ и i18n/.
7. Переведите значения в созданных YAML-файлах.
8. Откройте Pull Request в репозитории сайта.