> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # Versionskompatibilität von Paketen verwalten > Wartungsstrategien für Pakete bei Laravel- und PHP-Upgrades — von der Aktualisierung der composer.json bis zur Testmatrix in GitHub Actions. Laravel bringt jedes Jahr etwa im Februar/März eine neue Major-Version. Als Paketentwickler tragen Sie zur gesamten Ökosystem-Gesundheit bei, wenn Sie den Support für die neue Version zügig abschließen — und erhöhen zugleich die Vertrauenswürdigkeit Ihres Pakets. Diese Seite ist die Schwesterseite zu [Grundlagen der Paketentwicklung](/de/advanced/package-development) und setzt Grundwissen (Service Provider, Aufbau der `composer.json` usw.) voraus. ## Umgang mit Laravel-Major-Upgrades ### Ablauf Nehmen Sie die neue Version in den Dependency-Bereich auf. Wenn Sie ältere Versionen weiter unterstützen, listen Sie sie per `||` daneben. ```json theme={null} "require": { "php": "^8.2", "illuminate/support": "^12.0||^13.0" } ``` Ist die Umstellung abgeschlossen und werden alte Versionen nicht mehr unterstützt, entfernen Sie die alte Bedingung. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^13.0||^14.0" } ``` Halten Sie den Abhängigkeitsbaum klein, indem Sie nicht das gesamte `illuminate/framework`, sondern nur benötigte Komponenten wie `illuminate/support` einbinden. Lassen Sie Ihre Tests lokal oder in der CI mit der neuen Laravel-Version laufen. ```shell theme={null} composer update vendor/bin/pest ``` Wenn die Tests grün sind, ist die grundlegende Kompatibilität geprüft. Andernfalls passen Sie sich an geänderte APIs oder entfernte Methoden an. Fügen Sie die neue Laravel-Version in die CI-Matrix ein, damit die Kompatibilität kontinuierlich geprüft wird. Details siehe [Beispielkonfiguration der Testmatrix](#beispielkonfiguration-der-testmatrix). Taggen und releasen Sie eine neue Version mit der geänderten `composer.json`. Nutzer können dann per `composer update` auf die neue Laravel-Version umsteigen. ### Sich an offiziellen Paketen orientieren Sind Sie unsicher, ist die `composer.json` offizieller Laravel-Pakete die verlässlichste Referenz. * [laravel/socialite](https://github.com/laravel/socialite) * [laravel/horizon](https://github.com/laravel/horizon) * [laravel/telescope](https://github.com/laravel/telescope) Diese Pakete werden vom Laravel-Team gepflegt und sind bei neuen Versionen am schnellsten kompatibel. Auch das Notationsmuster für die `illuminate/*`-Versionen können Sie übernehmen. ## PHP-Versionsanforderungen aktualisieren Ein Laravel-Upgrade zieht oft auch die minimale PHP-Version nach oben. Aktualisieren Sie die PHP-Anforderung in der `composer.json` Ihres Pakets entsprechend. | Laravel | Minimale PHP-Version | | ---------- | -------------------- | | 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" } ``` ### Aktiv neue PHP-Features nutzen Wollen Sie Features ab PHP 8.3 (getypte Konstanten, neue Zufallsfunktionen usw.) nutzen, müssen Sie die Mindestanforderung anheben. Das ist SemVer-technisch ein Breaking Change und gehört daher in ein Major-Upgrade. ```json theme={null} "require": { "php": "^8.3", "illuminate/support": "^12.0||^13.0" } ``` Wenn Sie die minimale PHP-Version anheben, können Nutzer mit älterem PHP das Paket nicht mehr aktualisieren. Kommunizieren Sie das frühzeitig in README und CHANGELOG. ## Strategie zur Einstellung alter Versionen Alte Versionen unbegrenzt zu pflegen erhöht langfristig die Wartungskosten. Eine klare Support-Policy und der geplante Wegfall alter Versionen halten Ihr Paket gesund. ### Wann Sie Support beenden Ein gängiger Ansatz ist, sich an Laravels Support-Zeitraum zu orientieren. Laravel bietet pro Version 18 Monate Bugfixes und 2 Jahre Security-Fixes. Wenn Ihr Paket derselben Policy folgt, wissen Nutzer, was sie erwarten dürfen. | Kriterium | Erläuterung | | ------------------------------------- | ---------------------------------------------------------------------------- | | Ende des offiziellen Laravel-Supports | Sie beenden den Support parallel zur betreffenden Laravel-Version | | Nutzung | Wenn die Downloads einer alten Version laut Packagist-Statistik gering sind | | Feature-Hürde | Wenn alte Versionen die Implementierung neuer Features stark verkomplizieren | ### Support-Policy im README dokumentieren Damit Nutzer korrekte Erwartungen haben, dokumentieren Sie die Policy im `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. ``` ### Kosten weiterer Alt-Unterstützung Der Weiterbetrieb alter Versionen verursacht insbesondere: * **Doppelte Bugfixes** — derselbe Fehler in mehreren Branches. * **Bedingungscode** — Komplexität durch Verzweigung nach Version. * **Aufgeblähte Testmatrix** — CI-Laufzeiten steigen. * **Kompliziertere Security-Patches** — sichere Backports auch für alte Versionen. Ein sauberer Abschluss alter Versionen ermuntert zugleich Nutzer, ihre Umgebung zu modernisieren. ## Vorteile früher Anpassung Wenn Ihr Paket zeitgleich mit dem Laravel-Release kompatibel ist, können Nutzer sofort migrieren — ein starkes Vertrauenssignal. ### Vorabprüfung mit der Entwicklungsversion Laravel veröffentlicht keine Beta/RC, stattdessen können Sie mit `dev-master` oder `@dev` die kommende Version installieren. So gelingt eine Zero-Day-Anpassung. ```shell theme={null} # Kommende Version über dev-master installieren composer require laravel/framework:dev-master --no-update composer update vendor/bin/pest ``` Alternativ über den `@dev`-Constraint. ```shell theme={null} composer require laravel/framework:^14.0@dev --no-update composer update vendor/bin/pest ``` Mit `minimum-stability: dev` können Sie Abhängigkeiten zu Entwicklungsversionen auflösen. ```json theme={null} { "minimum-stability": "dev", "prefer-stable": true } ``` Mit `prefer-stable: true` haben stabile Versionen Vorrang, sofern sie existieren. Sie können also gegen dev testen und wechseln automatisch zurück auf stable. ### Der erste Schritt ist nur eine Änderung an composer.json Auch vor der vollständigen Kompatibilitätsprüfung genügt es, den Dependency-Range in der `composer.json` zu aktualisieren und ein Release zu veröffentlichen — dann können Nutzer das Paket installieren. ```json theme={null} "illuminate/support": "^12.0||^13.0" ``` Kleine Fehler beheben Sie danach in einem Patch-Release. Priorisieren Sie die Installierbarkeit vor Perfektion. ### Wie Sie Release-Informationen im Blick halten Um neue Releases rechtzeitig mitzubekommen: | Quelle | Inhalt | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | GitHub-Watch | „Watch → Custom → Releases" ergibt E-Mail-Benachrichtigungen. Registrieren Sie neben framework auch weitere wichtige Pakete. | | [Offizieller Laravel-Blog](https://laravel.com/blog) | Ankündigungen und Feature-Erläuterungen zu Major-Releases | | [Offizielle Upgrade Guides](https://laravel.com/docs/upgrade) | Übersicht der Breaking Changes | | [Commit-Log von laravel/framework](https://github.com/laravel/framework/commits/master) | Für einen Blick auf die nächste Version vor dem offiziellen Release | ## Beispielkonfiguration der Testmatrix Beispiel einer GitHub-Actions-Workflow, die mehrere Laravel- und PHP-Kombinationen automatisiert prüft. ```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 ``` ### Bedeutung von `fail-fast: false` Mit `fail-fast: false` laufen bei einer fehlgeschlagenen Kombination die übrigen weiter. So sehen Sie in einem CI-Lauf, welche Kombinationen problematisch sind. ### Testmatrix schrittweise pflegen Nehmen Sie neu erschienene Laravel-Versionen in die Matrix auf und entfernen Sie alte, deren Support Sie beendet haben. ```yaml theme={null} # Nach dem Release von Laravel 14 aufnehmen matrix: laravel: ["^13.0", "^14.0"] include: - laravel: "^14.0" testbench: "^11.0" - laravel: "^13.0" testbench: "^10.0" ``` ## Beispiel composer.json Vollständiges Beispiel für Multi-Version-Support in einer `composer.json`. ```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 } ``` ## Checkliste für Versions-Upgrades * [ ] Kompatibilität mit der Dev-Version (`dev-master` / `@dev`) prüfen * [ ] Breaking Changes anhand des offiziellen Upgrade Guide sichten * [ ] Neue Version in einer Test-Umgebung anpassen * [ ] Neue Version in die Testmatrix aufnehmen und CI grün stellen * [ ] `illuminate/*`-Anforderungen in `composer.json` um die neue Version ergänzen * [ ] Bei Bedarf die PHP-Anforderung aktualisieren * [ ] `orchestra/testbench` in `require-dev` auf die passende Version bringen * [ ] Neue Version taggen und auf Packagist bereitstellen * [ ] Kompatibilitätstabelle in README aktualisieren * [ ] CHANGELOG/README um Support-Ende ergänzen * [ ] Alte Version aus `composer.json` entfernen * [ ] Alte Version aus der Testmatrix entfernen * [ ] Alten Bedingungscode aufräumen ## Verwandte Seiten Wie Sie Laravel-Pakete rund um Service Provider entwickeln. Pakettests mit Expectation API und Datasets in Pest. ## Related topics - [Deferred Service Provider](/de/advanced/deferred-provider.md) - [Paketentwicklung mit Testbench Workbench](/de/advanced/package-workbench.md) - [GitHub-Actions-Pinning und Sicherheit](/de/advanced/github-actions-pinning.md) - [Laravel-Pakete mit Orchestra Testbench testen](/de/advanced/package-testing.md) - [CHANGELOG und Release-Management für Pakete](/de/advanced/package-changelog.md)