archived-frankenphp/docs/pt-br/CONTRIBUTING.md

Contribuindo

Compilando o PHP

Com Docker (Linux)

Crie a imagem Docker de desenvolvimento:

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

A imagem contém as ferramentas de desenvolvimento usuais (Go, GDB, Valgrind, Neovim...) e usa os seguintes locais de configuração do PHP:

• php.ini: /etc/frankenphp/php.ini. Um arquivo php.ini com configurações de desenvolvimento é fornecido por padrão.
• Arquivos de configuração adicionais: /etc/frankenphp/php.d/*.ini.
• Extensões PHP: /usr/lib/frankenphp/modules/.

Se a sua versão do Docker for anterior à 23.0, a compilação falhará devido ao problema de padrão do .dockerignore. Adicione diretórios ao .dockerignore.

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

Sem Docker (Linux e macOS)

Siga as instruções para compilar a partir do código-fonte e passe a flag de configuração --debug.

Executando a suite de testes

go test -race -v ./...

Módulo Caddy

Construa o Caddy com o módulo Caddy FrankenPHP:

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

Execute o Caddy com o módulo Caddy FrankenPHP:

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

O servidor está escutando em 127.0.0.1:80:

Note

Se você estiver usando o Docker, terá que vincular a porta 80 do contêiner ou executar de dentro do contêiner.

curl -vk http://127.0.0.1/phpinfo.php

Servidor de teste mínimo

Construa o servidor de teste mínimo:

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

Execute o servidor de teste:

cd testdata/
../internal/testserver/testserver

O servidor está escutando em 127.0.0.1:8080:

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

Construindo imagens Docker localmente

Imprima o plano do bake:

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

Construa imagens FrankenPHP para amd64 localmente:

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

Construa imagens FrankenPHP para arm64 localmente:

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

Construa imagens FrankenPHP do zero para arm64 e amd64 e envie para o Docker Hub:

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

Depurando falhas de segmentação com compilações estáticas

1. Baixe a versão de depuração do binário do FrankenPHP do GitHub ou crie sua própria compilação estática personalizada, incluindo símbolos de depuração:

   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. Substitua sua versão atual do frankenphp pelo executável de depuração do FrankenPHP.

3. Inicie o FrankenPHP normalmente (alternativamente, você pode iniciar o FrankenPHP diretamente com o GDB: gdb --args frankenphp run).

4. Anexe ao processo com o GDB:

   gdb -p `pidof frankenphp`
   

5. Se necessário, digite continue no shell do GDB.

6. Faça o FrankenPHP travar.

7. Digite bt no shell do GDB.

8. Copie a saída.

Depurando falhas de segmentação no GitHub Actions

1. Abra o arquivo .github/workflows/tests.yml.

2. Habilite os símbolos de depuração do PHP:

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

3. Habilite o tmate para se conectar ao contêiner:

       - 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. Conecte-se ao contêiner.

5. Abra o frankenphp.go.

6. Habilite o cgosymbolizer:

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

7. Baixe o módulo: go get.

8. No contêiner, você pode usar o GDB e similares:

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

9. Quando a falha for corrigida, reverta todas essas alterações.

Recursos diversos de desenvolvimento

• 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, por Sara Golemon
• What the heck is TSRMLS_CC, anyway?
• SDL bindings

Recursos relacionados ao Docker

• Definição do arquivo Bake
• docker buildx build

Comando útil

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

Traduzindo a documentação

Para traduzir a documentação e o site para um novo idioma, siga estes passos:

1. Crie um novo diretório com o código ISO de 2 caracteres do idioma no diretório docs/ deste repositório.
2. Copie todos os arquivos .md da raiz do diretório docs/ para o novo diretório (sempre use a versão em inglês como fonte para tradução, pois está sempre atualizada).
3. Copie os arquivos README.md e CONTRIBUTING.md do diretório raiz para o novo diretório.
4. Traduza o conteúdo dos arquivos, mas não altere os nomes dos arquivos, nem traduza strings que comecem com > [! (é uma marcação especial para o GitHub).
5. Crie um pull request com as traduções.
6. No repositório do site, copie e traduza os arquivos de tradução nos diretórios content/, data/ e i18n/.
7. Traduza os valores no arquivo YAML criado.
8. Abra um pull request no repositório do site.