Questa pagina è stata tradotta dalla community e potrebbe non essere aggiornata. Consulta la versione di riferimento (in inglese).
Questa pagina è stata tradotta dalla community e potrebbe non essere aggiornata. Consulta la versione di riferimento (in inglese).
Questa pagina è stata tradotta dalla community e potrebbe non essere aggiornata. Consulta la versione di riferimento (in inglese).
FrankenPHP, Caddy, così come i moduli Mercure e Vulcain, possono essere configurati utilizzando i formati supportati da Caddy.
Il formato più comune è Caddyfile, che è un formato di testo semplice e leggibile.
Per impostazione predefinita, FrankenPHP cercherà un Caddyfile nella directory corrente.
È possibile specificare un percorso personalizzato con l’opzione -c o --config.
Di seguito è mostrato un Caddyfile minimo per servire un’applicazione PHP:
# Il nome host a cui rispondere
localhost
# Facoltativo, la directory da cui servire i file, altrimenti sarà usata la directory corrente
#root public/
php_server
Viene fornito un Caddyfile più avanzato che abilita più funzionalità e fornisce comode variabili di ambiente nel repository FrankenPHP,
e con immagini Docker.
PHP stesso può essere configurato utilizzando un file php.ini.
A seconda del metodo di installazione, FrankenPHP e l’interprete PHP cercheranno i file di configurazione nelle posizioni descritte di seguito.
FrankenPHP:
/etc/frankenphp/Caddyfile: il file di configurazione principale/etc/frankenphp/Caddyfile.d/*.caddyfile: file di configurazione aggiuntivi che vengono caricati automaticamentePHP:
php.ini: /usr/local/etc/php/php.ini (per impostazione predefinita non è fornito php.ini)/usr/local/etc/php/conf.d/*.ini/usr/local/lib/php/extensions/no-debug-zts-<YYYYMMDD>/FROM dunglas/frankenphp
# Produzione:
RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini
# O sviluppo:
RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini
FrankenPHP:
/etc/frankenphp/Caddyfile: il file di configurazione principale/etc/frankenphp/Caddyfile.d/*.caddyfile: file di configurazione aggiuntivi che vengono caricati automaticamentePHP:
php.ini: /etc/php-zts/php.ini (per impostazione predefinita viene fornito un file php.ini con preimpostazioni di produzione)/etc/php-zts/conf.d/*.iniFrankenPHP:
CaddyfilePHP:
php.ini: la directory in cui viene eseguito frankenphp run o frankenphp php-server, quindi /etc/frankenphp/php.ini/etc/frankenphp/php.d/*.iniphp.ini-production o php.ini-development forniti nei sorgenti PHP.Le direttive HTTP php_server o php possono essere utilizzate all’interno dei blocchi del sito per servire la tua app PHP.
Esempio minimo:
localhost {
# Abilita la compressione (opzionale)
encode zstd br gzip
# Esegue i file PHP nella directory corrente e serve gli asset
php_server
}
Puoi anche configurare esplicitamente FrankenPHP utilizzando l’opzione globale frankenphp:
{
frankenphp {
num_threads <num_threads> # Imposta il numero di thread PHP da avviare per le richieste non servite da un worker, i thread worker si aggiungono a questi. Predefinito: ciò che resta di 2x il numero di CPU disponibili una volta che i worker hanno i loro thread, almeno uno.
max_threads <num_threads> # Limita il numero massimo di thread PHP che possono essere eseguiti contemporaneamente, inclusi i worker. Predefinito: i thread avviati all'avvio. Può essere impostato su 'auto'.
max_wait_time <duration> # Imposta il tempo massimo di attesa di una richiesta per un thread PHP libero prima del timeout. Predefinito: disabilitato.
max_idle_time <duration> # Imposta il tempo massimo di inattività di un thread autoscalato prima della disattivazione. Predefinito: 5s.
max_requests <num> # (sperimentale) Imposta il numero massimo di richieste gestite da un thread PHP prima del riavvio, utile per mitigare memory leak. Si applica ai thread regolari e worker. Predefinito: 0 (illimitato).
php_ini <key> <value> # Imposta una direttiva php.ini. Può essere usata più volte per impostare più direttive.
worker {
file <path> # Imposta il percorso dello script worker.
num <num> # Imposta il numero di thread PHP da avviare, predefinito: 2x il numero di CPU disponibili.
env <key> <value> # Imposta una variabile di ambiente aggiuntiva al valore specificato. Può essere specificata più volte per più variabili d'ambiente.
watch <path> # Imposta il percorso da osservare per le modifiche ai file. Può essere specificato più volte per più percorsi.
name <name> # Imposta il nome del worker, usato nei log e nelle metriche. Predefinito: percorso assoluto del file worker.
max_consecutive_failures <num> # Imposta il numero massimo di errori consecutivi prima che il worker sia considerato non sano; -1 significa che il worker verrà sempre riavviato. Predefinito: 6.
}
}
}
# ...
In alternativa, è possibile utilizzare la forma breve di una riga dell’opzione worker:
{
frankenphp {
worker <file> <num>
}
}
# ...
Puoi anche definire più worker se servi più app sullo stesso server:
app.example.com {
root /path/to/app/public
php_server {
root /path/to/app/public # per un migliore caching
worker index.php <num>
}
}
other.example.com {
root /path/to/other/public
php_server {
root /path/to/other/public
worker index.php <num>
}
}
# ...
L’uso della direttiva php_server è generalmente ciò che serve,
ma se si ha bisogno del controllo completo, si può utilizzare la direttiva php di livello inferiore.
La direttiva php passa tutti gli input a PHP, invece di verificare prima se
sia un file PHP o meno. Per ulteriori informazioni, consulta la pagina sulle prestazioni.
Una richiesta il cui percorso non contiene alcuna delle estensioni split_path riceve un 404, a meno che non sia gestita da un worker.
L’utilizzo della direttiva php_server equivale a questa configurazione:
route {
# Aggiunge lo slash finale alle richieste verso directory
@canonicalPath {
file {path}/index.php
not path */
}
redir @canonicalPath {path}/ 308
# Se il file richiesto non esiste, prova i file 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
}
Le direttive php_server e php hanno le seguenti opzioni:
php_server [<matcher>] {
root <directory> # Imposta la directory root del sito. Predefinito: direttiva `root`.
split_path <delim...> # Imposta le sottostringhe per dividere l'URI in due parti. La prima sottostringa corrispondente che termina un segmento di percorso verrà utilizzata per separare le "path info" dal percorso. La prima parte viene suffissata con la sottostringa corrispondente ed è considerata il nome effettivo della risorsa (script CGI). La seconda parte verrà impostata in PATH_INFO per l'utilizzo da parte dello script. Predefinito: `.php`
resolve_root_symlink false # Disabilita la risoluzione della directory `root` al suo valore reale tramite link simbolico, se presente (abilitato per impostazione predefinita).
name <name> # Imposta il nome per questo server, usato per attribuire worker, metriche e log. Predefinito: il primo matcher host del percorso che lo racchiude, o il primo indirizzo del listener.
env <key> <value> # Imposta una variabile di ambiente aggiuntiva al valore specificato. Può essere specificata più volte per più variabili d'ambiente.
file_server off # Disabilita la direttiva file_server integrata.
request_body_timeout <duration> # Imposta un timeout di inattività sulle letture del corpo della richiesta: un client bloccato (slow POST) viene interrotto mentre un upload costante di qualsiasi dimensione ha successo. Predefinito: 60s. Impostare su 0 per disabilitare.
worker { # Crea un worker specifico per questo server. Può essere specificato più volte per più worker.
file <path> # Imposta il percorso dello script worker; può essere relativo alla root di php_server.
num <num> # Imposta il numero di thread PHP da avviare, predefinito: 2x il numero di CPU disponibili.
name <name> # Imposta il nome per il worker, usato nei log e nelle metriche. Predefinito: percorso assoluto del file worker. Viene aggiunto un suffisso numerico se il nome è già in uso.
watch <path> # Imposta il percorso da osservare per le modifiche ai file. Può essere specificato più volte per più percorsi.
env <key> <value> # Imposta una variabile di ambiente aggiuntiva al valore specificato. Può essere specificata più volte per più variabili d'ambiente. Le variabili d'ambiente per questo worker sono ereditate anche dal parent php_server, ma possono essere sovrascritte qui.
match <path> # Associa il worker a un pattern di percorso. Sovrascrive try_files e può essere usato solo nella direttiva php_server.
}
worker <other_file> <num> # È possibile usare anche la forma breve, come nel blocco globale frankenphp.
}
Poiché i worker avviano l’applicazione solo una volta e la mantengono in memoria, eventuali modifiche ai file PHP non si rifletteranno immediatamente.
I worker possono invece essere riavviati in caso di modifiche ai file tramite la direttiva watch.
Ciò è utile per gli ambienti di sviluppo.
{
frankenphp {
worker {
file /path/to/app/public/worker.php
watch
}
}
}
Questa funzione viene spesso utilizzata in combinazione con il ricaricamento a caldo.
Se la directory watch non è specificata, tornerà a ./**/*.{env,php,twig,yaml,yml},
che controlla tutti i file .env, .php, .twig, .yaml e .yml nella directory e nelle sottodirectory
dove è stato avviato il processo FrankenPHP. Puoi invece anche specificare una o più directory tramite un
pattern di nomi di file della shell:
{
frankenphp {
worker {
file /path/to/app/public/worker.php
watch /path/to/app # osserva tutti i file in tutte le sottodirectory di /path/to/app
watch /path/to/app/*.php # osserva i file che terminano con .php in /path/to/app
watch /path/to/app/**/*.php # osserva i file PHP in /path/to/app e nelle sottodirectory
watch /path/to/app/**/*.{php,twig} # osserva i file PHP e Twig in /path/to/app e nelle sottodirectory
}
}
}
** indica il monitoraggio ricorsivoIl file watcher è basato su e-dant/watcher.
Nelle applicazioni PHP tradizionali, gli script vengono sempre inseriti nella directory pubblica.
Questo vale anche per i worker, che vengono trattati come qualsiasi altro script PHP.
Se si desidera invece inserire lo script worker all’esterno della directory pubblica, lo si può fare tramite la direttiva match.
La direttiva match è un’alternativa ottimizzata a try_files disponibile solo all’interno di php_server e php.
L’esempio seguente servirà sempre un file nella directory pubblica, se presente,
altrimenti inoltrerà la richiesta al worker che corrisponde al pattern di percorso.
{
frankenphp {
php_server {
worker {
file /path/to/worker.php # il file può trovarsi fuori dal percorso pubblico
match /api/* # ogni richiesta che inizia per /api/ sarà gestita da questo worker
}
}
}
}
FrankenPHP può riavviare automaticamente i thread PHP dopo aver gestito un determinato numero di richieste. Quando un thread raggiunge il limite, viene riavviato completamente, ripulendo tutta la memoria e lo stato. Altri thread continuano a servire le richieste durante il riavvio.
Se noti che la memoria aumenta nel tempo, la soluzione ideale è segnalare la perdita
all’estensione responsabile o al manutentore della libreria.
Ma quando la soluzione dipende da una terza parte che non controlli,
max_requests fornisce una soluzione pragmatica e, si spera, temporanea per la produzione:
{
frankenphp {
max_requests 500
}
}
Le seguenti variabili di ambiente possono essere utilizzate per inserire le direttive Caddy in Caddyfile senza modificarlo:
SERVER_NAME: modifica gli indirizzi su cui ascoltare, i nomi host forniti verranno utilizzati anche per il certificato TLS generatoSERVER_ROOT: cambia la directory principale del sito, il valore predefinito è public/CADDY_GLOBAL_OPTIONS: inietta opzioni globaliFRANKENPHP_CONFIG: inietta la configurazione nella direttiva frankenphpPer quanto riguarda le SAPI FPM e CLI, le variabili di ambiente sono esposte per impostazione predefinita nel superglobale $_SERVER.
Il valore S della direttiva PHP variables_order è sempre equivalente a ES indipendentemente dal posizionamento di E altrove in questa direttiva.
Per caricare file di configurazione PHP aggiuntivi,
è possibile utilizzare la variabile di ambiente PHP_INI_SCAN_DIR.
Quando impostato, PHP caricherà tutti i file con estensione .ini presenti nelle directory indicate.
Puoi anche modificare la configurazione PHP utilizzando la direttiva php_ini in Caddyfile:
{
frankenphp {
php_ini memory_limit 256M
# or
php_ini {
memory_limit 256M
max_execution_time 15
}
}
}
Per impostazione predefinita, FrankenPHP abiliterà automaticamente HTTPS per tutti i nomi host, incluso localhost.
Se si desidera disabilitare HTTPS (ad esempio in un ambiente di sviluppo), si può impostare la variabile di ambiente SERVER_NAME a http:// o :80:
In alternativa, è possibile utilizzare tutti gli altri metodi descritti nella documentazione Caddy.
Se si vuole utilizzare HTTPS con l’indirizzo IP 127.0.0.1 invece del nome host localhost, leggere la sezione problemi noti.
Quando si utilizza HTTP/1.x, potrebbe essere opportuno abilitare la modalità full-duplex per consentire la scrittura di una risposta prima che l’intero corpo sia stato letto (ad esempio: Mercure, WebSocket, eventi inviati dal server, ecc.).
Questa è una configurazione opt-in che deve essere aggiunta alle opzioni globali in Caddyfile:
{
servers {
enable_full_duplex
}
}
Caution
L’abilitazione di questa opzione potrebbe causare un deadlock dei vecchi client HTTP/1.x che non supportano il full-duplex. Questo può anche essere configurato utilizzando la configurazione dell’ambiente
CADDY_GLOBAL_OPTIONS:
CADDY_GLOBAL_OPTIONS="servers {
enable_full_duplex
}"
Puoi trovare ulteriori informazioni su questa impostazione nella documentazione Caddy.
Per limitare la dimensione dei body delle richieste, usa la direttiva request_body:
request_body {
max_size 10MB
}
Le richieste con un body più grande ricevono una risposta 413 Request Entity Too Large.
Se PHP legge il body prima che lo script inizi (richieste POST con un Content-Type, come form e upload di file), lo script non viene eseguito.
Se lo script legge il body direttamente, tramite php://input o request_parse_body(), la lettura genera una FrankenPHP\RequestBodyTooLargeException una volta raggiunto il limite, in modo che un body troncato non venga mai scambiato per uno completo.
Quando si utilizza l’immagine Docker, impostare la variabile di ambiente CADDY_GLOBAL_OPTIONS su debug per abilitare la modalità debug:
docker run -v $PWD:/app/public \
-e CADDY_GLOBAL_OPTIONS=debug \
-p 80:80 -p 443:443 -p 443:443/udp \
dunglas/frankenphp
FrankenPHP fornisce il supporto integrato per il completamento della shell per Bash, Zsh, Fish e PowerShell. Ciò abilita il completamento automatico per tutti i comandi (inclusi i comandi personalizzati come php-server, php-cli e extension-init) e i relativi flag.
Per caricare i completamenti nella sessione di shell corrente:
source <(frankenphp completion bash)
Per caricare i completamenti per ogni nuova sessione, eseguire:
Linux:
frankenphp completion bash > /usr/share/bash-completion/completions/frankenphp
macOS:
frankenphp completion bash > $(brew --prefix)/share/bash-completion/completions/frankenphp
Se il completamento della shell non è già abilitato nell’ambiente, sarà necessario abilitarlo. È possibile eseguire quanto segue una volta:
echo "autoload -U compinit; compinit" >> ~/.zshrc
Per caricare i completamenti per ogni sessione, eseguire una volta:
frankenphp completion zsh > "${fpath[1]}/_frankenphp"
Sarà necessario avviare una nuova shell affinché questa configurazione abbia effetto.
Per caricare i completamenti nella sessione di shell corrente:
frankenphp completion fish | source
Per caricare i completamenti per ogni nuova sessione, eseguire una volta:
frankenphp completion fish > ~/.config/fish/completions/frankenphp.fish
Per caricare i completamenti nella sessione di shell corrente:
frankenphp completion powershell | Out-String | Invoke-Expression
Per caricare i completamenti per ogni nuova sessione, eseguire una volta:
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")'
Sarà necessario avviare una nuova shell affinché questa configurazione abbia effetto.
Modifica questa pagina