Configurazione

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.

Cifratura

Per cifrare un file di ambiente usa il comando env:encrypt.

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. Se vuoi fornire una tua chiave di cifratura, usa l’opzione --key.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

La lunghezza della chiave che fornisci deve corrispondere alla lunghezza richiesta dal cifrario in uso. Di default Laravel usa il cifrario AES-256-CBC, che richiede una chiave di 32 caratteri. Puoi usare qualsiasi cifrario supportato dal componente di cifratura di Laravel passando l’opzione --cipher.

Se la tua applicazione ha più file di ambiente, come .env e .env.staging, puoi indicare quale cifrare tramite l’opzione --env.

php artisan env:encrypt --env=staging

Nomi delle variabili leggibili

Quando cifri il file di ambiente, l’opzione --readable ti permette di mantenere visibili i nomi delle variabili cifrando solo i loro valori.

php artisan env:encrypt --readable

Il risultato è un file cifrato nel seguente formato:

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

Il formato leggibile ti permette di vedere quali variabili d’ambiente esistono senza esporre dati sensibili. Rende anche più semplice la revisione delle pull request, poiché puoi vedere quali variabili sono state aggiunte, rimosse o modificate senza decifrare il file. Durante la decifratura dei file di ambiente Laravel rileva automaticamente il formato utilizzato, quindi il comando env:decrypt non richiede opzioni aggiuntive.

Quando usi l’opzione --readable, i commenti e le righe vuote del file di ambiente originale non vengono inclusi nell’output cifrato.

Aggiornare file di ambiente cifrati in formato leggibile

Quando aggiorni un file di ambiente cifrato in formato leggibile, Laravel conserva i valori non modificati e rimuove le variabili che non esistono più nel file di ambiente di origine.

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Se il file cifrato non esiste, viene creato. Quando aggiorni un file esistente, fornisci la stessa chiave di cifratura e lo stesso cifrario usati per crearlo. Se il file non può essere decifrato, il comando fallisce senza sovrascriverlo. Per ricifrare tutti i valori usa l’opzione --force. Questo ti permette di cambiare la chiave di cifratura o di sostituire un file cifrato non valido.

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Decifratura

Per decifrare un file di ambiente usa il comando env:decrypt. Questo comando richiede una chiave di decifratura, che Laravel recupera dalla variabile d’ambiente LARAVEL_ENV_ENCRYPTION_KEY.

php artisan env:decrypt

Oppure passa la chiave direttamente tramite l’opzione --key.

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

Quando esegui il comando env:decrypt, Laravel decifra il contenuto del file .env.encrypted e lo scrive nel file .env. Usa l’opzione --cipher per decifrare con un cifrario 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 indicare quale decifrare tramite l’opzione --env.

php artisan env:decrypt --env=staging

Per sovrascrivere un file di ambiente esistente, usa l’opzione --force.

php artisan env:decrypt --force

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.

Introduzione

Nozioni di base

Gestione delle richieste

Database

Autenticazione

Helper e comunicazione esterna

Test e deployment

Supporto allo sviluppo con AI

Introduzione

Il comando `about`

Configurazione dell’ambiente (.env)

Sicurezza del file di ambiente

File di ambiente aggiuntivi

Tipi delle variabili d’ambiente

Lettura delle variabili d’ambiente

Verifica dell’ambiente corrente

Cifratura del file di ambiente

Cifratura

Nomi delle variabili leggibili

Aggiornare file di ambiente cifrati in formato leggibile

Decifratura

Accesso ai valori di configurazione

Cache della configurazione

Pubblicare i file di configurazione

Modalità debug

Modalità manutenzione

Attivare la modalità manutenzione

Bypass della modalità manutenzione

Modalità manutenzione su più server

Pre-rendering della vista di manutenzione

Disattivare la modalità manutenzione

Prossimi passi

Routing

​Introduzione

​Il comando about

​Configurazione dell’ambiente (.env)

​Sicurezza del file di ambiente

​File di ambiente aggiuntivi

​Tipi delle variabili d’ambiente

​Lettura delle variabili d’ambiente

​Verifica dell’ambiente corrente

​Cifratura del file di ambiente

​Cifratura

​Nomi delle variabili leggibili

​Aggiornare file di ambiente cifrati in formato leggibile

​Decifratura

​Accesso ai valori di configurazione

​Cache della configurazione

​Pubblicare i file di configurazione

​Modalità debug

​Modalità manutenzione

​Attivare la modalità manutenzione

​Bypass della modalità manutenzione

​Modalità manutenzione su più server

​Pre-rendering della vista di manutenzione

​Disattivare la modalità manutenzione

​Prossimi passi

Routing

Introduzione

Il comando `about`

Configurazione dell’ambiente (.env)

Sicurezza del file di ambiente

File di ambiente aggiuntivi

Tipi delle variabili d’ambiente

Lettura delle variabili d’ambiente

Verifica dell’ambiente corrente

Cifratura del file di ambiente

Cifratura

Nomi delle variabili leggibili

Aggiornare file di ambiente cifrati in formato leggibile

Decifratura

Accesso ai valori di configurazione

Cache della configurazione

Pubblicare i file di configurazione

Modalità debug

Modalità manutenzione

Attivare la modalità manutenzione

Bypass della modalità manutenzione

Modalità manutenzione su più server

Pre-rendering della vista di manutenzione

Disattivare la modalità manutenzione

Prossimi passi