From 3226205889c8bc21fb8d627a33e6e7f4a5aafac9 Mon Sep 17 00:00:00 2001 From: Jens Beckmann Date: Wed, 17 Jun 2026 17:09:06 +0000 Subject: [PATCH] =?UTF-8?q?Doku/php.md=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doku/php.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 Doku/php.md diff --git a/Doku/php.md b/Doku/php.md new file mode 100644 index 0000000..97f08a2 --- /dev/null +++ b/Doku/php.md @@ -0,0 +1,68 @@ +# 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`). + * **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`.** \ No newline at end of file