Zum Hauptinhalt springen
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 und setzt Grundwissen (Service Provider, Aufbau der composer.json usw.) voraus.

​
Umgang mit Laravel-Major-Upgrades

​
Ablauf

1

`require` in composer.json aktualisieren

Nehmen Sie die neue Version in den Dependency-Bereich auf. Wenn Sie ältere Versionen weiter unterstützen, listen Sie sie per || daneben.
"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.
"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.
2

Tests mit der neuen Version ausführen

Lassen Sie Ihre Tests lokal oder in der CI mit der neuen Laravel-Version laufen.
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.
3

Neue Version in die Testmatrix in GitHub Actions aufnehmen

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.
4

Support-Release veröffentlichen

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. 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.
LaravelMinimale PHP-Version
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"
}

​
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. 
"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.
KriteriumErläuterung
Ende des offiziellen Laravel-SupportsSie beenden den Support parallel zur betreffenden Laravel-Version
NutzungWenn die Downloads einer alten Version laut Packagist-Statistik gering sind
Feature-HürdeWenn 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. 
## 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. 
# Kommende Version über dev-master installieren
composer require laravel/framework:dev-master --no-update
composer update
vendor/bin/pest
Alternativ über den @dev-Constraint. 
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. 
{
    "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. 
"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:
QuelleInhalt
GitHub-Watch„Watch → Custom → Releases” ergibt E-Mail-Benachrichtigungen. Registrieren Sie neben framework auch weitere wichtige Pakete.
Offizieller Laravel-BlogAnkündigungen und Feature-Erläuterungen zu Major-Releases
Offizielle Upgrade GuidesÜbersicht der Breaking Changes
Commit-Log von laravel/frameworkFü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. 
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. 
# 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. 
{
    "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

Grundlagen der Paketentwicklung

Wie Sie Laravel-Pakete rund um Service Provider entwickeln.

Fortgeschrittenes Testen mit Pest

Pakettests mit Expectation API und Datasets in Pest.
Zuletzt geändert am 13. Juli 2026

Verwandte Themen

Deferred Service ProviderPaketentwicklung mit Testbench WorkbenchGitHub-Actions-Pinning und SicherheitLaravel-Pakete mit Orchestra Testbench testenCHANGELOG und Release-Management für Pakete