Praktischer Blueprint: typsichere Collections in PHP-Projekten

Im Alltag landet in vielen Teams irgendwann dieselbe Diskussion auf dem Tisch. Warum tauchen in kritischen Stellen immer wieder unklare Collections auf, obwohl alle sauber arbeiten wollen?

Das ist nervig, weil es sich in Reviews und bei Änderungen ständig wiederholt. Genau deshalb wird es jetzt konkret: Wie sieht ein Teamstandard aus, den ich morgen in einem bestehenden PHP-Projekt einführen kann?

Was ich damit im Alltag erreichen will

Ich will drei Dinge gleichzeitig:

• klare Typverträge für Collections,
• weniger Fehler an Integrationsgrenzen,
• bessere Lesbarkeit in Reviews.

Nicht mit einem großen Rewrite, sondern mit kleinen, überprüfbaren Schritten.

1) Namenskonventionen zuerst festlegen

Ohne klare Namen wird jede Typdiskussion unnötig schwer. Ich lege deshalb zuerst einfache Regeln fest.

Mein Standard:

• *Collection für fachliche Sammlungen,
• *List nur für Reihenfolge-Container,
• *Map für Key-Value-Strukturen,
• keine generischen Namen wie DataContainer oder Items ohne Domänenbezug.

Beispiel: UserCollection, InvoiceList, FeatureFlagMap.

Damit versteht das Team sofort, welche Semantik eine Struktur hat.

2) Einheitliche PHPDoc-Templates einführen

Als Nächstes standardisiere ich die Typannotationen. Nicht jede Klasse erfindet ihre eigene Schreibweise.

Ein minimales Collection-Grundmuster:

<?php
 
/**
 * @template T of object
 * @implements \IteratorAggregate<int, T>
 */
final class TypedCollection implements \IteratorAggregate, \Countable
{
    /** @var list<T> */
    private array $items;
 
    /** @param list<T> $items */
    public function __construct(array $items)
    {
        $this->items = $items;
    }
 
    /** @return \ArrayIterator<int, T> */
    public function getIterator(): \ArrayIterator
    {
        return new \ArrayIterator($this->items);
    }
 
    public function count(): int
    {
        return count($this->items);
    }
}

Für fachliche Collections baue ich auf diesem Muster auf, statt überall neue Varianten zu mischen.

3) CI-Gates verbindlich machen

Ein Standard wirkt nur, wenn er überprüft wird. Darum gehören PHPStan oder Psalm als Pflicht in die Pipeline.

Ich nutze dabei klare Gates:

• statische Analyse muss grün sein,
• neue mixed-Einführungen brauchen Begründung,
• Suppressions brauchen Ticket und Rückbaufrist.

So bleibt Typsicherheit ein Prozess, nicht nur ein Papierbeschluss.

4) Anti-Patterns aktiv verbieten

Ein guter Standard braucht auch klare Verbote. Ich markiere vorab die Muster, die wir nicht mehr zulassen.

Typische Anti-Patterns:

• array<string, mixed> als Dauerlösung in Domänenklassen,
• fachliche Collections, die intern mehrere unklare Typfamilien mischen,
• breite Union-Typen im Kernmodell,
• stilles Verschlucken von Analysewarnungen.

Das spart später viele Endlosdiskussionen.

5) Rollout in vier Etappen planen

Ich führe den Standard nie als Big Bang ein. Ich arbeite in klaren Etappen.

Etappe 1: Kernpfade

Domänennahe Collections zuerst, dort ist der Nutzen am größten.

Etappe 2: Service-Grenzen

Repositories, Mapper und Integrationsadapter nachziehen.

Etappe 3: Legacy-Zonen

Bereiche mit hoher Fehlerquote priorisieren, nicht nach Dateialter.

Etappe 4: Härtung

Analyse-Level schrittweise erhöhen und Alt-Suppressions zurückbauen.

So bleibt Delivery stabil, während die Typqualität sichtbar steigt.

Ein Kontrollbild für Reviews

In Reviews stelle ich bei jeder neuen Collection dieselben Fragen:

1. Ist die fachliche Semantik im Namen klar?
2. Ist der erlaubte Typ präzise und dokumentiert?
3. Ist die Collection unveränderlich oder bewusst mutierbar?
4. Ist klar, wo Konvertierung auf untypisierte Daten stattfindet?
5. Ist das Verhalten über Tests oder Analyse-Regeln abgesichert?

Wenn ich diese fünf Fragen sauber beantworten kann, ist die Collection in der Regel tragfähig.

Fazit

Typsichere Collections sind in PHP kein Zukunftsthema, sondern heute umsetzbar. Mit klaren Namensregeln, einheitlichen Templates, verbindlichen CI-Gates und einem gestuften Rollout wird aus einer Einzelmaßnahme ein Teamstandard.

Ich brauche dafür keine perfekte Sprache von morgen. Ich brauche disziplinierte Entscheidungen von heute.

Wenn du magst, kannst du mit dem Projekt-Check prüfen, wie robust eure Architektur-, Test- und Typsicherheitsbasis aktuell ist.