4plants/Doku/php.md

PHP & Symfony Engineering Guidelines

1. Core PHP Standard

Wir schreiben modernen, typensicheren und expliziten Code. Ziel ist es, Fehler zur Compile-Zeit bzw. via statischer Analyse zu finden.

• Strict Typing: Jede Datei beginnt zwingend mit declare(strict_types=1);.
• Typisierung:
  • Konsequentes Type Hinting für alle Parameter und Rückgabewerte (inkl. void).
  • Nutzung von Union- und Intersection Types.
  • mixed ist verboten, außer in absolut unvermeidbaren Generics.
• Modern Features (PHP 8.2+):
  • Readonly: Standard für DTOs, Value Objects und Services (readonly class).
  • Constructor Promotion: Nutzung zur Reduktion von Boilerplate.
  • Enums: Einsatz anstelle von Konstanten oder Strings für feste Zustände.
  • Match Expression: Bevorzugt gegenüber switch.
• Anti-Magic: Magic Methods (__call, __get etc.) und dynamische Properties sind strikt verboten.

2. Control Flow & Readability

Lesbarkeit schlägt akademische Perfektion. Code muss für andere Senioren ohne "Rätselraten" sofort verstehbar sein.

• Control Flow: Nutzung von Early Returns und Guard Clauses. Verschachtelte if-else-Strukturen sind zu vermeiden, um die kognitive Last gering zu halten.
• Self-Explaining Code: Namen müssen den Intent beschreiben (calculateTotalTax() statt calc()). Booleans beginnen mit is, has oder can.
• Kommentare: Kommentare werden nur eingesetzt, wenn:
  1. Der Code aufgrund einer Sonderlösung nicht selbsterklärend ist (Dokumentation des "Warum").
  2. Arrays/Collections typisiert werden müssen (/** @var UserDTO[] $users */), sofern PHPStan dies nicht anders erfassen kann.

3. Data Structures & Collections

Wir vermeiden "Mystery Meat"-Datenstrukturen zugunsten von Typsicherheit.

• No Associative Arrays: Die Nutzung von assoziativen Arrays als Pseudo-Objekte/Datencontainer ist verboten. Es werden immer dedizierte Objekte (DTOs) verwendet.
• Collections:
  • Transport: Für einfache Listen, die nur durchiteriert werden, reichen typisierte Arrays (array<T>).
  • Domain-Logik: Sobald eine Liste fachliche Logik besitzt (z.B. Filterung, Aggregation), wird eine dedizierte Collection-Klasse erstellt (implementiert IteratorAggregate und Countable).

4. Infrastructure & Symfony Implementation

Symfony ist der Adapter zur Außenwelt, nicht das Zentrum der Applikation.

• Dependency Injection: Ausschließlich Constructor Injection. Kein Service-Locator ($this->container->get()). DI erfolgt primär gegen Interfaces (Ports).
• Controller: "Thin Controller". Aufgaben sind: Request-Daten validieren/extrahieren \rightarrow Application-Service aufrufen \rightarrow Response transformieren. Keine Business-Logik im Controller.
• Third-Party SDKs: Alle externen Services/SDKs werden konsequent hinter einem eigenen Interface (Port) in der Infrastructure-Schicht gekapselt. Vendor-Klassen dürfen niemals den Application- oder Domain-Layer erreichen.

5. Persistence & Entity Design

Wir minimieren die Koppelung an das ORM, um Performance und Testbarkeit zu sichern.

• Simple Entities: Entitäten werden flach gehalten.
• Avoid Joins: Gejointe Entitäten (komplexe @ManyToOne / @OneToMany) sind grundsätzlich zu vermeiden. Referenzen erfolgen über IDs. Die Zusammenführung erfolgt explizit in den Repositories/Services.
• Mapping: Transformationen zwischen Infrastructure-Entities und Domain-Modellen erfolgen ausschließlich über dedizierte Mapper-Klassen in der Dataschicht.

6. Validation Pipeline (Shift-Left)

Fehler werden so früh wie möglich abgefangen: Request \rightarrow DTO Asserts/Validation \rightarrow Application Logic \rightarrow Domain Complex Tests.

7. Quality Gates & Workflow (Definition of Done)

Bevor Code in ein Review geht, müssen folgende lokale Checks erfolgreich durchlaufen sein:

1. Syntax Check: php -l
2. Statische Analyse: phpstan analyse (Ziel Level 8/9). Pragmatismus-Regel: Wenn Typisierung die Lesbarkeit massiv zerstört \rightarrow Review-Dialog statt "Force-Typing".
3. Automatisierte Tests: phpunit (Unit, Integration, Functional).

---

Die Golden Rules im Überblick:

1. Kein Framework / Keine Vendor-Klassen im Domain.
2. Flache Entitäten / Referenzen über IDs.
3. Immutability by Default (readonly).
4. Keine assoziativen Arrays \rightarrow Dedizierte Objekte.
5. Early Returns \rightarrow Flacher Code.
6. Local Check: php -l \rightarrow phpstan \rightarrow phpunit.