archived-frankenphp/docs/fr/config.md

Configuration

FrankenPHP, Caddy ainsi que les modules Mercure et Vulcain peuvent être configurés à l'aide des formats pris en charge par Caddy.

Le format le plus courant est le Caddyfile, un format texte simple et facilement lisible par les humains. Par défaut, FrankenPHP recherchera un Caddyfile dans le répertoire courant. Vous pouvez spécifier un chemin personnalisé avec l'option -c ou --config.

Un Caddyfile minimal pour servir une application PHP est présenté ci-dessous :

# Le nom d'hôte auquel répondre
localhost

# Optionnellement, le répertoire à partir duquel servir les fichiers, sinon le répertoire courant sera utilisé par défaut
#root public/
php_server

Un Caddyfile plus avancé, activant davantage de fonctionnalités et fournissant des variables d'environnement pratiques, est disponible dans le dépôt FrankenPHP et avec les images Docker.

PHP lui-même peut être configuré en utilisant un fichier php.ini.

Selon votre méthode d'installation, FrankenPHP et l'interpréteur PHP chercheront les fichiers de configuration aux emplacements décrits ci-dessous.

Docker

FrankenPHP :

• /etc/frankenphp/Caddyfile : le fichier de configuration principal
• /etc/frankenphp/Caddyfile.d/*.caddyfile : fichiers de configuration additionnels qui sont chargés automatiquement

PHP :

• php.ini : /usr/local/etc/php/php.ini (aucun php.ini n'est fourni par défaut)
• Fichiers de configuration supplémentaires : /usr/local/etc/php/conf.d/*.ini
• Extensions PHP : /usr/local/lib/php/extensions/no-debug-zts-<YYYYMMDD>/
• Vous devriez copier un modèle officiel fourni par le projet PHP :

FROM dunglas/frankenphp

# Production :
RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini

# Ou développement :
RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini

Packages RPM et Debian

FrankenPHP :

• /etc/frankenphp/Caddyfile : le fichier de configuration principal
• /etc/frankenphp/Caddyfile.d/*.caddyfile : fichiers de configuration additionnels qui sont chargés automatiquement

PHP :

• php.ini : /etc/php-zts/php.ini (un fichier php.ini avec des préréglages de production est fourni par défaut)
• fichiers de configuration supplémentaires : /etc/php-zts/conf.d/*.ini

Binaire statique

FrankenPHP :

• Dans le répertoire de travail actuel : Caddyfile

PHP :

• php.ini : Le répertoire dans lequel frankenphp run ou frankenphp php-server est exécuté, puis /etc/frankenphp/php.ini
• fichiers de configuration supplémentaires : /etc/frankenphp/php.d/*.ini
• Extensions PHP : ne peuvent pas être chargées, intégrez-les au binaire lui-même
• copiez l'un des fichiers php.ini-production ou php.ini-development fournis dans les sources de PHP.

Configuration du Caddyfile

Les directives HTTP php_server ou php peuvent être utilisées dans les blocs de site pour servir votre application PHP.

Exemple minimal :

localhost {
	# Activer la compression (optionnel)
	encode zstd br gzip
	# Exécuter les fichiers PHP dans le répertoire courant et servir les assets
	php_server
}

Vous pouvez également configurer explicitement FrankenPHP en utilisant l'option globale frankenphp :

{
	frankenphp {
		num_threads <num_threads> # Définit le nombre de threads PHP à démarrer. Par défaut : 2x le nombre de CPUs disponibles.
		max_threads <num_threads> # Limite le nombre de threads PHP supplémentaires qui peuvent être démarrés au moment de l'exécution. Valeur par défaut : num_threads. Peut être mis à 'auto'.
		max_wait_time <duration> # Définit le temps maximum pendant lequel une requête peut attendre un thread PHP libre avant d'être interrompue. Valeur par défaut : désactivé.
		max_idle_time <duration> # Définit le temps maximum pendant lequel un thread auto-dimensionné peut être inactif avant d'être désactivé. Par défaut : 5s.
		php_ini <key> <value> # Définit une directive php.ini. Peut être utilisé plusieurs fois pour définir plusieurs directives.
		worker {
			file <path> # Définit le chemin vers le script worker.
			num <num> # Définit le nombre de threads PHP à démarrer, par défaut 2x le nombre de CPUs disponibles.
			env <key> <value> # Définit une variable d'environnement supplémentaire avec la valeur donnée. Peut être spécifié plusieurs fois pour régler plusieurs variables d'environnement.
			watch <path> # Définit le chemin d'accès à surveiller pour les modifications de fichiers. Peut être spécifié plusieurs fois pour plusieurs chemins.
			name <name> # Définit le nom du worker, utilisé dans les journaux et les métriques. Par défaut : chemin absolu du fichier du worker
			max_consecutive_failures <num> # Définit le nombre maximum d'échecs consécutifs avant que le worker ne soit considéré comme défaillant, -1 signifie que le worker redémarre toujours. Par défaut : 6.
		}
	}
}

# ...

Vous pouvez également utiliser la forme courte de l'option worker en une seule ligne :

{
	frankenphp {
		worker <file> <num>
	}
}

# ...

Vous pouvez aussi définir plusieurs workers si vous servez plusieurs applications sur le même serveur :

app.example.com {
    root /path/to/app/public
	php_server {
		root /path/to/app/public # permet une meilleure mise en cache
		worker index.php <num>
	}
}

other.example.com {
    root /path/to/other/public
	php_server {
		root /path/to/other/public
		worker index.php <num>
	}
}

# ...

L'utilisation de la directive php_server est généralement ce dont vous avez besoin, mais si vous avez besoin d'un contrôle total, vous pouvez utiliser la sous-directive php. La directive php transmet toutes les entrées à PHP, au lieu de vérifier d'abord si c'est un fichier PHP ou pas. En savoir plus à ce sujet dans la documentation liée aux performances.

Utiliser la directive php_server est équivalent à cette configuration :

route {
	# Ajoute un slash final pour les requêtes de répertoire
	@canonicalPath {
		file {path}/index.php
		not path */
	}
	redir @canonicalPath {path}/ 308
	# Si le fichier demandé n'existe pas, essayer les fichiers index
	@indexFiles file {
		try_files {path} {path}/index.php index.php
		split_path .php
	}
	rewrite @indexFiles {http.matchers.file.relative}
	# FrankenPHP!
	@phpFiles path *.php
	php @phpFiles
	file_server
}

Les directives php_server et php disposent des options suivantes :

php_server [<matcher>] {
	root <directory> # Définit le dossier racine du site. Par défaut : la directive `root`.
	split_path <delim...> # Définit les sous-chaînes pour diviser l'URI en deux parties. La première sous-chaîne correspondante sera utilisée pour séparer le "path info" du chemin. La première partie est suffixée avec la sous-chaîne correspondante et sera considérée comme le nom réel de la ressource (script CGI). La seconde partie sera définie comme PATH_INFO pour utilisation par le script. Par défaut : `.php`
	resolve_root_symlink false # Désactive la résolution du répertoire `root` vers sa valeur réelle en évaluant un lien symbolique, s'il existe (activé par défaut).
	env <key> <value> # Définit une variable d'environnement supplémentaire avec la valeur donnée. Peut être spécifié plusieurs fois pour plusieurs variables d'environnement.
	file_server off # Désactive la directive file_server intégrée.
	worker { # Crée un worker spécifique à ce serveur. Peut être spécifié plusieurs fois pour plusieurs workers.
		file <path> # Définit le chemin vers le script worker, peut être relatif à la racine du php_server
		num <num> # Définit le nombre de threads PHP à démarrer, par défaut 2x le nombre de CPUs disponibles
		name <name> # Définit le nom du worker, utilisé dans les journaux et les métriques. Par défaut : chemin absolu du fichier du worker. Commence toujours par m# lorsqu'il est défini dans un bloc php_server.
		watch <path> # Définit le chemin d'accès à surveiller pour les modifications de fichiers. Peut être spécifié plusieurs fois pour plusieurs chemins.
		env <key> <value> # Définit une variable d'environnement supplémentaire avec la valeur donnée. Peut être spécifié plusieurs fois pour plusieurs variables d'environnement. Les variables d'environnement pour ce worker sont également héritées du parent php_server, mais peuvent être écrasées ici.
		match <path> # fait correspondre le worker à un modèle de chemin. Écrase try_files et ne peut être utilisé que dans la directive php_server.
	}
	worker <other_file> <num> # Peut également utiliser la forme courte comme dans le bloc frankenphp global.
}

Surveillance des modifications de fichier

Vu que les workers ne démarrent votre application qu'une seule fois et la gardent en mémoire, toute modification apportée à vos fichiers PHP ne sera pas répercutée immédiatement.

Les workers peuvent être redémarrés en cas de changement de fichier via la directive watch. Ceci est utile pour les environnements de développement.

{
	frankenphp {
		worker {
			file  /path/to/app/public/worker.php
			watch
		}
	}
}

Cette fonctionnalité est souvent utilisée en combinaison avec le rechargement à chaud.

Si le répertoire watch n'est pas précisé, il se rabattra sur ./**/*.{env,php,twig,yaml,yml}, qui surveille tous les fichiers .env, .php, .twig, .yaml et .yml dans le répertoire et les sous-répertoires où le processus FrankenPHP a été lancé. Vous pouvez également spécifier un ou plusieurs répertoires via un motif de nom de fichier shell :

{
	frankenphp {
		worker {
			file  /path/to/app/public/worker.php
			watch /path/to/app # surveille tous les fichiers dans tous les sous-répertoires de /path/to/app
			watch /path/to/app/*.php # surveille les fichiers se terminant par .php dans /path/to/app
			watch /path/to/app/**/*.php # surveille les fichiers PHP dans /path/to/app et les sous-répertoires
			watch /path/to/app/**/*.{php,twig} # surveille les fichiers PHP et Twig dans /path/to/app et les sous-répertoires
		}
	}
}

• Le motif ** signifie une surveillance récursive.
• Les répertoires peuvent également être relatifs (depuis l'endroit où le processus FrankenPHP est démarré).
• Si vous avez défini plusieurs workers, ils seront tous redémarrés lorsqu'un fichier est modifié.
• Méfiez-vous des fichiers créés au moment de l'exécution (comme les logs) car ils peuvent provoquer des redémarrages intempestifs du worker.

La surveillance des fichiers est basée sur e-dant/watcher.

Faire correspondre le Worker à un chemin

Dans les applications PHP traditionnelles, les scripts sont toujours placés dans le répertoire public. C'est également vrai pour les scripts worker, qui sont traités comme n'importe quel autre script PHP. Si vous souhaitez plutôt placer le script worker en dehors du répertoire public, vous pouvez le faire via la directive match.

La directive match est une alternative optimisée à try_files disponible uniquement à l'intérieur de php_server et php. L'exemple suivant servira toujours un fichier dans le répertoire public s'il est présent et transmettra sinon la requête au worker correspondant au modèle de chemin.

{
	frankenphp {
		php_server {
			worker {
				file /path/to/worker.php # le fichier peut être en dehors du chemin public
				match /api/* # toutes les requêtes commençant par /api/ seront traitées par ce worker
			}
		}
	}
}

Variables d'environnement

Les variables d'environnement suivantes peuvent être utilisées pour insérer des directives Caddy dans le Caddyfile sans le modifier :

• SERVER_NAME : change les adresses sur lesquelles écouter, les noms d'hôte fournis seront également utilisés pour le certificat TLS généré
• SERVER_ROOT : change le répertoire racine du site, par défaut public/
• CADDY_GLOBAL_OPTIONS : injecte des options globales
• FRANKENPHP_CONFIG : insère la configuration sous la directive frankenphp

Comme pour les SAPI FPM et CLI, les variables d'environnement sont exposées par défaut dans la superglobale $_SERVER.

La valeur S de la directive variables_order de PHP est toujours équivalente à ES, que E soit défini ailleurs dans cette directive ou non.

Configuration PHP

Pour charger des fichiers de configuration PHP supplémentaires, la variable d'environnement PHP_INI_SCAN_DIR peut être utilisée. Lorsqu'elle est définie, PHP chargera tous les fichiers avec l'extension .ini présents dans les répertoires donnés.

Vous pouvez également modifier la configuration de PHP en utilisant la directive php_ini dans le fichier Caddyfile :

{
    frankenphp {
        php_ini memory_limit 256M

        # or

        php_ini {
            memory_limit 256M
            max_execution_time 15
        }
    }
}

Désactiver HTTPS

Par défaut, FrankenPHP activera automatiquement HTTPS pour tous les noms d'hôte, y compris localhost. Si vous souhaitez désactiver HTTPS (par exemple dans un environnement de développement), vous pouvez définir la variable d'environnement SERVER_NAME à http:// ou :80 :

Alternativement, vous pouvez utiliser toutes les autres méthodes décrites dans la documentation Caddy.

Si vous souhaitez utiliser HTTPS avec l'adresse IP 127.0.0.1 au lieu du nom d'hôte localhost, veuillez lire la section problèmes connus.

Full Duplex (HTTP/1)

Lors de l'utilisation de HTTP/1.x, il peut être souhaitable d'activer le mode full-duplex pour permettre l'écriture d'une réponse avant que le corps entier n'ait été lu. (par exemple : Mercure, WebSocket, Server-Sent Events, etc.)

Il s'agit d'une configuration facultative qui doit être ajoutée aux options globales dans le Caddyfile :

{
  servers {
    enable_full_duplex
  }
}

Caution

L'activation de cette option peut entraîner un blocage (deadlock) des anciens clients HTTP/1.x qui ne supportent pas le full-duplex. Cela peut aussi être configuré en utilisant la variable d'environnement CADDY_GLOBAL_OPTIONS :

CADDY_GLOBAL_OPTIONS="servers {
  enable_full_duplex
}"

Vous trouverez plus d'informations sur ce paramètre dans la documentation Caddy.

Activer le mode Debug

Lors de l'utilisation de l'image Docker, définissez la variable d'environnement CADDY_GLOBAL_OPTIONS sur debug pour activer le mode debug :

docker run -v $PWD:/app/public \
    -e CADDY_GLOBAL_OPTIONS=debug \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Autocomplétion Shell

FrankenPHP fournit un support d'autocomplétion intégré pour Bash, Zsh, Fish et PowerShell. Cela permet l'autocomplétion de toutes les commandes (y compris les commandes personnalisées comme php-server, php-cli et extension-init) ainsi que leurs options.

Bash

Pour charger l'autocomplétion dans votre session shell actuelle :

source <(frankenphp completion bash)

Pour charger l'autocomplétion à chaque nouvelle session, exécutez :

Linux :

frankenphp completion bash > /usr/share/bash-completion/completions/frankenphp

macOS :

frankenphp completion bash > $(brew --prefix)/share/bash-completion/completions/frankenphp

Zsh

Si l'autocomplétion shell n'est pas déjà activée dans votre environnement, vous devrez l'activer. Vous pouvez exécuter la commande suivante une fois :

echo "autoload -U compinit; compinit" >> ~/.zshrc

Pour charger l'autocomplétion à chaque session, exécutez une fois :

frankenphp completion zsh > "${fpath[1]}/_frankenphp"

Vous devrez démarrer un nouveau shell pour que cette configuration prenne effet.

Fish

Pour charger l'autocomplétion dans votre session shell actuelle :

frankenphp completion fish | source

Pour charger l'autocomplétion à chaque nouvelle session, exécutez une fois :

frankenphp completion fish > ~/.config/fish/completions/frankenphp.fish

PowerShell

Pour charger l'autocomplétion dans votre session shell actuelle :

frankenphp completion powershell | Out-String | Invoke-Expression

Pour charger l'autocomplétion à chaque nouvelle session, exécutez une fois :

frankenphp completion powershell | Out-File -FilePath (Join-Path (Split-Path $PROFILE) "frankenphp.ps1")
Add-Content -Path $PROFILE -Value '. (Join-Path (Split-Path $PROFILE) "frankenphp.ps1")'

Vous devrez démarrer un nouveau shell pour que cette configuration prenne effet.

Vous devrez ensuite démarrer un nouveau shell pour que cette configuration prenne effet.