> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Gestire la compatibilità tra versioni dei pacchetti > Strategie di manutenzione dei pacchetti per gli upgrade major di Laravel e PHP: dall'aggiornamento di composer.json alla configurazione della test matrix di GitHub Actions. 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](/it/advanced/package-development). 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 Aggiungi la nuova versione al range di dipendenza. Se continui a supportare vecchie versioni, elencale con `||`. ```json theme={null} "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. ```json theme={null} "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. In locale o in CI esegui i test con la nuova versione di Laravel. ```shell theme={null} 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. Aggiungi la nuova versione di Laravel alla matrix di CI per verificare la compatibilità in modo continuo. Vedi [Esempio di configurazione della test matrix](#esempio-di-configurazione-della-test-matrix). 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. * [laravel/socialite](https://github.com/laravel/socialite) * [laravel/horizon](https://github.com/laravel/horizon) * [laravel/telescope](https://github.com/laravel/telescope) 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. | Laravel | Requisito minimo PHP | | ---------- | -------------------- | | Laravel 11 | PHP 8.2 | | Laravel 12 | PHP 8.2 | | Laravel 13 | PHP 8.3 | | Laravel 14 | PHP 8.4 | ```json theme={null} "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. ```json theme={null} "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. | Criterio | Descrizione | | ---------------------------------- | ------------------------------------------------------------------------------------------------- | | Fine supporto ufficiale di Laravel | Termina il supporto quando termina il supporto della versione Laravel | | Utilizzo | Quando le statistiche di download su Packagist mostrano pochi utenti della vecchia versione | | Difficoltà nell'aggiungere feature | Quando 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`. ```markdown theme={null} ## 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. ```shell theme={null} # 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`. ```shell theme={null} 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. ```json theme={null} { "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. ```json theme={null} "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. | Fonte | Contenuto | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Watch di GitHub | Su ogni repository "Watch → Custom → Releases" per notifiche via email. Registra anche i pacchetti principali oltre a framework | | [Blog ufficiale Laravel](https://laravel.com/blog) | Annuncio delle major e spiegazione delle novità | | [Guida ufficiale all'upgrade](https://laravel.com/docs/upgrade) | Lista dei breaking change | | [Commit log di laravel/framework](https://github.com/laravel/framework/commits/master) | Seguire 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. ```yaml theme={null} 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. ```yaml theme={null} # 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. ```json theme={null} { "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 Come sviluppare pacchetti Laravel imperniati sui service provider. Come scrivere test dei pacchetti usando l'Expectation API e i dataset di Pest. ## Related topics - [CHANGELOG e release management dei pacchetti](/it/advanced/package-changelog.md) - [Analisi statica dei pacchetti (PHPStan / Larastan)](/it/advanced/package-static-analysis.md) - [Testare pacchetti Laravel con Orchestra Testbench](/it/advanced/package-testing.md) - [Sviluppare pacchetti con Testbench Workbench](/it/advanced/package-workbench.md) - [Pinning e sicurezza delle GitHub Actions](/it/advanced/github-actions-pinning.md)