Configurazione

File di configurazione, variabili d’ambiente (.env), accesso ai valori di configurazione, cache, modalità debug e modalità manutenzione di Laravel.

​

Introduzione

Tutti i file di configurazione del framework Laravel sono nella directory config/. Ogni opzione ha un commento: apri i file per prendere confidenza con le opzioni disponibili.

Nei file di configurazione gestisci diversi valori centrali: informazioni di connessione al database, informazioni del server mail, URL dell’applicazione, chiavi di cifratura e altro.

​

Il comando about

Con il comando Artisan about puoi controllare una panoramica di configurazione, driver e ambiente dell’applicazione.

php artisan about

Se vuoi controllare solo una sezione specifica usa l’opzione --only.

php artisan about --only=environment

Per controllare in dettaglio i valori di un file di configurazione specifico, è utile il comando config:show.

php artisan config:show database

​

Configurazione dell’ambiente (.env)

Spesso vuoi cambiare i valori di configurazione in base all’ambiente di esecuzione. Ad esempio, potresti voler usare driver di cache diversi in locale e in produzione.

Per semplificare, Laravel usa la libreria PHP DotEnv. All’installazione, nella root dell’applicazione trovi il file .env.example con le variabili d’ambiente più comuni; durante l’installazione viene copiato automaticamente in .env.

Quando sviluppi in team è comodo aggiornare .env.example e includerlo nel repository. Con valori segnaposto è chiaro a tutti quali variabili d’ambiente sono richieste.

​

Sicurezza del file di ambiente

Non fare il commit del file .env nel controllo di versione. Le impostazioni devono variare per sviluppatore e per server, e includerlo nel repository comporta il rischio di divulgare informazioni sensibili in caso di incidente.

Laravel include comunque una funzionalità per cifrare il file di ambiente: in forma cifrata puoi salvarlo in modo sicuro nel controllo di versione.

​

File di ambiente aggiuntivi

All’avvio dell’applicazione, Laravel verifica se sono impostate la variabile d’ambiente APP_ENV o l’argomento CLI --env. Se specificato e se esiste un file .env.[APP_ENV], viene caricato quello. Altrimenti viene usato il file .env predefinito.

​

Tipi delle variabili d’ambiente

Tutte le variabili nel file .env vengono interpretate come stringhe, ma per consentire alla funzione env() di restituire tipi più vari sono previsti i seguenti valori speciali.

Valore in .env	Valore restituito da env()
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

Per impostare valori che contengono spazi, racchiudili tra doppi apici.

APP_NAME="My Application"

​

Lettura delle variabili d’ambiente

Tutte le variabili scritte nel file .env vengono caricate nella superglobal PHP $_ENV all’arrivo di una richiesta. All’interno dei file di configurazione puoi leggerne i valori con la funzione env().

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

Il secondo argomento è il valore predefinito, restituito se quella variabile non esiste.

​

Verifica dell’ambiente corrente

L’ambiente corrente è determinato dalla variabile APP_ENV del file .env. Puoi ottenerlo con il metodo environment della facade App.

use Illuminate\Support\Facades\App;

$environment = App::environment();

Puoi anche passare un argomento per verificare se sei in un ambiente specifico.

if (App::environment('local')) {
    // Ambiente locale
}

if (App::environment(['local', 'staging'])) {
    // Ambiente locale o di staging
}

​

Cifratura del file di ambiente

I file di ambiente non cifrati non andrebbero salvati nel controllo di versione, ma Laravel offre la funzionalità di cifrarli.

php artisan env:encrypt

Eseguendolo, .env viene cifrato e il contenuto cifrato salvato nel file .env.encrypted. La chiave di decifratura viene mostrata nell’output del comando: conservala in un password manager sicuro.

Per decifrare usa il comando env:decrypt.

php artisan env:decrypt

​

Accesso ai valori di configurazione

Puoi accedere ai valori di configurazione da qualunque punto dell’applicazione tramite la facade Config o la funzione globale config(). Usa la “notazione dot” per combinare nome del file e nome dell’opzione.

use Illuminate\Support\Facades\Config;

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

// Puoi anche recuperarlo con la funzione globale
$value = config('app.timezone');

// Specifica un valore predefinito se non esiste
$value = config('app.timezone', 'Europe/Rome');

Per modificare i valori a runtime usa Config::set() oppure passa un array a config().

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

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

Sono disponibili anche metodi di recupero tipizzati che sollevano un’eccezione se il tipo non corrisponde.

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

​

Cache della configurazione

Per migliorare le prestazioni dell’applicazione, metti in cache tutti i file di configurazione in un unico file.

php artisan config:cache

Questo comando unisce tutte le opzioni di configurazione in un solo file che il framework può caricare velocemente.

Esegui il comando config:cache come parte del processo di deploy in produzione. Durante lo sviluppo locale la configurazione cambia spesso, quindi è meglio non eseguirlo.

Una volta creata la cache, il file .env non viene più letto durante le richieste del framework o l’esecuzione dei comandi Artisan. Di conseguenza env() restituirà solo le variabili d’ambiente di sistema.

Per questo motivo, chiama la funzione env() esclusivamente all’interno dei file di configurazione della directory config/. Altrove nell’applicazione usa config() per recuperare i valori.

Per rimuovere la cache usa il comando config:clear.

php artisan config:clear

​

Pubblicare i file di configurazione

Molti file di configurazione di Laravel sono già pubblicati nella directory config/, ma alcuni file come cors.php o view.php non lo sono per impostazione predefinita.

Per pubblicare i file di configurazione non pubblicati usa il comando config:publish.

php artisan config:publish

php artisan config:publish --all

​

Modalità debug

L’opzione debug in config/app.php determina quanto vengono mostrate all’utente le informazioni di errore. Questa opzione segue di default il valore della variabile d’ambiente APP_DEBUG nel file .env.

In produzione imposta sempre APP_DEBUG a false. Se resta true, rischi di esporre agli utenti finali informazioni di configurazione sensibili dell’applicazione.

# Sviluppo locale
APP_DEBUG=true

# Produzione
APP_DEBUG=false

​

Modalità manutenzione

Quando l’applicazione è in modalità manutenzione, viene mostrata una vista personalizzata per tutte le richieste. Questo ti permette di “disabilitare” temporaneamente l’applicazione durante aggiornamenti o interventi di manutenzione.

​

Attivare la modalità manutenzione

php artisan down

Con l’opzione --refresh il browser si ricarica automaticamente dopo il numero di secondi indicato.

php artisan down --refresh=15

L’opzione --retry viene impostata come valore dell’header HTTP Retry-After.

php artisan down --retry=60

​

Bypass della modalità manutenzione

Per permettere l’accesso solo ad alcuni utenti tramite un token segreto usa l’opzione --secret.

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

Con l’opzione --with-secret Laravel genera automaticamente il token.

php artisan down --with-secret

​

Modalità manutenzione su più server

Di default Laravel gestisce la modalità manutenzione su file. In configurazioni con più server è comodo il metodo basato sulla cache.

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

​

Pre-rendering della vista di manutenzione

Se esegui php artisan down durante il deploy, gli utenti che accedono mentre le dipendenze si aggiornano potrebbero vedere un errore. Per evitarlo, pre-renderizza la vista con l’opzione --render.

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

Puoi anche reindirizzare tutte le richieste a un URL specifico durante la modalità manutenzione.

php artisan down --redirect=/

​

Disattivare la modalità manutenzione

php artisan up

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

Se vuoi eliminare completamente il downtime, valuta una piattaforma completamente gestita come Laravel Cloud.

​

Prossimi passi

Routing

Impara le basi del routing per collegare URL e controller.