composer.lock-Merge-Konflikte in Magento-Projekten sauber lösen

1. Warum composer.lock in Magento-Projekten so oft Konflikte verursacht

Magento-Projekte binden typischerweise Dutzende bis Hunderte Composer-Pakete ein, das Kernsystem selbst, zahlreiche Drittanbieter-Erweiterungen und eigene Module mit ihren jeweiligen Abhängigkeiten. Jede noch so kleine Aenderung an einer Versionsanforderung in composer.json, etwa das Anheben eines einzelnen Pakets um eine Minor-Version, schreibt Composer beim nächsten composer update quer durch die gesamte composer.lock neu, weil sich Abhängigkeitsauflösungen gegenseitig beeinflussen können.

Arbeiten mehrere Entwickler gleichzeitig an unterschiedlichen Feature-Branches und aktualisiert jeder davon unabhängig voneinander Pakete, ist ein Konflikt beim Zusammenführen praktisch unausweichlich, selbst wenn die eigentlichen inhaltlichen Aenderungen an composer.json gar nicht überlappen. Git kennt die semantische Struktur der Datei nicht und behandelt sie wie reinen Text, was bei einer so stark vernetzten Datenstruktur fast zwangsläufig zu Konflikten führt.

2. Den Aufbau von composer.lock verstehen

composer.lock speichert für jedes installierte Paket die exakt aufgelöste Version, den Quell-Commit-Hash und alle transitiven Abhängigkeiten, getrennt in die Bereiche packages für Produktionsabhängigkeiten und packages-dev für Entwicklungsabhängigkeiten. Am Anfang der Datei steht zusätzlich ein content-hash-Feld, ein Hash über die relevanten Teile der zugehörigen composer.json, mit dem Composer bei jedem Aufruf prüft, ob die Lock-Datei noch zur aktuellen Anforderungsdatei passt.

Genau dieser content-hash ist der Grund, warum ein manuell zusammengeführter Konflikt selbst dann problematisch ist, wenn die restlichen Einträge korrekt erscheinen: Passt der Hash nicht mehr exakt zur composer.json, meldet Composer bei jedem Befehl eine Warnung, dass die Lock-Datei veraltet ist, ein untrüglicher Hinweis darauf, dass beim Merge etwas nicht sauber zusammengeführt wurde.

3. Wie ein klassischer Merge-Konflikt aussieht und warum manuelles Lösen riskant ist

Beim Zusammenführen zweier Branches, die composer.lock unterschiedlich verändert haben, markiert Git die betroffenen Blöcke mit den bekannten <<<<<<<, ======= und >>>>>>>-Trennern, oft mitten in einem Paketeintrag mit Versionsnummer, Hash und Abhängigkeitsliste. Wer diese Marker von Hand entfernt und eine der beiden Varianten auswählt oder Zeilen aus beiden kombiniert, erzeugt eine Datei, die syntaktisch gültiges JSON sein kann, aber inhaltlich inkonsistent ist, etwa wenn ein Paket in einer Version referenziert wird, deren Abhängigkeiten gar nicht mehr zu den anderen Einträgen passen.

Das eigentliche Risiko liegt darin, dass diese Inkonsistenz nicht sofort auffällt. composer install installiert zunächst genau das, was in der manuell reparierten Datei steht, ohne die innere Konsistenz zu prüfen, Probleme zeigen sich möglicherweise erst Wochen später durch subtile Bugs, die auf eine falsch aufgelöste transitive Abhängigkeit zurückgehen.

4. Der korrekte Weg: composer.lock verwerfen und neu auflösen lassen

Die zuverlässige Lösung ignoriert den Konflikt in composer.lock bewusst und lässt stattdessen Composer selbst die Datei neu berechnen. Dafür wird composer.lock zunächst aus einem der beiden Branches vollständig übernommen, üblicherweise aus dem Zielbranch, in den gemergt wird, und anschliessend führt ein composer update --lock die Abhängigkeitsauflösung frisch auf Basis der bereits korrekt gemergten composer.json durch.

Der Parameter --lock ist dabei entscheidend, denn er weist Composer an, nur die Lock-Datei entsprechend der composer.json neu zu berechnen, ohne dabei tatsächlich Pakete im vendor-Verzeichnis zu aktualisieren oder neu zu installieren. Nach diesem Schritt ist die composer.lock garantiert konsistent, weil sie aus einem echten Composer-Lauf stammt und nicht aus einer manuellen Textzusammenführung.

# Während eines Merge-Konflikts: composer.lock aus dem Zielbranch übernehmen
git checkout --ours composer.lock
# oder je nach gewünschter Ausgangsbasis
git checkout --theirs composer.lock

# composer.json ist bereits korrekt gemergt, Lock-Datei neu berechnen lassen
composer update --lock

# Ergebnis prüfen und committen
git add composer.json composer.lock
git commit

5. Gezieltes Update einzelner Pakete nach dem Merge

Ein vollständiger composer update ohne Paketangabe aktualisiert potenziell weit mehr Pakete als nötig, weil Composer dabei versucht, innerhalb der in composer.json erlaubten Versionsbereiche die jeweils neuesten kompatiblen Versionen zu finden. Für einen sauberen Merge-Konflikt reicht das oft nicht, das eigentliche Ziel ist lediglich, die Lock-Datei wieder konsistent zur composer.json zu bringen, nicht zusätzliche, ungeplante Paket-Updates einzuschleusen.

Wer nur die tatsächlich betroffenen Pakete aktualisieren möchte, gibt sie explizit an und ergänzt --with-dependencies, damit Composer auch die transitive Abhängigkeitskette dieser Pakete mit auflöst, ohne den Rest des Abhängigkeitsbaums anzurühren.

# Nur ein bestimmtes Paket samt Abhängigkeiten neu auflösen
composer update vendor/paket-name --with-dependencies

# Mehrere betroffene Pakete gezielt aktualisieren
composer update vendor/paket-a vendor/paket-b --with-dependencies

6. Warum ein automatischer Merge-Driver für composer.lock keine gute Idee ist

In .gitattributes lässt sich für bestimmte Dateien ein Merge-Verhalten wie merge=union konfigurieren, das bei Konflikten automatisch beide Varianten zeilenweise zusammenführt. Für composer.lock ist das keine gute Idee, weil eine union-Zusammenführung schlicht beide Versionen eines Pakets nebeneinander in die Datei schreibt, ohne Rücksicht darauf, dass ein Paket nur in genau einer Version vorkommen darf, das Ergebnis ist praktisch immer ungültig oder inkonsistent.

Auch ein eigener, spezialisierter Merge-Driver, der versucht, die JSON-Struktur intelligent zusammenzuführen, löst das Kernproblem nicht, denn selbst ein syntaktisch korrektes Zusammenführen zweier Paketlisten sagt nichts darüber aus, ob die daraus resultierende Kombination von Versionen überhaupt eine gültige Abhängigkeitsauflösung darstellt. Diese Prüfung kann zuverlässig nur der Composer-Dependency-Resolver selbst leisten, weshalb der Weg über composer update --lock jedem Automatismus in Git vorzuziehen ist.

7. Nach dem Merge validieren: composer validate und Plattform-Checks

Bevor der gelöste Merge-Konflikt committet wird, lohnt sich eine kurze Validierungsrunde. composer validate prüft, ob composer.json und composer.lock strukturell zueinander passen und der content-hash korrekt ist, während composer check-platform-reqs zusätzlich sicherstellt, dass alle aufgelösten Pakete tatsächlich mit der lokal installierten PHP-Version und den vorhandenen PHP-Extensions kompatibel sind.

Für Magento-Projekte empfiehlt sich zusätzlich ein testweises composer install --dry-run, das simuliert, welche Pakete installiert würden, ohne tatsächlich Aenderungen am vendor-Verzeichnis vorzunehmen, ein schneller Weg, um offensichtliche Inkonsistenzen zu erkennen, bevor der Merge in einen gemeinsam genutzten Branch gelangt.

# Struktur und content-hash prüfen
composer validate --strict

# Kompatibilität mit der lokalen PHP-Umgebung prüfen
composer check-platform-reqs

# Simulierte Installation ohne Aenderungen am vendor-Verzeichnis
composer install --dry-run

8. Workflow im Team: Lock-File-Politik, Feature-Branches und Rebase

Ein Grossteil der composer.lock-Konflikte lässt sich vermeiden, indem Paket-Updates als eigene, klar abgegrenzte Commits erfolgen, statt sie beiläufig in einem thematisch anderen Feature-Branch mitzuführen. Ein Team, das eine klare Regel etabliert, wonach Composer-Updates nur über dedizierte, kurzlebige Branches laufen, die zügig gemergt werden, reduziert die Wahrscheinlichkeit, dass mehrere parallele Branches gleichzeitig an derselben Lock-Datei arbeiten.

Bei länger laufenden Feature-Branches hilft regelmäßiges Rebasing oder Mergen des Zielbranches in den Feature-Branch, weil dadurch composer.lock-Konflikte frühzeitig und in kleineren, überschaubareren Schritten auftreten, statt sich am Ende zu einem grossen, schwer aufzulösenden Konflikt aufzustauen.

9. CI-Absicherung gegen inkonsistente Lock-Dateien

Als letzte Sicherheitsnetz-Ebene sollte jede Magento-CI-Pipeline einen Job enthalten, der composer install --no-dev --prefer-dist mit striktem Fehlerverhalten ausführt, idealerweise ergänzt um composer validate --strict als vorgeschalteten Schritt. Composer bricht bei einem inkonsistenten content-hash mit einer klaren Fehlermeldung ab, statt stillschweigend eine möglicherweise falsche Abhängigkeitskombination zu installieren.

Ein solcher Pipeline-Schritt fängt genau die Fälle ab, in denen ein manuell reparierter, aber inhaltlich inkonsistenter Merge unbemerkt in den Zielbranch gelangt ist, und verhindert, dass ein fehlerhafter Zustand erst beim Deployment auf einer Produktionsumgebung auffällt.

# Beispielhafter CI-Job zur Absicherung der Lock-Datei
composer-check:
  script:
    - composer validate --strict
    - composer install --no-dev --prefer-dist

10. Zusammenfassung

11. FAQ: composer.lock-Konflikte: Das Wichtigste auf einen Blick