> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Versiecompatibiliteit van packages beheren > Een praktische uitleg van de onderhoudsstrategie voor packages bij major-upgrades van Laravel en PHP, van het bijwerken van composer.json tot de testmatrixconfiguratie in GitHub Actions. Laravel krijgt elk jaar rond februari–maart een major-upgrade. Voor packageontwikkelaars is het snel afronden van de ondersteuning voor een nieuwe versie een bijdrage aan het hele ecosysteem én een belangrijke activiteit die de betrouwbaarheid van je eigen package vergroot. Deze pagina is een zusterpagina van [De basis van packageontwikkeling](/nl/advanced/package-development). Ze gaat uit van basiskennis van packageontwikkeling (service providers, de opbouw van `composer.json`, enz.). ## Omgaan met major-upgrades van Laravel ### Het stappenplan Voeg de nieuwe versie toe aan het dependencybereik. Als je oudere versies blijft ondersteunen, zet je ze naast elkaar met `||`. ```json theme={null} "require": { "php": "^8.2", "illuminate/support": "^12.0||^13.0" } ``` Als de ondersteuning voor de nieuwe versie klaar is en je de oude versie niet langer ondersteunt, verwijder je de oude constraint. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^13.0||^14.0" } ``` Door alleen afhankelijk te zijn van de componenten die je nodig hebt, zoals `illuminate/support`, in plaats van heel `illuminate/framework`, houd je de dependency tree klein. Voer de tests lokaal of in CI uit met de nieuwe Laravel-versie. ```shell theme={null} composer update vendor/bin/pest ``` Als de tests slagen, is de basiscompatibiliteit bevestigd. Zo niet, dan pas je gewijzigde API's en verwijderde methodes aan. Voeg de nieuwe Laravel-versie toe aan de CI-testmatrix om de compatibiliteit continu te controleren. Zie [het voorbeeld van een testmatrixconfiguratie](#voorbeeld-van-een-testmatrixconfiguratie) voor details. Tag en release een nieuwe versie met de wijzigingen in `composer.json`. Gebruikers kunnen dan met alleen `composer update` op de nieuwe Laravel-versie installeren. ### Officiële packages als referentie Als je twijfelt over de aanpak, is het raadplegen van de `composer.json` van de officiële Laravel-packages de betrouwbaarste route. * [laravel/socialite](https://github.com/laravel/socialite) * [laravel/horizon](https://github.com/laravel/horizon) * [laravel/telescope](https://github.com/laravel/telescope) Deze packages worden beheerd door het Laravel-team, ondersteunen nieuwe versies het snelst en zijn ook een goede referentie voor hoe je de `illuminate/*`-versieconstraints noteert. ## PHP-versievereisten bijwerken Een Laravel-upgrade verhoogt soms ook de minimale PHP-vereiste. Werk de PHP-vereiste in de `composer.json` van je package dan mee bij. | Laravel | Minimale PHP-vereiste | | ---------- | --------------------- | | 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" } ``` ### Als je nieuwe PHP-features actief wilt gebruiken Wil je features van PHP 8.3 en later gebruiken (getypte constanten, nieuwe randomfuncties, enz.), dan moet je beslissen om de minimale vereiste te verhogen. Het verhogen van de minimale vereiste is volgens semantische versionering een breaking change, dus doe dit bij een major-upgrade. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^12.0||^13.0" } ``` Als je de minimale PHP-vereiste verhoogt, kunnen gebruikers met een oudere PHP-versie het package niet meer updaten. Het is belangrijk om dit vooraf duidelijk aan te kondigen in de README en changelog. ## Strategie voor het stopzetten van oude versies Oude versies eindeloos blijven onderhouden vergroot op de lange termijn de onderhoudskosten. Een duidelijk supportbeleid vastleggen en regelmatig de ondersteuning van oude versies stopzetten leidt tot een gezond packagebeheer. ### Wanneer stop je met ondersteuning? Een gangbare aanpak is **aansluiten bij de supportperiode van Laravel**. Laravel biedt per versie 18 maanden bugfixes en 2 jaar securityfixes. Als je package hetzelfde beleid hanteert, is dat voor gebruikers overzichtelijk. | Criterium | Toelichting | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Einde van officiële Laravel-ondersteuning | Stop met ondersteunen op het moment dat de ondersteuning van die Laravel-versie afloopt | | Gebruiksstatistieken | Het moment waarop de downloadstatistieken van Packagist laten zien dat er weinig gebruikers van de oude versie over zijn | | Belemmering voor nieuwe features | Het moment waarop de implementatie van nieuwe features complex wordt door de ondersteuning van oude versies | ### Zet het supportbeleid in de README Beschrijf het supportbeleid in `README.md`, zodat gebruikers de juiste verwachtingen hebben. ```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. ``` ### De kosten van het onderhouden van oude versies Als je oude versies blijft ondersteunen, ontstaan de volgende kosten: * **Dubbele bugfixes** — dezelfde bug moet je in meerdere branches repareren * **Meer vertakkende code** — de complexiteit van conditionele code die verschillende implementaties per versie opvangt * **Uitdijende testmatrix** — de CI-doorlooptijd wordt langer * **Complexere securitypatches** — je moet ook veilig naar oude versies backporten Terwijl het hele ecosysteem doorschuift naar nieuwe versies, heeft het netjes stopzetten van oude versies ook het effect dat gebruikers worden aangemoedigd om naar een actuele omgeving te migreren. ## De voordelen van vroeg reageren Als je ondersteuning al klaar is op het moment dat Laravel wordt uitgebracht, kunnen gebruikers meteen naar de nieuwe versie migreren. Dat is een belangrijk signaal van de betrouwbaarheid van je package. ### Vooraf verifiëren met de ontwikkelversie Laravel publiceert geen beta's of RC's, maar je kunt de volgende versie in ontwikkeling installeren via `dev-master` of `@dev`. Door vóór de major-release te verifiëren, is een zero-day-respons mogelijk. ```shell theme={null} # De volgende versie installeren via dev-master composer require laravel/framework:dev-master --no-update composer update vendor/bin/pest ``` Je kunt ook installeren met de `@dev`-constraint. ```shell theme={null} composer require laravel/framework:^14.0@dev --no-update composer update vendor/bin/pest ``` Door `minimum-stability` op `dev` te zetten, kun je de dependencies met ontwikkelversies oplossen. ```json theme={null} { "minimum-stability": "dev", "prefer-stable": true } ``` Met `prefer-stable: true` krijgt een stabiele versie voorrang wanneer die bestaat. Je test dus met de ontwikkelversie, terwijl automatisch overschakelen naar de stabiele versie gegarandeerd blijft. ### De eerste stap kan bij alleen een wijziging in composer.json blijven Zelfs vóór een volledige compatibiliteitscontrole kunnen gebruikers je package al installeren zodra je alleen het dependencybereik in `composer.json` bijwerkt en een release uitbrengt. ```json theme={null} "illuminate/support": "^12.0||^13.0" ``` Kleine problemen kun je ook na de release nog met een patchversie oplossen. Geef prioriteit aan installeerbaar zijn boven wachten op een perfecte ondersteuning. ### Releasenieuws bijhouden Manieren om tijdig op de hoogte te zijn van nieuwe releases. | Bron | Inhoud | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | GitHub Watch-functie | Ontvang e-mailmeldingen via "Watch → Custom → Releases" op de repository. Registreer naast framework ook de andere belangrijke packages | | [Officiële Laravel-blog](https://laravel.com/blog) | Aankondigingen van major-releases en uitleg van nieuwe features | | [Upgradegids in de officiële Laravel-documentatie](https://laravel.com/docs/upgrade) | Overzicht van breaking changes | | [Commitlog van laravel/framework](https://github.com/laravel/framework/commits/master) | Volg de commitlog rechtstreeks als je vooruit wilt lopen op wijzigingen in de volgende versie | ## Voorbeeld van een testmatrixconfiguratie Een voorbeeldworkflow die in GitHub Actions automatisch combinaties van meerdere Laravel- en PHP-versies test. ```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 ``` ### Het belang van fail-fast: false Met `fail-fast: false` gaan de tests van de andere combinaties door, ook als één combinatie faalt. Zo zie je in één CI-run bij welke versiecombinatie het probleem optreedt. ### De testmatrix stapsgewijs bijwerken Komt er een nieuwe Laravel-versie uit, dan voeg je die toe aan de matrix. Stop je de ondersteuning van een oude versie, dan verwijder je die uit de matrix. ```yaml theme={null} # Toevoegen zodra Laravel 14 is uitgebracht matrix: laravel: ["^13.0", "^14.0"] include: - laravel: "^14.0" testbench: "^11.0" - laravel: "^13.0" testbench: "^10.0" ``` ## Voorbeeld van composer.json Een volledig voorbeeld van een `composer.json` die meerdere versies ondersteunt. ```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 voor versie-upgrades * [ ] Verifieer de werking met de ontwikkelversie (`dev-master` / `@dev`) * [ ] Controleer breaking changes in de officiële upgradegids * [ ] Implementeer de ondersteuning voor de nieuwe versie in een testomgeving * [ ] Voeg de nieuwe versie toe aan de testmatrix en controleer in CI * [ ] Voeg de nieuwe versie toe aan de `illuminate/*`-vereisten in `composer.json` * [ ] Werk zo nodig de PHP-vereiste bij * [ ] Werk ook `orchestra/testbench` in `require-dev` bij naar de bijbehorende versie * [ ] Tag de nieuwe versie en laat die doorstromen naar Packagist * [ ] Werk de versiecompatibiliteitstabel in de README bij * [ ] Vermeld het einde van de ondersteuning duidelijk in de CHANGELOG/README * [ ] Verwijder de constraint van de oude versie uit `composer.json` * [ ] Verwijder de oude versie uit de testmatrix * [ ] Ruim de conditionele code voor de oude versie op ## Gerelateerde pagina's Uitleg over het ontwikkelen van Laravel-packages met de service provider als kern. Uitleg over het schrijven van packagetests met de Expectation API en datasets van Pest. ## Related topics - [Laravel-packages testen met Orchestra Testbench](/nl/advanced/package-testing.md) - [Statische analyse van packages (PHPStan / Larastan)](/nl/advanced/package-static-analysis.md) - [Uitgestelde service providers](/nl/advanced/deferred-provider.md) - [CHANGELOG en releasebeheer voor packages](/nl/advanced/package-changelog.md) - [Packageontwikkeling met Testbench Workbench](/nl/advanced/package-workbench.md)