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

# Guida all'aggiornamento da Laravel 11 a 12

> Spiega la procedura di aggiornamento da Laravel 11 a 12 e le principali modifiche

## Introduzione

Laravel 12 è stato rilasciato a febbraio 2025. Questa guida illustra la procedura di aggiornamento da Laravel 11.x a 12.x.

<Info>
  Il tempo stimato necessario all'aggiornamento è di **circa 5 minuti**. L'impatto dei breaking change sull'applicazione varia in base a dimensione e funzionalità usate.
</Info>

### Aggiornamento automatico con Laravel Shift

Puoi automatizzare l'aggiornamento con [Laravel Shift](https://laravelshift.com/). Shift aggiorna in automatico le dipendenze e i file di configurazione.

***

## Cambiamenti per livello di impatto

### Impatto: Alto

* Aggiornamento delle dipendenze
* Aggiornamento dell'installer di Laravel

### Impatto: Medio

* Trait `HasUuids` di Eloquent e UUIDv7

### Impatto: Basso

* Carbon 3
* Mappatura degli indici dei risultati di Concurrency
* Risoluzione delle dipendenze di classe nel container
* Esclusione degli SVG dalla validazione delle immagini
* Path di root predefinito del disco filesystem locale
* Ispezione database multi-schema
* Merge di request con array annidati

***

## Procedura di aggiornamento

### Aggiornamento delle dipendenze

**Impatto: Alto**

Aggiorna in `composer.json` le seguenti dipendenze.

```json theme={null}
{
  "require": {
    "laravel/framework": "^12.0"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "pestphp/pest": "^3.0"
  }
}
```

Dopo l'aggiornamento, installa le dipendenze con il comando seguente.

```shell theme={null}
composer update
```

***

### Aggiornamento dell'installer di Laravel

**Impatto: Alto**

Se usi la CLI dell'installer di Laravel per creare nuove app, aggiornalo a una versione compatibile con Laravel 12.x e con i [nuovi starter kit](https://laravel.com/starter-kits).

Se l'hai installato con `composer global require`:

```shell theme={null}
composer global update laravel/installer
```

Se l'hai installato con `php.new`, esegui il comando di reinstallazione adatto al tuo sistema operativo.

<Tabs>
  <Tab title="macOS">
    ```shell theme={null}
    /bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```shell theme={null}
    # Esegui come amministratore
    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))
    ```
  </Tab>

  <Tab title="Linux">
    ```shell theme={null}
    /bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
    ```
  </Tab>
</Tabs>

Se usi la versione bundle di [Laravel Herd](https://herd.laravel.com), aggiorna Herd stesso all'ultima release.

***

## Nuovi starter kit

In Laravel 12 sono stati introdotti nuovi starter kit al posto dei precedenti Breeze e Jetstream. Eseguendo `laravel new` puoi selezionare in modo interattivo lo stack frontend.

Starter kit disponibili:

* **React** — Inertia 2, React 19, TypeScript, Tailwind 4, shadcn/ui
* **Vue** — Inertia 2, Vue Composition API, TypeScript, Tailwind 4, shadcn-vue
* **Svelte** — Inertia 2, Svelte 5, TypeScript, Tailwind 4, shadcn-svelte
* **Livewire** — Livewire, Tailwind 4, Flux UI

```shell theme={null}
laravel new my-app
```

Eseguendo il comando ti viene chiesta la selezione dello starter kit. Dopo la selezione, installa le dipendenze e avvia il server di sviluppo.

```shell theme={null}
cd my-app
npm install && npm run build
composer run dev
```

<Info>
  Se aggiorni un'app esistente, non è necessario reintrodurre uno starter kit. È una modifica per i nuovi progetti.
</Info>

***

## Modifiche non retrocompatibili (Breaking Changes)

### Eloquent

#### Trait `HasUuids` e UUIDv7

**Impatto: Medio**

Il trait `HasUuids` restituisce ora UUID v7 (UUID ordinati). Se vuoi mantenere il precedente comportamento con UUID v4 ordinati, passa al trait `HasVersion4Uuids`.

```php theme={null}
use Illuminate\Database\Eloquent\Concerns\HasUuids; // [tl! remove]
use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids; // [tl! add]
```

Se usavi già il trait `HasVersion7Uuids`, passa al trait `HasUuids` (ora ha lo stesso comportamento).

***

### Validazione

#### Esclusione degli SVG dalla validazione delle immagini

**Impatto: Basso**

La regola di validazione `image` non consente più gli SVG per impostazione predefinita. Per consentirli, specificalo esplicitamente.

```php theme={null}
use Illuminate\Validation\Rules\File;

'photo' => 'required|image:allow_svg'

// oppure
'photo' => ['required', File::image(allowSvg: true)],
```

***

### Storage

#### Path di root predefinito del disco filesystem locale

**Impatto: Basso**

Se nel `filesystems` non definisci esplicitamente il disco `local`, il path di root predefinito è cambiato da `storage/app` a `storage/app/private`.

Per mantenere il comportamento precedente, definisci esplicitamente il disco `local` nel file di configurazione.

```php theme={null}
// config/filesystems.php
'local' => [
    'driver' => 'local',
    'root' => storage_path('app'),
],
```

***

### Database

#### Ispezione database multi-schema

**Impatto: Basso**

`Schema::getTables()`, `Schema::getViews()` e `Schema::getTypes()` restituiscono ora, per impostazione predefinita, i risultati di tutti gli schemi. Per limitarti a uno schema specifico, passa l'argomento `schema`.

```php theme={null}
// Tabelle di tutti gli schemi
$tables = Schema::getTables();

// Solo tabelle dello schema 'main'
$tables = Schema::getTables(schema: 'main');
```

`Schema::getTableListing()` restituisce ora, per impostazione predefinita, nomi di tabella qualificati dallo schema.

```php theme={null}
$tables = Schema::getTableListing();
// ['main.migrations', 'main.users', 'blog.posts']

$tables = Schema::getTableListing(schema: 'main', schemaQualified: false);
// ['migrations', 'users']
```

#### Modifica della firma del costruttore per il database

**Impatto: Molto basso**

I costruttori di `Illuminate\Database\Schema\Blueprint` e `Illuminate\Database\Grammar` richiedono ora un'istanza `Connection` come primo argomento.

```php theme={null}
// Laravel <= 11.x
$grammar = new MySqlGrammar;
$grammar->setConnection($connection);

// Laravel >= 12.x
$grammar = new MySqlGrammar($connection);
```

Inoltre, le seguenti API sono state rimosse o deprecate.

| API                                              | Stato     |
| ------------------------------------------------ | --------- |
| `Blueprint::getPrefix()`                         | Deprecato |
| `Connection::withTablePrefix()`                  | Rimosso   |
| `Grammar::getTablePrefix()` / `setTablePrefix()` | Deprecati |
| `Grammar::setConnection()`                       | Rimosso   |

Ottieni il prefisso della tabella direttamente dalla connessione.

```php theme={null}
$prefix = $connection->getTablePrefix();
```

***

### Concurrency

#### Mappatura degli indici dei risultati

**Impatto: Basso**

Se passi un array associativo a `Concurrency::run()`, i risultati ora vengono restituiti in corrispondenza delle rispettive chiavi.

```php theme={null}
$result = Concurrency::run([
    'task-1' => fn () => 1 + 1,
    'task-2' => fn () => 2 + 2,
]);

// ['task-1' => 2, 'task-2' => 4]
```

***

### Container

#### Valori predefiniti nella risoluzione delle dipendenze di classe

**Impatto: Basso**

Il container di DI rispetta ora i valori predefiniti delle proprietà della classe quando risolve un'istanza.

```php theme={null}
class Example
{
    public function __construct(public ?Carbon $date = null) {}
}

$example = resolve(Example::class);

// Laravel <= 11.x: restituisce un'istanza Carbon
// Laravel >= 12.x: restituisce null
```

***

### Request

#### Merge di request con array annidati

**Impatto: Basso**

Con `$request->mergeIfMissing()` puoi ora mergiare dati di array annidati usando la notazione con punti. Prima le chiavi con notazione a punti venivano create direttamente come chiavi di primo livello.

```php theme={null}
$request->mergeIfMissing([
    'user.last_name' => 'Otwell',
]);
```

***

### Routing

#### Priorità delle rotte

**Impatto: Basso**

Il comportamento in presenza di più rotte con lo stesso nome è stato uniformato tra rotte cache e non-cache. Anche nel routing non cache viene ora considerata prioritaria la prima rotta registrata, non l'ultima.

***

### Autenticazione

#### Modifica del costruttore di `DatabaseTokenRepository`

**Impatto: Molto basso**

Il costruttore di `Illuminate\Auth\Passwords\DatabaseTokenRepository` accetta il parametro `$expires` in secondi, non più in minuti.

***

### Carbon 3

**Impatto: Basso**

Il supporto a Carbon 2.x è stato rimosso. Tutte le app Laravel 12 richiedono [Carbon 3.x](https://carbon.nesbot.com/guide/getting-started/migration.html).

***

## Conclusioni

Laravel 12 è una versione che si aggiorna in modo relativamente fluido. Ecco i punti principali di attenzione.

| Modifica                                          | Impatto | Azione                                                |
| ------------------------------------------------- | ------- | ----------------------------------------------------- |
| Aggiornamento delle dipendenze in `composer.json` | Alto    | Passa a `laravel/framework ^12.0`                     |
| Aggiornamento dell'installer di Laravel           | Alto    | `composer global update`                              |
| `HasUuids` → UUIDv7                               | Medio   | Se necessario, passa a `HasVersion4Uuids`             |
| Esclusione degli SVG in `image`                   | Basso   | Se vuoi consentire SVG, aggiungi `allow_svg`          |
| Cambio del root predefinito del disco locale      | Basso   | Specificalo esplicitamente nel file di configurazione |
| Carbon 3 richiesto                                | Basso   | Verifica la compatibilità API                         |

***

## Riferimenti

* [Guida ufficiale all'aggiornamento (in inglese)](https://laravel.com/docs/12.x/upgrade)
* [Diff del repository laravel/laravel (11.x → 12.x)](https://github.com/laravel/laravel/compare/11.x...12.x)
* [Nuovi starter kit](https://laravel.com/starter-kits)
* [Laravel Shift](https://laravelshift.com) — servizio della community che automatizza l'aggiornamento
* [Guida di migrazione a Carbon 3](https://carbon.nesbot.com/guide/getting-started/migration.html)


## Related topics

- [Guida all'aggiornamento da Laravel 12 a 13](/it/blog/upgrade-12-to-13.md)
- [Aggiornamento da Laravel 10 a 11](/it/blog/upgrade-10-to-11.md)
- [Aggiornamento da Laravel 8 a 9](/it/blog/upgrade-8-to-9.md)
- [Aggiornamento da Laravel 9 a 10](/it/blog/upgrade-9-to-10.md)
- [Riepilogo delle novità di Laravel 13](/it/blog/laravel-13-new-features.md)