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

# Deployment

> Guida alla configurazione, ottimizzazione e gestione operativa per il deploy di un'applicazione Laravel in produzione

## Introduzione

Quando esegui il deploy di un'applicazione Laravel in produzione, occorre prepararla per farla girare nel modo più efficiente possibile.
Questa guida illustra i punti chiave per un deploy sicuro in produzione.

## Flusso di deploy

```mermaid theme={null}
flowchart TD
    A["Push del codice"] --> B["php artisan optimize"]
    B --> C["Serve tramite Nginx / FrankenPHP"]
    C --> D["php artisan reload"]
    D --> E["Riavvio dei queue worker<br>Reverb / Octane"]
    E --> F["Deploy completato"]
```

## Requisiti del server

Il framework Laravel ha i seguenti requisiti di sistema.
Sono necessari **PHP 8.3 o superiore** e le seguenti estensioni PHP.

| Estensione | Descrizione                     |
| ---------- | ------------------------------- |
| Ctype      | Controllo dei tipi di carattere |
| cURL       | Comunicazione HTTP              |
| DOM        | Manipolazione DOM di XML/HTML   |
| Fileinfo   | Rilevamento del tipo MIME       |
| Filter     | Filtraggio dei dati             |
| Hash       | Funzioni di hashing             |
| Mbstring   | Gestione stringhe multibyte     |
| OpenSSL    | Cifratura                       |
| PCRE       | Espressioni regolari            |
| PDO        | Connessione al database         |
| Session    | Gestione delle sessioni         |
| Tokenizer  | Analisi dei token PHP           |
| XML        | Elaborazione XML                |

## Configurazione del server

### Nginx

Se usi Nginx, parti dal seguente file di configurazione come base.
È importante **inoltrare tutte le richieste a `public/index.php`**.
Non spostare `index.php` nella root del progetto: esporresti file di configurazione riservati all'esterno.

```nginx theme={null}
server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### FrankenPHP

[FrankenPHP](https://frankenphp.dev/) è un moderno application server PHP scritto in Go.
Puoi avviare un'applicazione Laravel con un solo comando.

```shell theme={null}
frankenphp php-server -r public/
```

Per funzionalità avanzate come HTTP/3, compressione moderna, integrazione con [Laravel Octane](https://laravel.com/docs/octane) e binari standalone, consulta la [documentazione Laravel di FrankenPHP](https://frankenphp.dev/docs/laravel/).

### Permessi delle directory

Laravel deve scrivere nelle directory `bootstrap/cache` e `storage`.
Configura i permessi in modo che l'utente proprietario del processo del web server possa scrivere in queste directory.

```shell theme={null}
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

## Ottimizzazione

Durante il deploy in produzione, effettua la cache di configurazione, eventi, route e viste per migliorare le prestazioni.
Con il comando `optimize` puoi gestire tutta la cache in un'unica esecuzione.

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

Per svuotare le cache usa `optimize:clear`.

```shell theme={null}
php artisan optimize:clear
```

### Singoli comandi di ottimizzazione

`optimize` esegue in blocco i comandi seguenti. Puoi eseguirli anche singolarmente all'occorrenza.

| Comando                    | Descrizione                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `php artisan config:cache` | Unisce e mette in cache i file di configurazione in un solo file         |
| `php artisan event:cache`  | Mette in cache la mappa evento→listener                                  |
| `php artisan route:cache`  | Mette in cache le definizioni delle route accelerandone la registrazione |
| `php artisan view:cache`   | Precompila le viste Blade accelerando le richieste                       |

<Info>
  Dopo aver eseguito `config:cache`, chiama la funzione `env()` solo all'interno dei file di configurazione.
  Dopo la cache il file `.env` non viene più letto, quindi chiamare `env()` al di fuori dei file di configurazione restituirà `null`.
</Info>

## Ricaricamento dei servizi

Dopo il deploy di una nuova versione, i servizi di lunga durata come i queue worker, Laravel Reverb e Laravel Octane devono essere riavviati per usare il nuovo codice.

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

Questo comando termina i servizi ricaricabili.
Configura il process monitor (come Supervisor) in modo che li riavvii automaticamente.

<Info>
  Se usi Laravel Cloud, il ricaricamento graceful di tutti i servizi è gestito automaticamente e il comando `reload` non è necessario.
</Info>

## Modalità debug

L'opzione `debug` di `config/app.php` controlla quante informazioni di errore vengono mostrate all'utente.
Di default viene usato il valore della variabile d'ambiente `APP_DEBUG` nel file `.env`.

<Warning>
  **In produzione imposta sempre `APP_DEBUG` a `false`.**
  Se lasci `APP_DEBUG=true` in produzione rischi di esporre agli utenti finali informazioni di configurazione sensibili come credenziali del database e chiavi private.
</Warning>

```ini theme={null}
# .env (produzione)
APP_DEBUG=false
```

## Route di health check

Laravel include una route di health check integrata per monitorare lo stato dell'applicazione.
Puoi integrarla con monitor di uptime, load balancer e sistemi di orchestrazione come Kubernetes.

Di default è disponibile l'endpoint `/up` che restituisce `200` se l'applicazione è avviata correttamente e `500` se si è verificata un'eccezione all'avvio.

Puoi personalizzare l'URI in `bootstrap/app.php`.

```php theme={null}
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // il valore predefinito è /up
)
```

Alla richiesta di questa route viene emesso l'evento `Illuminate\Foundation\Events\DiagnosingHealth`, quindi puoi implementare controlli aggiuntivi (database, cache, ecc.) con un listener.

## Deploy con Laravel Cloud o Forge

### Laravel Cloud

Se cerchi una piattaforma di deploy completamente gestita e con autoscaling, [Laravel Cloud](https://cloud.laravel.com) è consigliata.
È un PaaS ottimizzato per Laravel che offre compute, database, cache e object storage gestiti.

Viene messa a punto direttamente dal team di sviluppo di Laravel e si integra senza soluzione di continuità con il framework.

### Laravel Forge

Se vuoi gestire da te i server ma non vuoi perdere tempo a configurare servizi come Nginx e MySQL, [Laravel Forge](https://forge.laravel.com) è comodo.

Crea server sui principali cloud provider come DigitalOcean, Linode e AWS e installa e gestisce automaticamente strumenti come Nginx, MySQL, Redis, Memcached e Beanstalk.

## Prossimi passi

<Card title="Deployment — Documentazione ufficiale" icon="arrow-right" href="https://laravel.com/docs/deployment">
  Puoi consultare i dettagli aggiornati della configurazione di deploy nella documentazione ufficiale.
</Card>


## Related topics

- [Introduzione a Laravel Nightwatch](/it/blog/nightwatch-introduction.md)
- [Mock](/it/mocking.md)
- [Test HTTP](/it/http-tests.md)
- [Test del database](/it/database-testing.md)
- [Introduzione al testing](/it/testing.md)