chore: complete update

2025-07-17 16:24:20 +02:00
parent 899227b0a4
commit 64a7051137
1300 changed files with 85570 additions and 2756 deletions
--- a/docs/standards/CODING-GUIDELINES.md
+++ b/docs/standards/CODING-GUIDELINES.md
@@ -0,0 +1,234 @@
+# Coding Guidelines
+
+## Allgemeine Prinzipien
+
+Diese Guidelines definieren die Standards für die Entwicklung und Wartung des Projekts. Sie sorgen für Konsistenz, Lesbarkeit und Wartbarkeit des Codes.
+
+## PHP-Version
+
+- **PHP 8.4**: Die Codebase nutzt stets die neueste stabile PHP-Version (aktuell PHP 8.4)
+- Alle neuen PHP-Sprachfeatures sollten, wo sinnvoll, genutzt werden
+
+## Abhängigkeiten
+
+- **Externe Abhängigkeiten vermeiden**: Das Projekt soll möglichst ohne externe Bibliotheken auskommen
+- **Eigene Implementierungen bevorzugen**: Anstatt externe Pakete einzubinden, sollten eigene Lösungen entwickelt werden
+- **Erlaubte Abhängigkeiten**: Nur die bereits in composer.json definierten Pakete dürfen verwendet werden
+- **Neue Abhängigkeiten**: Müssen explizit genehmigt werden und sollten nur in Ausnahmefällen hinzugefügt werden
+
+## Klassenstruktur
+
+### Klassen
+
+- **Alle Klassen müssen `final` sein**, es sei denn, es gibt einen zwingenden Grund für Vererbung
+- **Keine abstrakten Klassen** - bevorzuge Interfaces und Kompositionen
+- **Klassen sollten `readonly` sein**, wann immer möglich
+- Interfaces verwenden, um Verträge zwischen Komponenten zu definieren
+
+```php
+// Gut
+final readonly class AnalyticsManager
+{
+    // ...
+}
+
+// Vermeiden
+abstract class BaseManager
+{
+    // ...
+}
+```
+
+### Properties
+
+- **Properties sollten `readonly` sein**, wann immer möglich
+- Private Visibility für alle Properties, es sei denn, es gibt einen zwingenden Grund
+- Typisierung ist obligatorisch für alle Properties
+
+```php
+// Gut
+private readonly StorageInterface $storage;
+
+// Vermeiden
+public array $config;
+```
+
+## Methoden und Funktionen
+
+- Typisierung ist obligatorisch für alle Parameter und Rückgabewerte
+- Methoden sollten klein und fokussiert sein (Single Responsibility)
+- Verwende named arguments für bessere Lesbarkeit
+
+```php
+// Gut
+public function track(string $event, array $properties = [], ?string $userId = null): void
+{
+    // ...
+}
+
+// Vermeiden
+public function process($data)
+{
+    // ...
+}
+```
+
+## Dependency Injection
+
+- Constructor Injection für alle Abhängigkeiten
+- Keine Service Locator oder globale Zustände
+- Verwende das `#[Initializer]`-Attribut für Service-Registrierung
+
+```php
+// Gut
+public function __construct(
+    private readonly Configuration $config,
+    private readonly StorageInterface $storage
+) {}
+
+// Vermeiden
+public function __construct()
+{
+    $this->config = Container::get(Configuration::class);
+}
+```
+
+## Moderne PHP-Features
+
+### Nullable Types und Union Types
+
+```php
+public function findUser(?int $id): ?User
+public function process(int|string $identifier): void
+```
+
+### Match Expression statt Switch
+
+```php
+// Gut
+return match($storageType) {
+    'file' => new FileStorage($path),
+    'redis' => new RedisStorage($connection),
+    default => throw new \InvalidArgumentException("Nicht unterstützter Storage-Typ: {$storageType}")
+};
+
+// Vermeiden
+switch ($storageType) {
+    case 'file':
+        return new FileStorage($path);
+    // ...
+}
+```
+
+### Named Arguments
+
+```php
+$this->createUser(
+    email: 'user@example.com',
+    role: 'admin',
+    sendWelcomeEmail: true
+);
+```
+
+### Constructor Property Promotion
+
+```php
+public function __construct(
+    private readonly Configuration $config,
+    private readonly PathProvider $pathProvider
+) {}
+```
+
+## Fehlerbehandlung
+
+- Spezifische Exceptions werfen
+- Typed Exceptions verwenden
+- Early Return Pattern bevorzugen
+
+```php
+// Gut
+if (!$this->isValid()) {
+    throw new ValidationException('Ungültige Daten');
+}
+
+// Vermeiden
+if ($this->isValid()) {
+    // Lange Verarbeitung...
+} else {
+    throw new Exception('Fehler');
+}
+```
+
+## Testing
+
+- Tests mit Pest-Framework schreiben
+- Für jede öffentliche Methode sollte mindestens ein Test existieren
+- Mocking nur für externe Abhängigkeiten verwenden
+
+```php
+test('track method records events correctly', function () {
+    $analytics = new Analytics($manager, $dispatcher);
+    $analytics->track('test_event', ['key' => 'value']);
+
+    expect($manager->getEvents())->toHaveCount(1);
+});
+```
+
+## Dokumentation
+
+- PHPDoc für alle öffentlichen Methoden und Klassen
+- Typen in PHPDoc sollten den tatsächlichen Typen entsprechen
+- Klare, beschreibende Kommentare für komplexe Logik
+
+```php
+/**
+ * Zeichnet ein Event auf und wendet Middleware an
+ *
+ * @param string $event Event-Name
+ * @param array $properties Event-Eigenschaften
+ * @param string|null $userId Benutzer-ID (optional)
+ */
+public function track(string $event, array $properties = [], ?string $userId = null): void
+```
+
+## Namenskonventionen
+
+- **Klassen**: PascalCase (`AnalyticsManager`)
+- **Methoden/Funktionen**: camelCase (`getEventStats()`)
+- **Variablen**: camelCase (`$eventData`)
+- **Konstanten**: SNAKE_CASE (`MAX_BATCH_SIZE`)
+- **Dateien**: Klassenname.php (`AnalyticsManager.php`)
+
+## Architektur
+
+- Dependency Inversion Principle befolgen
+- Interfaces für alle externen Abhängigkeiten
+- Vermeide zirkuläre Abhängigkeiten zwischen Modulen
+- Services sollten eine klare, fokussierte Verantwortung haben
+
+## Performance
+
+- Lazy Loading für ressourcenintensive Operationen
+- Caching wo sinnvoll
+- Datenstrukturen sorgfältig auswählen
+
+## Security
+
+- Alle Benutzereingaben validieren und bereinigen
+- Prepared Statements für Datenbankabfragen
+- Vermeidung von `eval()` und ähnlichen unsicheren Funktionen
+- Sensible Daten niemals in Logs schreiben
+
+## Best Practices
+
+- **Immutability**: Bevorzuge unveränderliche Objekte
+- **Pure Functions**: Bevorzuge reine Funktionen ohne Seiteneffekte
+- **Enums**: Verwende Enums statt String-Konstanten für feste Optionssätze
+- **DTOs**: Verwende Data Transfer Objects für Datentransport
+- **Value Objects**: Verwende Value Objects für semantisch reiche Datentypen
+
+## Refactoring
+
+- Code, der diese Guidelines nicht erfüllt, sollte beim Bearbeiten aktualisiert werden
+- Tests müssen vor und nach dem Refactoring bestehen
+- Große Refactorings sollten in kleinen, separaten Commits erfolgen