Composer-Abhaengigkeiten bei Symfony-Major-Upgrades verwalten

1. Warum Composer-Konflikte bei Major-Upgrades unausweichlich sind

Bei jedem Symfony-Major-Upgrade ist die eigentliche Kernfrage selten, ob Symfony selbst kompatibel ist, sondern ob die zwanzig bis fuenfzig weiteren Composer-Pakete im Projekt mitziehen. Ein API-Client-Bundle, ein PDF-Generator, ein Payment-SDK: jedes dieser Pakete hat eigene Versionsanforderungen an Symfony-Komponenten, PHP und oft auch aneinander. Composer-Konflikte entstehen genau dort, wo zwei Pakete widerspruechliche Anforderungen an dieselbe Abhaengigkeit stellen, etwa wenn Paket A symfony/http-foundation ^6.0 braucht und Paket B bereits ^7.0 voraussetzt.

Diese Konflikte sind kein Zeichen eines schlecht gepflegten Projekts, sondern eine strukturelle Eigenschaft jedes groesseren PHP-Oekosystems mit vielen unabhaengigen Maintainer-Teams. Der Unterschied zwischen einem reibungslosen und einem schmerzhaften Symfony-Upgrade liegt fast immer darin, wie systematisch ein Team diese Composer-Konflikte analysiert, statt sie mit pauschalen Loesungen wie --ignore-platform-reqs zu umgehen, was Inkompatibilitaeten nur in die Produktion verschiebt, statt sie zu loesen.

Dieser Artikel zeigt, wie man Composer-Fehlermeldungen bei Symfony-Upgrades korrekt interpretiert, mit composer why-not die tatsaechliche Ursache von Konflikten findet, und wie Version-Constraints, Platform-Konfiguration und eine saubere CI-Pipeline zusammenspielen, um Major-Upgrades planbar statt riskant zu machen.

2. Composer-Fehlermeldungen richtig lesen

Die Meldung "Your requirements could not be resolved to an installable set of packages" ist die haeufigste Fehlermeldung bei Symfony-Major-Upgrades und wird oft als undurchsichtig empfunden, ist aber tatsaechlich strukturiert aufgebaut. Composer listet darunter jede einzelne Anforderungskette, die zum Konflikt fuehrt, in der Form "Paket A requires Paket B (Version X), found Version Y but it conflicts with your requirements". Wer diese Kette von unten nach oben liest, findet fast immer direkt das blockierende Paket.

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - acme/pdf-generator 2.3.0 requires symfony/http-foundation ^6.0
      -> satisfiable by symfony/http-foundation[v6.4.11].
    - Root composer.json requires symfony/http-foundation ^7.2
      -> satisfiable by symfony/http-foundation[v7.2.0].
    - acme/pdf-generator 2.3.0 conflicts with symfony/http-foundation v7.2.0.

  To resolve this, you can:
    1. Upgrade acme/pdf-generator to a version supporting Symfony 7 (check its changelog)
    2. Downgrade symfony/http-foundation temporarily (not recommended for a full upgrade)
    3. Find an alternative package if acme/pdf-generator has no Symfony 7 release

Der praktische Schluessel liegt im letzten Satz der Kette: "conflicts with". Dieser Satz benennt exakt das Paket und die Version, die den Konflikt ausloesen. Composer selbst schlaegt seit Version 2.3 sogar Loesungsvorschlaege vor, etwa das betroffene Paket zu aktualisieren oder eine alternative Version zu suchen, was das manuelle Debugging deutlich verkuerzt gegenueber aelteren Composer-Versionen mit weniger aussagekraeftigen Fehlermeldungen.

3. composer why und why-not gezielt einsetzen

Waehrend eine einzelne Fehlermeldung oft nur einen Konflikt zeigt, gibt composer why-not einen vollstaendigen Ueberblick, welche Pakete eine bestimmte Zielversion blockieren, noch bevor man das eigentliche Upgrade startet. Der Befehl composer why-not symfony/framework-bundle 7.2 zeigt jedes installierte Paket, dessen aktuelle Version mit Symfony 7.2 nicht kompatibel ist, inklusive der genauen Versionsbedingung, die den Konflikt verursacht.

# Before starting the upgrade: check what blocks Symfony 7.2 right now
composer why-not symfony/framework-bundle 7.2

# Output shows every blocking package with its exact constraint, for example:
# acme/pdf-generator 2.3.0 requires symfony/http-foundation (^6.0)
# acme/legacy-cache  1.8.2 requires symfony/cache (^5.4|^6.0)

# The inverse question: why is a package installed at its current version?
composer why symfony/http-foundation

# Shows the full dependency chain that pins this version,
# useful when a transitive dependency forces an old constraint

Diese beiden Befehle zusammen ergeben ein vollstaendiges Bild vor jedem Symfony-Upgrade: why-not zeigt, was ein Ziel-Upgrade blockiert, why zeigt, warum ein bestehendes Paket in seiner aktuellen Version festgehalten wird. Ein Team, das beide Befehle vor dem eigentlichen composer require ausfuehrt, kennt den vollstaendigen Umfang der noetigen Vorarbeiten, statt sie erst durch gescheiterte Installationsversuche zu entdecken.

4. Version-Constraints strategisch lockern

Ein haeufiger Fehler bei Symfony-Upgrades ist, Version-Constraints entweder zu eng zu halten, was jedes zukuenftige Upgrade erschwert, oder sie panisch mit * komplett zu oeffnen, was unkontrollierte Breaking Changes ins Projekt einschleust. Die bewaehrte Mitte ist die Caret-Notation ^7.2, die Minor- und Patch-Updates innerhalb derselben Major-Version erlaubt, aber nie automatisch auf eine neue Major-Version springt, wodurch Breaking Changes immer eine bewusste, manuelle Entscheidung bleiben.

Fuer Pakete, die den eigentlichen Konflikt verursachen, lohnt sich vor einem kompletten Ersatz zunaechst ein Blick in deren Changelog: haeufig existiert bereits eine neuere Major-Version des Pakets selbst, die die neue Symfony-Version unterstuetzt, aber noch nicht in der eigenen composer.json erlaubt ist, weil die Versionsbedingung zu eng formuliert wurde.

{
    "require": {
        "php": ">=8.3",
        "symfony/framework-bundle": "^7.2",

        // Before: too tight, blocks the vendor's own Symfony 7 release
        // "acme/pdf-generator": "^2.3"

        // After: widened after checking the changelog, 3.0 supports Symfony 7
        "acme/pdf-generator": "^2.3 || ^3.0"
    }
}

Die Schreibweise ^2.3 || ^3.0 erlaubt Composer, entweder bei der bisherigen Major-Version zu bleiben oder auf die neue zu wechseln, je nachdem, was mit den uebrigen Constraints im Projekt kompatibel ist. Das ist besonders in einer Uebergangsphase nuetzlich, in der noch nicht sicher ist, ob die neue Paketversion ohne eigene Breaking Changes im Anwendungscode auskommt.

5. Platform-Config und Conflict-Eintraege nutzen

Die platform-Konfiguration in composer.json erlaubt, eine bestimmte PHP-Version zu simulieren, unabhaengig davon, welche PHP-Version lokal tatsaechlich installiert ist. Das ist besonders in Teams nuetzlich, in denen einzelne Entwickler noch auf einer aelteren PHP-Version arbeiten, waehrend das Zielsystem bereits die neue Version fuer das Symfony-Upgrade nutzt, weil Composer sonst faelschlicherweise Pakete als kompatibel meldet, die tatsaechlich nur mit der lokal installierten, aelteren PHP-Version funktionieren.

Der conflict-Schluessel in composer.json ist das Gegenstueck zu require: er erklaert explizit, dass bestimmte Paketversionen niemals gemeinsam mit dem eigenen Projekt installiert werden duerfen. Das ist nuetzlich, wenn ein bekanntes Bundle in einer bestimmten Versionsspanne einen Bug hat, der erst mit dem Symfony-Upgrade sichtbar wurde, und verhindert, dass ein Teammitglied versehentlich auf genau diese fehlerhafte Version zurueckfaellt.

{
    "config": {
        "platform": {
            "php": "8.3.0"
        }
    },
    "conflict": {
        "acme/legacy-cache": "<2.0",
        "doctrine/dbal": "3.6.0"
    }
}

In diesem Beispiel verhindert der conflict-Eintrag zuverlaessig, dass acme/legacy-cache in einer Version unterhalb von 2.0 installiert wird, und schliesst zusaetzlich eine spezifische, als fehlerhaft bekannte Patch-Version von doctrine/dbal explizit aus. Composer respektiert diese Regel bei jedem composer update, auch wenn eine transitive Abhaengigkeit versuchen wuerde, die ausgeschlossene Version zu installieren.

6. Path-Repositories fuer parallele Versionstests

Wenn ein internes Bundle selbst noch nicht fuer die neue Symfony-Version vorbereitet ist, aber im selben Zug aktualisiert werden soll, bieten Path-Repositories eine Moeglichkeit, das interne Paket lokal zu bearbeiten, waehrend das Hauptprojekt bereits gegen die neue Symfony-Version testet, ohne staendig neue Versionen ins interne Package-Repository pushen zu muessen. Composer verlinkt das lokale Verzeichnis dabei symbolisch, sodass Aenderungen am internen Bundle sofort im Hauptprojekt sichtbar sind.

{
    "repositories": [
        {
            "type": "path",
            "url": "../acme-audit-log-bundle",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "acme/audit-log-bundle": "@dev"
    }
}

Diese Konfiguration eignet sich hervorragend fuer die Uebergangsphase eines Symfony-Upgrades, in der ein internes Bundle parallel zum Hauptprojekt an die neue Version angepasst wird. Sobald die Anpassung abgeschlossen ist und eine echte Versionsnummer ueber das normale Package-Repository verfuegbar ist, wird der Path-Repository-Eintrag wieder entfernt und die reguelaere Versionsbedingung tritt an seine Stelle.

7. Lockfile-Strategie in Branches und Merges

Waehrend eines laengeren Symfony-Upgrades, das in einem separaten Feature Branch entwickelt wird, entstehen fast zwangslaeufig Merge-Konflikte in der composer.lock-Datei, sobald der Hauptbranch parallel weitere Abhaengigkeits-Updates erhaelt. Ein manuelles Aufloesen dieser Konflikte durch direktes Bearbeiten der JSON-Struktur ist fehleranfaellig, weil die Datei Hash-Werte enthaelt, die nach einer manuellen Aenderung nicht mehr zum tatsaechlichen Zustand passen.

Der zuverlaessige Weg ist, die composer.lock beim Merge-Konflikt komplett zu verwerfen und stattdessen composer update --lock auf Basis der gemergten composer.json neu auszufuehren, was eine frische, konsistente Lock-Datei erzeugt. Dieser Ansatz kostet zwar eine erneute Aufloesung aller Abhaengigkeiten, verhindert aber die deutlich schwerer zu findenden Fehler, die aus einer inkonsistenten, manuell zusammengefuegten Lock-Datei entstehen.

# On merge conflict in composer.lock: discard it entirely
git checkout --theirs composer.lock

# Regenerate a consistent lock file from the merged composer.json
composer update --lock

# Verify no unintended version changes slipped in
git diff composer.lock

Der abschliessende git diff composer.lock ist kein optionaler Schritt: er zeigt, ob durch die Neugenerierung unbeabsichtigt zusaetzliche Pakete aktualisiert wurden, die nicht Teil des eigentlichen Symfony-Upgrades sein sollten. Ein sauberer Merge-Prozess trennt bewusst gewaehlte Versionsupdates von versehentlichen Nebeneffekten der Lock-Datei-Neugenerierung.

8. CI-Pipeline: Dependency-Updates sicher testen

Eine CI-Pipeline, die Symfony-Upgrades absichern soll, braucht mindestens zwei getrennte Jobs: einen, der composer install mit der eingecheckten composer.lock ausfuehrt, um zu verifizieren, dass das Projekt exakt mit den getesteten Versionen funktioniert, und einen zweiten, optionalen Job, der composer update ohne Lock-Datei ausfuehrt, um fruehzeitig zu erkennen, ob neue Paketversionen in der Zukunft Probleme verursachen werden, bevor ein Entwickler das naechste Mal manuell aktualisiert.

<?php
declare(strict_types=1);

// scripts/check-composer-drift.php: run in CI as an early-warning job
// Compares locked versions against the latest allowed versions per constraint

use Composer\Semver\VersionParser;

$lockData = json_decode(file_get_contents(__DIR__ . '/../composer.lock'), true, flags: JSON_THROW_ON_ERROR);

$outdatedCount = 0;
foreach ($lockData['packages'] as $package) {
    if (str_starts_with($package['name'], 'symfony/')) {
        // In a real script: compare against Packagist metadata here
        $outdatedCount++;
    }
}

fwrite(STDOUT, sprintf("Tracked %d Symfony packages in composer.lock\n", $outdatedCount));

Ein solcher Drift-Check, kombiniert mit einem regelmaessig laufenden composer outdated --direct-Job, gibt einem Team fruehzeitige Signale, bevor ein Symfony-Major-Upgrade ansteht, statt es unvorbereitet mit einem einzigen grossen Composer-Konflikt zu konfrontieren. Diese kontinuierliche Beobachtung ist der wichtigste Unterschied zwischen einem Team, das Upgrades planbar durchfuehrt, und einem, das sie als riskantes Grossereignis alle paar Jahre fuerchtet.

9. Strategien im direkten Vergleich

Die folgende Tabelle vergleicht die gaengigen Strategien zum Loesen von Composer-Konflikten bei Symfony-Major-Upgrades.

Die erste Zeile der Tabelle bleibt eine der haeufigsten Quellen von Produktionsproblemen nach einem Symfony-Upgrade, weil sie Inkompatibilitaeten nicht loest, sondern lediglich fuer Composer unsichtbar macht. Die uebrigen drei Strategien lassen sich gut kombinieren und bilden zusammen einen soliden Prozess fuer jedes groessere Upgrade.

10. Zusammenfassung

Composer-Konflikte bei Symfony-Major-Upgrades sind eine strukturelle Eigenschaft jedes Projekts mit mehreren unabhaengig gepflegten Abhaengigkeiten, kein Zeichen mangelnder Codequalitaet. Composer-Fehlermeldungen sind bei genauem Lesen strukturiert aufgebaut und benennen das blockierende Paket direkt. composer why-not liefert vor jedem Upgrade einen vollstaendigen Ueberblick ueber blockierende Abhaengigkeiten, waehrend gezielt gelockerte Constraints mit ||-Notation Uebergangsphasen sauber abbilden, ohne unkontrollierte Breaking Changes zuzulassen.

Platform-Konfiguration und conflict-Eintraege in der composer.json steuern das Verhalten praezise, waehrend Path-Repositories parallele Entwicklung an internen Bundles ermoeglichen. Eine saubere Lockfile-Strategie bei Merge-Konflikten und eine CI-Pipeline mit Drift-Checks machen aus einem gefuerchteten Grossereignis einen planbaren, wiederholbaren Prozess. Teams, die diese Werkzeuge kombinieren, vermeiden riskante Abkuerzungen wie --ignore-platform-reqs und bringen Symfony-Major-Upgrades kontrolliert in Produktion.

11. FAQ: Composer-Konflikte bei Symfony-Upgrades