Configurazione di Laravel

Introduzione

Tutti i file di configurazione per il framework Laravel sono memorizzati nella directory “config”. Ogni opzione è documentata, quindi sentiti libero di esaminare i file e familiarizzare con le opzioni disponibili per te.

Questi file di configurazione ti consentono di configurare informazioni come la connessione al database, il server di posta elettronica e vari altri valori di configurazione fondamentali come il fuso orario dell’applicazione e la chiave di crittografia.

Panoramica dell’applicazione

Di fretta? Puoi ottenere una panoramica rapida della configurazione, dei driver e dell’ambiente dell’applicazione utilizzando il comando Artisan “about“:

php artisan about

Se sei interessato solo a una sezione specifica dell’output della panoramica dell’applicazione, puoi filtrare quella sezione utilizzando l’opzione –only:

php artisan about --only=environment

Configurazione dell’ambiente

È spesso utile avere valori di configurazione diversi in base all’ambiente in cui viene eseguita l’applicazione. Ad esempio, potresti desiderare di utilizzare un driver di cache diverso in locale rispetto a quello utilizzato nel server di produzione.

Per semplificare questa operazione, Laravel utilizza la libreria PHP DotEnv. In un’installazione di Laravel appena creata, la directory principale dell’applicazione conterrà un file .env.example che definisce molte variabili d’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 variare in base al fatto che l’applicazione venga eseguita in locale o su un server web di produzione. Questi valori vengono quindi recuperati da vari file di configurazione di Laravel all’interno della directory config utilizzando la funzione env di Laravel.

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

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

Sicurezza del file di ambiente

Il tuo file .env non dovrebbe essere incluso nel controllo del codice sorgente dell’applicazione, poiché ogni sviluppatore o server che utilizza l’applicazione potrebbe richiedere una configurazione dell’ambiente diversa. Inoltre, ciò costituirebbe un rischio per la sicurezza nel caso in cui un intruso ottenga accesso al repository di controllo del codice sorgente, poiché potrebbero essere esposte credenziali sensibili.

Tuttavia, è possibile crittografare il file di ambiente utilizzando la funzionalità di crittografia dell’ambiente integrata in Laravel. I file di ambiente crittografati possono essere inseriti in modo sicuro nel controllo del codice sorgente.

File di ambiente aggiuntivi

Prima di caricare le variabili d’ambiente dell’applicazione, Laravel verifica se è stata fornita esternamente una variabile d’ambiente 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 il file non esiste, verrà caricato il file .env predefinito.

Tipi di variabili d’ambiente

Tutte le variabili nei file .env vengono generalmente analizzate come stringhe, ma sono state create alcune valori riservati per consentirti di restituire una gamma più ampia di tipi dalla funzione env().

.env Value	env() Value
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ”
(empty)	(string) ”
null	(null) null
(null)	(null) null

Se hai bisogno di definire una variabile d’ambiente con un valore che contiene spazi, puoi farlo racchiudendo il valore tra doppi apici:

APP_NAME="My Application"

Recupero della configurazione dell’ambiente

Tutte le variabili elencate nel file .env saranno caricate nella variabile super-globale $_ENV quando la tua applicazione riceve una richiesta. Tuttavia, puoi utilizzare la funzione env per recuperare i valori di queste variabili nei tuoi file di configurazione. Infatti, se esaminiamo i file di configurazione di Laravel, noterai che molte delle opzioni stanno già utilizzando questa funzione.

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

Il secondo valore passato alla funzione env è il “valore predefinito”. Questo valore verrà restituito se non esiste alcuna variabile d’ambiente per la chiave specificata.

Determinare l’ambiente corrente

L’ambiente corrente dell’applicazione viene determinato tramite la variabile APP_ENV nel file .env. Puoi accedere a questo valore utilizzando il metodo environment sull’ App facade, nel seguente modo:

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

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

if (App::environment('local')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

ChatGPT
La rilevazione dell’ambiente corrente dell’applicazione può essere sovrascritta definendo una variabile di ambiente APP_ENV a livello di server.

Crittografia dei file di ambiente

I file di ambiente non crittografati non dovrebbero mai essere archiviati nel controllo di versione del codice sorgente. Tuttavia, Laravel consente di crittografare i file di ambiente in modo che possano essere aggiunti in modo sicuro al controllo di versione insieme al resto dell’applicazione.

Crittografia

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

php artisan env:encrypt

Eseguendo il comando env:encrypt, verrà crittografato il tuo file .env e i contenuti criptati saranno inseriti in un file .env.encrypted. La chiave di decrittografia viene mostrata nell’output del comando e dovrebbe essere archiviata in un gestore di password sicuro. Se desideri fornire la tua chiave di crittografia, puoi utilizzare l’opzione –key al momento dell’esecuzione del comando.

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

La lunghezza della chiave fornita deve corrispondere alla lunghezza della chiave richiesta dalla cifratura utilizzata. Per impostazione predefinita, Laravel utilizza il cifrario AES-256-CBC, che richiede una chiave di 32 caratteri. Se desideri utilizzare un cifrario diverso supportato dall’encrypter di Laravel, puoi passare l’opzione –cipher al momento dell’esecuzione del comando.

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

php artisan env:encrypt --env=staging

Decrittazione

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

php artisan env:decrypt

Altrimenti, 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 inserirà il contenuto decifrato nel file .env.

L’opzione –cipher può essere fornita al comando env:decrypt per utilizzare una cifratura personalizzata:

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

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

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

Accedere ai valori di configurazione

Puoi facilmente accedere ai valori di configurazione utilizzando la funzione globale config da qualsiasi parte della tua applicazione. I valori di configurazione possono essere accessibili utilizzando la sintassi “dot”, che include il nome del file e dell’opzione che desideri accedere. Puoi anche specificare un valore predefinito che verrà restituito se l’opzione di configurazione non esiste:

$value = config('app.timezone');
 
// Retrieve a default value if the configuration value does not exist...
$value = config('app.timezone', 'Asia/Seoul');

Per impostare i valori di configurazione durante l’esecuzione, passa un array alla funzione config:

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

Cache di configurazione

Per ottimizzare le prestazioni della tua applicazione, è consigliabile memorizzare nella cache tutti i file di configurazione in un singolo file utilizzando il comando Artisan config:cache. Questo combinerà tutte le opzioni di configurazione per la tua applicazione in un unico file che può essere caricato rapidamente dal framework.

Di solito si esegue il comando php artisan config:cache come parte del processo di distribuzione in produzione. Il comando non dovrebbe essere eseguito durante lo sviluppo locale poiché le opzioni di configurazione verranno spesso modificate durante lo sviluppo dell’applicazione.

Una volta che la configurazione è stata memorizzata nella cache, il file .env della tua applicazione non verrà 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, assicurati 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 accessibili da qualsiasi punto della tua applicazione utilizzando la funzione config descritta in precedenza.

Il comando config:clear può essere utilizzato per eliminare la configurazione memorizzata nella cache.

php artisan config:clear

If you execute the config:cache command during your deployment process, you should be sure that you are only calling the env function from within your configuration files. Once the configuration has been cached, the .env file will not be loaded; therefore, the env function will only return external, system level environment variables.

Modalità Debug

L’opzione debug nel file di configurazione config/app.php determina quanto informazioni sull’errore vengono effettivamente visualizzate all’utente. Per impostazione predefinita, questa opzione è impostata per rispettare il valore della variabile di ambiente APP_DEBUG, che è memorizzato nel file .env.

Per lo sviluppo locale, dovresti impostare la variabile di ambiente APP_DEBUG su true. Nell’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 dell’applicazione.

Modalità Manutenzione

Permettimi di tradurre soltanto:

Quando la tua applicazione è in modalità di manutenzione, verrà visualizzata una vista personalizzata per tutte le richieste inviate all’applicazione. Ciò rende facile “disabilitare” l’applicazione durante l’aggiornamento o quando si sta effettuando la manutenzione. Un controllo per la modalità di manutenzione è incluso nello stack di middleware predefinito per l’applicazione. Se l’applicazione è in modalità di manutenzione, verrà generata un’istanza di Symfony\Component\HttpKernel\Exception\HttpException con un codice di stato 503.

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

php artisan down

Per inviare l’intestazione HTTP Refresh con tutte le risposte della modalità di manutenzione, puoi fornire l’opzione refresh quando esegui il comando down. L’intestazione Refresh istruirà il browser a ricaricare automaticamente la pagina dopo il numero di secondi specificato.

php artisan down --refresh=15

Puoi anche fornire l’opzione retry al comando down, che verrà impostata come valore dell’intestazione HTTP Retry-After, anche se i browser di solito 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 impostato l’applicazione in modalità di manutenzione, puoi visitare l’URL dell’applicazione corrispondente a questo token e Laravel emetterà un cookie di bypass della modalità di manutenzione al tuo browser:

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

Quando si accede a questa route nascosta, sarai quindi reindirizzato alla route / dell’applicazione. Una volta che il cookie è stato emesso al tuo browser, potrai navigare normalmente nell’applicazione come se non fosse in modalità di manutenzione.

Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as ?.

Pre-renderizzare la vista della modalità di manutenzione.

Se si utilizza il comando php artisan down durante il rilascio, gli utenti potrebbero comunque incontrare occasionalmente degli errori se accedono all’applicazione mentre le dipendenze di Composer o altri componenti dell’infrastruttura vengono aggiornati. Questo avviene perché una parte significativa del framework Laravel deve essere avviata per determinare che l’applicazione è in modalità di manutenzione e renderizzare la vista della modalità di manutenzione utilizzando il motore di template.

Per questo motivo, Laravel consente di pre-renderizzare una vista della modalità di manutenzione che verrà restituita all’inizio del ciclo di richiesta. Questa vista viene renderizzata prima del caricamento di qualsiasi dipendenza dell’applicazione. È possibile pre-renderizzare un modello a scelta utilizzando l’opzione render del comando down.

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

Reindirizzamento delle richieste in modalità di manutenzione

Mentre è in modalità di manutenzione, Laravel mostrerà la vista della modalità di manutenzione per tutti gli URL dell’applicazione che l’utente cerca di accedere. Se desideri, puoi istruire Laravel a reindirizzare tutte le richieste a un URL specifico. Ciò può essere fatto utilizzando l’opzione di reindirizzamento (redirect). Ad esempio, potresti desiderare di reindirizzare tutte le richieste all’URI /:

php artisan down --redirect=/

Disabilitare la modalità di manutenzione

Per disabilitare la modalità di manutenzione, utilizza il comando up:

php artisan up

You may customize the default maintenance mode template by defining your own template at resources/views/errors/503.blade.php.

La modalità di manutenzione e le code (queues)

Durante la modalità di manutenzione, i job in coda non verranno elaborati. Una volta che l’applicazione esce dalla modalità di manutenzione, i job verranno elaborati normalmente.

Alternative alla modalità di manutenzione

Poiché la modalità di manutenzione richiede che la tua applicazione sia inattiva per alcuni secondi, considera alternative come Laravel Vapor e Envoyer per ottenere un deployment senza tempi di inattività con Laravel.