Vai al contenuto principale
Laravel esce con una nuova versione major ogni anno, di solito tra febbraio e marzo. Per gli sviluppatori di pacchetti, completare rapidamente il supporto alla nuova versione è un contributo all’ecosistema e un fattore che aumenta l’affidabilità del proprio pacchetto.
Questa pagina è la sorella di Sviluppo di pacchetti Laravel. Si presuppone la conoscenza di base dello sviluppo dei pacchetti (service provider, struttura del composer.json, ecc.).

​
Adattarsi agli upgrade major di Laravel

​
Flusso operativo

1

Aggiornare require nel composer.json

Aggiungi la nuova versione al range di dipendenza. Se continui a supportare vecchie versioni, elencale con ||.
"require": {
    "php": "^8.2",
    "illuminate/support": "^12.0||^13.0"
}
Completato il supporto alla nuova versione, se termini il supporto alle vecchie, rimuovi i vincoli obsoleti.
"require": {
    "php": "^8.3",
    "illuminate/support": "^13.0||^14.0"
}
Dipendere non da tutto illuminate/framework ma solo dai componenti necessari (illuminate/support ecc.) mantiene piccolo l’albero delle dipendenze.
2

Eseguire i test sulla nuova versione

In locale o in CI esegui i test con la nuova versione di Laravel.
composer update
vendor/bin/pest
Se i test passano, la compatibilità di base è confermata. In caso contrario correggi le API modificate o i metodi rimossi.
3

Aggiungere la nuova versione alla test matrix di GitHub Actions

Aggiungi la nuova versione di Laravel alla matrix di CI per verificare la compatibilità in modo continuo. Vedi Esempio di configurazione della test matrix.
4

Rilasciare il supporto alla nuova versione

Tagga e rilascia una nuova versione che include le modifiche a composer.json. Gli utenti potranno installare sulla nuova versione di Laravel con un semplice composer update.

​
Prendere spunto dai pacchetti ufficiali

Se sei incerto sull’approccio, il modo più sicuro è leggere il composer.json dei pacchetti ufficiali Laravel. Sono mantenuti dal team Laravel, sono i più veloci ad adattarsi alle nuove versioni e la loro sintassi di dipendenza illuminate/* è un buon riferimento.

​
Aggiornare il requisito di versione PHP

Un upgrade di Laravel a volte alza anche il requisito minimo di PHP. Aggiorna coerentemente anche il requisito PHP nel composer.json del pacchetto.
LaravelRequisito minimo PHP
Laravel 11PHP 8.2
Laravel 12PHP 8.2
Laravel 13PHP 8.3
Laravel 14PHP 8.4
"require": {
    "php": "^8.2",
    "illuminate/support": "^11.0||^12.0||^13.0"
}

​
Se vuoi sfruttare funzionalità PHP recenti

Se vuoi usare feature di PHP 8.3+ (costanti tipizzate, nuove funzioni random, ecc.) è opportuno alzare il requisito minimo. Alzarlo, dal punto di vista del Semantic Versioning, è un breaking change: fallo in occasione di un upgrade major. 
"require": {
    "php": "^8.3",
    "illuminate/support": "^12.0||^13.0"
}
Alzando il minimo PHP, gli utenti su PHP più vecchi non potranno più aggiornare il pacchetto. Chiarisci il cambiamento in README e CHANGELOG e comunicalo in anticipo.

​
Strategia di end-of-life per le versioni vecchie

Mantenere le vecchie versioni all’infinito aumenta il costo di manutenzione a lungo termine. Definire una policy chiara e chiudere periodicamente il supporto alle vecchie versioni è più salutare.

​
Timing per la fine del supporto

L’approccio più comune è allinearsi al periodo di supporto di Laravel. Laravel offre 18 mesi di bugfix e 2 anni di security fix per ogni versione. Se il pacchetto adotta una policy analoga, gli utenti la capiscono facilmente.
CriterioDescrizione
Fine supporto ufficiale di LaravelTermina il supporto quando termina il supporto della versione Laravel
UtilizzoQuando le statistiche di download su Packagist mostrano pochi utenti della vecchia versione
Difficoltà nell’aggiungere featureQuando il supporto alla vecchia versione rende complicata l’implementazione di nuove funzionalità

​
Documentare la policy nel README

Perché gli utenti abbiano aspettative corrette, indica la policy in README.md. 
## Version Compatibility

| Package | Laravel | PHP  |
|---------|---------|------|
| 3.x     | 13.x    | ^8.2 |
| 2.x     | 11.x, 12.x | ^8.2 |
| 1.x     | 10.x    | ^8.1 |

Only the latest major version receives new features.
Security fixes are backported to the previous major version for 12 months.

​
Costo del mantenimento delle vecchie versioni

Continuare a supportare le vecchie versioni comporta questi costi.
  • Doppio bugfix — devi correggere lo stesso bug su più branch
  • Aumento del codice condizionale — la complessità di gestire implementazioni diverse per versione con branch condizionali
  • Matrix di test più grande — i tempi di esecuzione CI si allungano
  • Complicazione dei fix di sicurezza — backport sicuri verso versioni vecchie diventano più complessi
Nella dinamica di aggiornamento dell’ecosistema, chiudere in modo ordinato il supporto alle vecchie versioni incoraggia gli utenti a migrare all’ambiente più recente.

​
Vantaggi dell’adozione precoce

Se il tuo supporto è pronto insieme al rilascio di Laravel, gli utenti possono migrare subito. È un segnale importante di affidabilità del pacchetto.

​
Verificare in anticipo su versioni di sviluppo

Laravel non pubblica beta o RC, ma puoi installare la prossima versione in sviluppo indicando dev-master o @dev. Verificando prima del release major, puoi supportare al giorno zero. 
# installa la prossima versione con dev-master
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest
Oppure puoi usare il vincolo @dev. 
composer require laravel/framework:^14.0@dev --no-update
composer update
vendor/bin/pest
Impostando minimum-stability su dev risolvi le dipendenze verso le versioni di sviluppo. 
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
Con prefer-stable: true, quando esiste una release stabile prevale quella. Puoi testare sulle versioni di sviluppo con la certezza di passare automaticamente alle release stabili.

​
Il primo passo può essere la sola modifica del composer.json

Anche prima di aver verificato la compatibilità completa, aggiornare il range di dipendenze e rilasciare basta a rendere il pacchetto installabile. 
"illuminate/support": "^12.0||^13.0"
Piccoli bug si correggono con release patch dopo il rilascio. Meglio rendere il pacchetto installabile subito che aspettare la perfezione.

​
Seguire le notizie sui rilasci

Modi per stare al passo con le release delle nuove versioni.
FonteContenuto
Watch di GitHubSu ogni repository “Watch → Custom → Releases” per notifiche via email. Registra anche i pacchetti principali oltre a framework
Blog ufficiale LaravelAnnuncio delle major e spiegazione delle novità
Guida ufficiale all’upgradeLista dei breaking change
Commit log di laravel/frameworkSeguire in anticipo le modifiche della prossima versione

​
Esempio di configurazione della test matrix

Esempio di workflow GitHub Actions che testa automaticamente le combinazioni di più versioni di Laravel e PHP. 
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]
        include:
          - laravel: "^13.0"
            testbench: "^10.0"
          - laravel: "^12.0"
            testbench: "^9.0"

    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           "orchestra/testbench:${{ matrix.testbench }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

​
L’importanza di fail-fast: false

Impostando fail-fast: false, quando una combinazione fallisce le altre continuano. In una sola esecuzione CI capisci in quali combinazioni si presenta il problema.

​
Aggiornamento graduale della matrix

Quando esce una nuova versione di Laravel, la aggiungi alla matrix. Quando termini il supporto di una vecchia, la rimuovi. 
# quando esce Laravel 14, aggiungi
matrix:
  laravel: ["^13.0", "^14.0"]
  include:
    - laravel: "^14.0"
      testbench: "^11.0"
    - laravel: "^13.0"
      testbench: "^10.0"

​
Esempio di composer.json

Esempio completo di composer.json con supporto multi-versione. 
{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "pestphp/pest": "^3.0",
        "pestphp/pest-plugin-laravel": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ]
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

​
Checklist per l’upgrade di versione

  • Testare sulle versioni di sviluppo (dev-master / @dev)
  • Verificare i breaking change sulla guida ufficiale di upgrade
  • Implementare le modifiche di supporto in ambiente di test
  • Aggiungere la nuova versione alla test matrix e verificare in CI
  • Aggiungere la nuova versione ai requisiti illuminate/* in composer.json
  • Aggiornare eventualmente il requisito PHP
  • Aggiornare anche orchestra/testbench in require-dev alla versione compatibile
  • Taggare la nuova versione e sincronizzarla su Packagist
  • Aggiornare la tabella di compatibilità nel README
  • Documentare la fine del supporto in CHANGELOG/README
  • Rimuovere i vincoli delle vecchie versioni dal composer.json
  • Rimuovere le vecchie versioni dalla test matrix
  • Riordinare il codice con branch condizionali per le versioni vecchie

​
Pagine correlate

Nozioni di sviluppo dei pacchetti

Come sviluppare pacchetti Laravel imperniati sui service provider.

Test avanzati con Pest

Come scrivere test dei pacchetti usando l’Expectation API e i dataset di Pest.
Ultima modifica il 13 luglio 2026

Argomenti correlati

CHANGELOG e release management dei pacchettiAnalisi statica dei pacchetti (PHPStan / Larastan)Testare pacchetti Laravel con Orchestra TestbenchSviluppare pacchetti con Testbench WorkbenchPinning e sicurezza delle GitHub Actions