> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={null}
flowchart LR
    A["file .env"] -->|env()| B["file config/"]
    B -->|config()| C["Applicazione"]
```

### Il comando `about`

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

```shell theme={null}
php artisan about
```

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

```shell theme={null}
php artisan about --only=environment
```

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

```shell theme={null}
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](https://github.com/vlucas/phpdotenv). 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`.

<Info>
  Quando sviluppi in team è comodo aggiornare `.env.example` e includerlo nel repository. Con valori segnaposto è chiaro a tutti quali variabili d'ambiente sono richieste.
</Info>

### Sicurezza del file di ambiente

<Warning>
  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.
</Warning>

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.

```ini theme={null}
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()`.

```php theme={null}
'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`.

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

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

```php theme={null}
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.

```shell theme={null}
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`.

```shell theme={null}
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.

```php theme={null}
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()`.

```php theme={null}
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.

```php theme={null}
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.

```shell theme={null}
php artisan config:cache
```

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

<Warning>
  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.
</Warning>

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.

<Tip>
  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.
</Tip>

Per rimuovere la cache usa il comando `config:clear`.

```shell theme={null}
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`.

```shell theme={null}
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`.

<Warning>
  **In produzione imposta sempre `APP_DEBUG` a `false`.** Se resta `true`, rischi di esporre agli utenti finali informazioni di configurazione sensibili dell'applicazione.
</Warning>

```ini theme={null}
# 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

```shell theme={null}
php artisan down
```

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

```shell theme={null}
php artisan down --refresh=15
```

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

```shell theme={null}
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`.

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

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

```shell theme={null}
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.

```ini theme={null}
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`.

```shell theme={null}
php artisan down --render="errors::503"
```

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

```shell theme={null}
php artisan down --redirect=/
```

### Disattivare la modalità manutenzione

```shell theme={null}
php artisan up
```

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

<Tip>
  Se vuoi eliminare completamente il downtime, valuta una piattaforma completamente gestita come [Laravel Cloud](https://cloud.laravel.com).
</Tip>

## Prossimi passi

<Card title="Routing" icon="route" href="/it/routing">
  Impara le basi del routing per collegare URL e controller.
</Card>


## Related topics

- [Hashing](/it/hashing.md)
- [Labeler](/it/packages/laravel-bluesky/labeler.md)
- [WebSocket (Jetstream / Firehose)](/it/packages/laravel-bluesky/websocket.md)
- [Logging](/it/logging.md)
- [Laravel Pint](/it/pint.md)