Configurazione

• Introduzione
• Configurazione dell’Ambiente
• Accesso ai Valori di Configurazione
• Cache della Configurazione
• Pubblicazione della Configurazione
• Modalità di Debug
• Modalità di Manutenzione

Introduzione

Tutti i file di configurazione del framework Laravel sono situati nella directory config. Ogni opzione è documentata, quindi sentiti libero di esplorare i file e familiarizzare con le opzioni disponibili.

Questi file di configurazione ti permettono di impostare informazioni come la connessione al database, i dettagli del server di posta, oltre a vari altri valori di configurazione principali come il fuso orario dell’applicazione e la chiave di crittografia.

Il comando about

Laravel può mostrare una panoramica della configurazione della tua applicazione, dei driver e dell’ambiente tramite il comando Artisan about.

php artisan about

Se sei interessato solo a una sezione particolare dell’output della panoramica dell’applicazione, puoi filtrare per quella sezione usando l’opzione --only:

php artisan about --only=environment

Oppure, per esplorare in dettaglio i valori di un file di configurazione specifico, puoi usare il comando Artisan config:show:

php artisan config:show database

Configurazione dell’Ambiente

Solitamente è utile avere valori di configurazione diversi in base all’ambiente in cui l’applicazione è in esecuzione. Per esempio, potresti voler usare un driver di cache diverso in locale rispetto al server di produzione.

Per semplificare questo processo, Laravel utilizza la libreria PHP DotEnv. In una nuova installazione di Laravel, la directory principale dell’applicazione conterrà un file .env.example che definisce molte variabili di ambiente comuni. Durante il processo di installazione di Laravel, questo file verrà automaticamente copiato in .env.

Il file .env predefinito di Laravel contiene alcuni valori di configurazione comuni che possono differire a seconda che l’applicazione sia in esecuzione in locale o su un server di produzione. Questi valori vengono poi letti dai file di configurazione all’interno della directory config utilizzando la funzione env di Laravel.

Se stai sviluppando in team, potresti voler continuare a includere e aggiornare il file .env.example con la tua applicazione. Inserendo valori segnaposto nel file di configurazione di esempio, gli altri sviluppatori del tuo team possono vedere chiaramente quali variabili di ambiente sono necessarie per eseguire l’applicazione.

Qualsiasi variabile nel file .env può essere sovrascritta da variabili di ambiente esterne, come quelle a livello di server o di sistema.

Sicurezza del File .env

Il tuo file .env non dovrebbe essere versionato nel codice sorgente della tua applicazione, poiché ogni sviluppatore/server che utilizza la tua applicazione potrebbe richiedere una configurazione di ambiente diversa. Inoltre, ciò rappresenterebbe un rischio per la sicurezza nel caso in cui un intruso ottenga accesso al tuo repository di controllo del codice sorgente, poiché eventuali credenziali sensibili verrebbero esposte.

Tuttavia, è possibile crittografare il tuo file di ambiente utilizzando l’environment encryption integrata di Laravel. I file di ambiente crittografati possono essere inseriti in modo sicuro nel controllo del codice sorgente.

File .env Aggiuntivi

Prima di caricare le variabili d’ambiente della tua applicazione, Laravel verifica se è stata fornita esternamente una variabile APP_ENV o se è stato specificato l’argomento CLI --env. In tal caso, Laravel cercherà di caricare un file .env.[APP_ENV] se esiste. Se non esiste, verrà caricato il file predefinito .env.

Tipi di Variabili d’Ambiente

Tutte le variabili nei tuoi file .env sono solitamente interpretate come stringhe, quindi sono stati creati alcuni valori riservati per permetterti di ottenere una gamma più ampia di tipi dalla funzione env():

Valore in .env	Valore in env()
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ”
(empty)	(string) ”
null	(null) null
(null)	(null) null

Se devi definire una variabile d’ambiente con un valore che contiene spazi, puoi farlo racchiudendo il valore tra virgolette doppie:

APP_NAME="My Application"

Recuperare la Configurazione dell’Ambiente

Tutte le variabili elencate nel file .env verranno caricate nella superglobale PHP $_ENV quando la tua applicazione riceve una richiesta. Tuttavia, puoi usare la funzione env per ottenere i valori di queste variabili nei tuoi file di configurazione. Infatti, se esamini i file di configurazione di Laravel, noterai che molte opzioni già utilizzano questa funzione:

    'debug' => env('APP_DEBUG', false),

Il secondo valore passato alla funzione env è il "valore predefinito". Questo valore verrà restituito se non esiste una variabile d’ambiente per la chiave fornita.

Determinare l’Ambiente Corrente

L’ambiente corrente dell’applicazione è determinato tramite la variabile APP_ENV presente nel file .env. Puoi accedere a questo valore tramite il metodo environment sulla facade App:

use Illuminate\Support\Facades\App;

$environment = App::environment();

Puoi anche passare argomenti al metodo environment per verificare se l’ambiente corrisponde a un determinato valore. Il metodo restituirà true se l’ambiente corrisponde a uno dei valori forniti:

if (App::environment('local')) {
    // L'ambiente è locale
}

if (App::environment(['local', 'staging'])) {
    // L'ambiente è locale oppure staging...
}

Il rilevamento dell’ambiente corrente dell’applicazione può essere sovrascritto definendo una variabile di ambiente APP_ENV a livello di server.

Crittografare i File .env

I file di ambiente non crittografati non dovrebbero mai essere memorizzati nel controllo del codice sorgente. Tuttavia, Laravel permette di crittografare i file di ambiente in modo che possano essere aggiunti in sicurezza al controllo del codice insieme al resto della tua applicazione.

Crittografia

Per crittografare un file di ambiente, puoi usare il comando env:encrypt:

php artisan env:encrypt

Eseguendo il comando env:encrypt, il tuo file .env sarà crittografato e il contenuto crittografato sarà salvato in un file .env.encrypted. La chiave di decrittazione viene mostrata nell’output del comando e dovrebbe essere conservata in un password manager sicuro. Se desideri fornire una tua chiave di crittografia, puoi usare l’opzione --key quando esegui il comando:

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

La lunghezza della chiave fornita deve corrispondere a quella richiesta dal cifrario di crittografia utilizzato. Per impostazione predefinita, Laravel utilizza il cifrario AES-256-CBC che richiede una chiave di 32 caratteri. Puoi utilizzare qualsiasi cifrario supportato dall’encrypter di Laravel passando l’opzione --cipher quando esegui il comando.

Se la tua applicazione ha più file di ambiente, come .env e .env.staging, puoi specificare quale file crittografare fornendo il nome dell’ambiente tramite l’opzione --env:

php artisan env:encrypt --env=staging

Decifratura

Per decifrare un file di ambiente, puoi usare il comando env:decrypt. Questo comando richiede una chiave di decifratura, che Laravel recupererà dalla variabile di ambiente LARAVEL_ENV_ENCRYPTION_KEY:

php artisan env:decrypt

Oppure, la chiave può essere fornita direttamente al comando tramite l’opzione --key:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Quando viene eseguito il comando env:decrypt, Laravel decifrerà il contenuto del file .env.encrypted e metterà il contenuto decifrato nel file .env.

L’opzione --cipher può essere fornita al comando env:decrypt per utilizzare un cifrario di crittografia personalizzato:

php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

Se la tua applicazione ha più file di ambiente, come .env e .env.staging, puoi specificare il file di ambiente da decifrare fornendo il nome dell’ambiente tramite l’opzione --env:

php artisan env:decrypt --env=staging

Per sovrascrivere un file di ambiente esistente, puoi fornire l’opzione --force al comando env:decrypt:

php artisan env:decrypt --force

Accesso ai Valori di Configurazione

Puoi facilmente accedere ai tuoi valori di configurazione utilizzando la facade Config o la funzione globale config da qualsiasi parte della tua applicazione. I valori di configurazione possono essere accessi usando la sintassi "dot", che include il nome del file e l’opzione che desideri accedere. È possibile specificare anche un valore predefinito che verrà restituito se l’opzione di configurazione non esiste:

use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

// Recupera un valore predefinito se il valore di configurazione non esiste...
$value = config('app.timezone', 'Asia/Seoul');

Per impostare i valori di configurazione durante l’esecuzione, puoi invocare il metodo set della facade Config oppure passare un array alla funzione config:

Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);

Per aiutare l’analisi statica, la facade Config fornisce anche metodi di recupero della configurazione tipizzati. Se il valore di configurazione recuperato non corrisponde al tipo previsto, verrà generata un’eccezione:

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');

Cache della Configurazione

Per aumentare la velocità della tua applicazione, dovresti mettere in cache tutti i file di configurazione in un unico file usando il comando Artisan config:cache. Questo unirà tutte le opzioni di configurazione della tua applicazione in un unico file che il framework può caricare rapidamente.

Di solito dovresti eseguire il comando php artisan config:cache come parte del processo di deploy in produzione. Il comando non dovrebbe essere eseguito durante lo sviluppo locale, poiché le opzioni di configurazione spesso necessitano di essere modificate durante lo sviluppo della tua applicazione.

Una volta che la configurazione è stata messa in cache, il file .env della tua applicazione non sarà caricato dal framework durante le richieste o i comandi Artisan; pertanto, la funzione env restituirà solo le variabili di ambiente esterne a livello di sistema.

Per questo motivo, dovresti assicurarti di chiamare la funzione env solo all’interno dei file di configurazione (config) della tua applicazione. Puoi vedere molti esempi di ciò esaminando i file di configurazione predefiniti di Laravel. I valori di configurazione possono essere accessi da qualsiasi parte della tua applicazione utilizzando la funzione config descritta sopra.

Il comando config:clear può essere usato per cancellare la configurazione memorizzata nella cache:

php artisan config:clear

Se esegui il comando config:cache durante il processo di deploy, dovresti assicurarti di chiamare la funzione env solo dai file di configurazione. Una volta che la configurazione è stata messa in cache, il file .env non sarà caricato; pertanto, la funzione env restituirà solo le variabili di ambiente esterne a livello di sistema.

Pubblicazione della Configurazione

La maggior parte dei file di configurazione di Laravel è già pubblicata nella directory config della tua applicazione; tuttavia, alcuni file come cors.php e view.php non sono pubblicati di default, poiché la maggior parte delle applicazioni non ha bisogno di modificarli.

Tuttavia, puoi usare il comando Artisan config:publish per pubblicare i file di configurazione non pubblicati di default:

php artisan config:publish

php artisan config:publish --all

Modalità di Debug

L’opzione debug nel file di configurazione config/app.php determina quante informazioni su un errore vengono effettivamente mostrate all’utente. Per impostazione predefinita, questa opzione rispetta il valore della variabile d’ambiente APP_DEBUG, che si trova nel tuo file .env.

Per lo sviluppo locale, dovresti impostare la variabile d’ambiente APP_DEBUG su true. Nel tuo ambiente di produzione, questo valore dovrebbe essere sempre false. Se la variabile è impostata su true in produzione, rischi di esporre valori di configurazione sensibili agli utenti finali della tua applicazione.

Modalità di Manutenzione

Quando la tua applicazione è in modalità manutenzione, verrà mostrata una view personalizzata per tutte le richieste. Questo rende facile "disabilitare" l’applicazione durante un aggiornamento o durante la manutenzione. Un controllo della modalità manutenzione è incluso nello stack di middleware predefinito per la tua applicazione. Se l’applicazione è in modalità manutenzione, verrà lanciata un’istanza di Symfony\Component\HttpKernel\Exception\HttpException con un codice di stato 503.

Per abilitare la modalità manutenzione, esegui il comando Artisan down:

php artisan down

Se desideri che l’intestazione HTTP Refresh venga inviata con tutte le risposte in modalità manutenzione, puoi fornire l’opzione refresh quando invichi il comando down. L’intestazione Refresh istruirà il browser ad aggiornare automaticamente la pagina dopo il numero di secondi specificato:

php artisan down --refresh=15

Puoi anche fornire un’opzione retry al comando down, che verrà impostata come valore dell’intestazione HTTP Retry-After, anche se generalmente i browser ignorano questa intestazione:

php artisan down --retry=60

Bypassare la Modalità di Manutenzione

Per consentire di bypassare la modalità di manutenzione utilizzando un token segreto, puoi utilizzare l’opzione secret per specificare un token di bypass della modalità di manutenzione:

php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"

Dopo aver messo l’applicazione in modalità di manutenzione, puoi navigare all’URL dell’applicazione che corrisponde a questo token e Laravel invierà un cookie di bypass della modalità di manutenzione al tuo browser:

https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515

Se desideri che Laravel generi il token segreto per te, puoi usare l’opzione with-secret. Il segreto ti verrà mostrato una volta che l’applicazione è in modalità di manutenzione:

php artisan down --with-secret

Quando accedi a questa rotta nascosta, verrai reindirizzato alla rotta / dell’applicazione. Una volta che il cookie è stato inviato al tuo browser, potrai navigare normalmente nell’applicazione come se non fosse in modalità di manutenzione.

Il tuo segreto per la modalità di manutenzione dovrebbe tipicamente essere composto da caratteri alfanumerici e, opzionalmente, trattini. Evita di utilizzare caratteri che hanno un significato speciale negli URL come ? o &.

Modalità Manutenzione su più server

Di default, Laravel verifica se la tua applicazione è in modalità manutenzione usando un sistema basato su file. Questo significa che per attivare la modalità manutenzione, il comando php artisan down deve essere eseguito su ogni server che ospita la tua applicazione.

In alternativa, Laravel offre un metodo basato su cache per gestire la modalità manutenzione. Questo metodo richiede di eseguire il comando php artisan down su un solo server. Per utilizzare questo approccio, modifica l’impostazione "driver" nel file config/app.php della tua applicazione a cache. Poi, seleziona uno store di cache accessibile da tutti i tuoi server. Questo assicura che lo stato della modalità manutenzione sia mantenuto in modo coerente su ogni server:

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

Pre-renderizzazione della Vista in Modalità Manutenzione

Se usi il comando php artisan down durante il deployment, i tuoi utenti potrebbero occasionalmente riscontrare errori se accedono all’applicazione mentre le dipendenze di Composer o altri componenti dell’infrastruttura vengono aggiornati. Questo accade perché una parte significativa del framework Laravel deve avviarsi per determinare che l’applicazione è in modalità manutenzione e per mostrare la vista in modalità manutenzione usando il motore di template.

Per questo motivo, Laravel ti permette di pre-renderizzare una vista in modalità manutenzione che verrà restituita all’inizio del ciclo di richiesta. Questa vista viene generata prima che le dipendenze dell’applicazione siano caricate. Puoi pre-renderizzare un template a tua scelta usando l’opzione render del comando down:

php artisan down --render="errors::503"

Reindirizzare le Richieste in Modalità Manutenzione

Quando Laravel è in modalità manutenzione, mostrerà la vista di manutenzione per tutti gli URL dell’applicazione a cui l’utente tenta di accedere. Se vuoi, puoi istruire Laravel a reindirizzare tutte le richieste a un URL specifico. Questo può essere fatto usando l’opzione redirect. Ad esempio, potresti voler reindirizzare tutte le richieste all’URI /:

php artisan down --redirect=/

Disabilitare la modalità manutenzione

Per disabilitare la modalità manutenzione, usa il comando up:

php artisan up

Puoi personalizzare il template predefinito della modalità manutenzione definendo il tuo template in resources/views/errors/503.blade.php.

Modalità di Manutenzione e Code

Mentre la tua applicazione è in modalità di manutenzione, nessun queued jobs verrà eseguito e gestito. I vari job continueranno a essere gestiti normalmente una volta usciti dalla modalità di manutenzione.

Alternative alla Modalità di Manutenzione

La modalità di manutenzione comporta alcuni secondi di downtime per la tua applicazione. Considera alternative come Laravel Vapor e Envoyer per realizzare un deployment senza downtime con Laravel.