frankenphp/docs/fr/CONTRIBUTING.md

Contribuer

Compiler PHP

Avec Docker (Linux)

Construisez l'image Docker de développement :

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

L'image contient les outils de développement habituels (Go, GDB, Valgrind, Neovim...) et utilise les emplacements de configuration PHP suivants

• php.ini: /etc/frankenphp/php.ini Un fichier php.ini avec des préréglages de développement est fourni par défaut.
• fichiers de configuration supplémentaires: /etc/frankenphp/php.d/*.ini
• extensions php: /usr/lib/frankenphp/modules/

Si votre version de Docker est inférieure à 23.0, la construction échouera à cause d'un problème de pattern dans .dockerignore. Ajoutez les répertoires à .dockerignore.

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

Sans Docker (Linux et macOS)

Suivez les instructions pour compiler à partir des sources et passez l'indicateur de configuration --debug.

Exécution de la suite de tests

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

Module Caddy

Construire Caddy avec le module FrankenPHP :

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

Exécuter Caddy avec le module FrankenPHP :

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

Le serveur est configuré pour écouter à l'adresse 127.0.0.1:80:

Note

Si vous utilisez Docker, vous devrez soit lier le port 80 du conteneur, soit exécuter depuis l'intérieur du conteneur.

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

Serveur de test minimal

Construire le serveur de test minimal :

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

Lancer le test serveur :

cd testdata/
../internal/testserver/testserver

Le serveur est configuré pour écouter à l'adresse 127.0.0.1:8080:

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

Construire localement les images Docker

Afficher le plan de compilation :

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

Construire localement les images FrankenPHP pour amd64 :

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

Construire localement les images FrankenPHP pour arm64 :

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

Construire à partir de zéro les images FrankenPHP pour arm64 & amd64 et les pousser sur Docker Hub :

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

Déboguer les erreurs de segmentation avec les builds statiques

1. Téléchargez la version de débogage du binaire FrankenPHP depuis GitHub ou créez votre propre build statique incluant des symboles de débogage :

   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. Remplacez votre version actuelle de frankenphp par l'exécutable de débogage de FrankenPHP.

3. Démarrez FrankenPHP comme d'habitude (alternativement, vous pouvez directement démarrer FrankenPHP avec GDB : gdb --args frankenphp run).

4. Attachez-vous au processus avec GDB :

   gdb -p `pidof frankenphp`
   

5. Si nécessaire, tapez continue dans le shell GDB

6. Faites planter FrankenPHP.

7. Tapez bt dans le shell GDB

8. Copiez la sortie

Déboguer les erreurs de segmentation dans GitHub Actions

1. Ouvrir .github/workflows/tests.yml

2. Activer les symboles de débogage de la bibliothèque PHP

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

3. Activer tmate pour se connecter au conteneur

       - 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. Se connecter au conteneur

5. Ouvrir frankenphp.go

6. Activer cgosymbolizer

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

7. Télécharger le module : go get

8. Dans le conteneur, vous pouvez utiliser GDB et similaires :

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

9. Quand le bug est corrigé, annulez tous les changements.

Ressources Diverses pour le Développement

• Intégration de PHP dans uWSGI
• Intégration de PHP dans NGINX Unit
• Intégration de PHP dans Go (go-php)
• Intégration de PHP dans Go (GoEmPHP)
• Intégration de PHP dans C++
• Extending and Embedding PHP par Sara Golemon
• Qu'est-ce que TSRMLS_CC, au juste ?
• Intégration de PHP sur Mac
• Bindings SDL

Ressources Liées à Docker

• Définition du fichier Bake
• docker buildx build

Commande utile

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

Traduire la documentation

Pour traduire la documentation et le site dans une nouvelle langue, procédez comme suit :

1. Créez un nouveau répertoire nommé avec le code ISO à 2 caractères de la langue dans le répertoire docs/ de ce dépôt
2. Copiez tous les fichiers .md à la racine du répertoire docs/ dans le nouveau répertoire (utilisez toujours la version anglaise comme source de traduction, car elle est toujours à jour).
3. Copiez les fichiers README.md et CONTRIBUTING.md du répertoire racine vers le nouveau répertoire.
4. Traduisez le contenu des fichiers, mais ne changez pas les noms de fichiers, ne traduisez pas non plus les chaînes commençant par > [! (c'est un balisage spécial pour GitHub).
5. Créez une Pull Request avec les traductions
6. Dans le référentiel du site, copiez et traduisez les fichiers de traduction dans les répertoires content/, data/ et i18n/.
7. Traduire les valeurs dans le fichier YAML créé.
8. Ouvrir une Pull Request sur le dépôt du site.