michael/michaelschiemer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: complete update

Browse Source
This commit is contained in:
Michael Schiemer
2025-07-17 16:24:20 +02:00
parent 899227b0a4
commit 64a7051137
1300 changed files with 85570 additions and 2756 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/MARKDOWN.md Normal file
View File

@@ -0,0 +1,61 @@
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
*italics*
**bold**
***italics & bold***
~~crossed off~~
<mark>highlight</mark>
<sub>Test</sub>
`monospace`
```html
<html>
<header></header>
<footer></footer>
</html>
```
[This is a link](https://localhost)
![Image](url)
> This is a blockquote
>> and it can be nested
***
---
___
1. Item 1
2. Item 2
3. Item 3
* Test
* Test
* Subitem
* Subitem
| Column1 | Column 2 |
| --- |-----|
| Test | Test2 |
- [ ] Test
- [x] Test 2

77
docs/README.md Normal file
View File

@@ -0,0 +1,77 @@
# Projekt-Dokumentation
## Übersicht
Willkommen zur Dokumentation des Projekts. Diese Dokumentation dient als zentrale Informationsquelle für Entwickler, die am Projekt arbeiten.
## Inhaltsverzeichnis
### Standards und Guidelines
- [Coding Guidelines](/docs/standards/CODING-GUIDELINES.md) - Allgemeine Coding-Standards für das Projekt
- [Sicherheitsrichtlinien](/docs/standards/SICHERHEITS-GUIDELINES.md) - Standards für sichere Softwareentwicklung
### Entwicklungsrichtlinien
- [Performance Guidelines](/docs/guidelines/PERFORMANCE-GUIDELINES.md) - Richtlinien zur Optimierung der Anwendungsleistung
- [Testing Guidelines](/docs/guidelines/TESTING-GUIDELINES.md) - Standards und Best Practices für Tests
### KI-Assistent Konfiguration
- [Guidelines für KI-Assistenten](/docs/ai/GUIDELINES-FÜR-AI-ASSISTANT.md) - Spezifische Richtlinien für den KI-Assistenten
- [PhpStorm Einrichtung](/docs/ai/EINRICHTUNG-PHPSTORM.md) - Anleitung zur Einrichtung des KI-Assistenten in PhpStorm
### Architektur und Struktur
- [Projektstruktur](/docs/architecture/STRUKTUR-DOKUMENTATION.md) - Überblick über die Struktur des Projekts
### Framework-Entwicklung
- [Modul-Checkliste](/docs/framework/MODUL-CHECKLISTE.md) - Leitfaden für die Erstellung neuer Module
- [Erweiterungsmuster](/docs/framework/ERWEITERUNGSPATTERN.md) - Muster zur Erweiterung des Frameworks
### Framework-Module
- [Analytics-Modul](/docs/framework/analytics/README.md) - Tracking und Analyse von Anwendungsdaten
- [Core-Modul](/docs/framework/core/README.md) - Kernkomponenten und Event-System
- [DI-Modul](/docs/framework/di/README.md) - Dependency-Injection-Container
- [HTTP-Modul](/docs/framework/http/README.md) - HTTP-Request und -Response-Handling
## Mitwirken
### Neue Module entwickeln
1. Folge der [Framework-Modul Checkliste](/docs/framework/MODUL-CHECKLISTE.md) für neue Module
2. Stelle sicher, dass dein Code den [Coding Guidelines](/docs/standards/CODING-GUIDELINES.md) entspricht
3. Schreibe Tests gemäß den [Testing Guidelines](/docs/guidelines/TESTING-GUIDELINES.md)
4. Erstelle eine ausführliche Dokumentation für dein Modul
### Dokumentation verbessern
Wir begrüßen Beiträge zur Verbesserung der Dokumentation. Wenn du Fehler findest oder Vorschläge zur Verbesserung hast, erstelle bitte einen Pull Request mit deinen Änderungen.
## Erste Schritte
Neue Entwickler sollten mit folgenden Schritten beginnen:
1. Projekt lokal einrichten (siehe [Installation](#installation))
2. Die [Projektstruktur](/docs/architecture/STRUKTUR-DOKUMENTATION.md) verstehen
3. Die [Coding Guidelines](/docs/standards/CODING-GUIDELINES.md) lesen
4. PhpStorm mit dem [KI-Assistenten einrichten](/docs/ai/EINRICHTUNG-PHPSTORM.md)
## Installation
```bash
# Repository klonen
git clone [repository-url]
# Abhängigkeiten installieren
composer install
# Entwicklungsserver starten
php -S localhost:8000 -t public/
```
## Updates und Änderungen
Diese Dokumentation wird kontinuierlich aktualisiert. Prüfe regelmäßig auf Aktualisierungen, um über die neuesten Best Practices und Standards informiert zu bleiben.

16
docs/WORKER.md Normal file
View File

@@ -0,0 +1,16 @@
# Queue Worker - Docker Management
Dieses Dokument beschreibt alle Docker-spezifischen Befehle für die Verwaltung des Queue Workers.
## 📋 Inhaltsverzeichnis
- [Schnellstart](#schnellstart)
- [Worker Management](#worker-management)
- [Monitoring & Debugging](#monitoring--debugging)
- [Konfiguration](#konfiguration)
- [Troubleshooting](#troubleshooting)
- [Wartung](#wartung)
## 🚀 Schnellstart
### Worker starten

53
docs/ai/EINRICHTUNG-PHPSTORM.md Normal file
View File

@@ -0,0 +1,53 @@
# Einrichtung des KI-Assistenten in PhpStorm
## Übersicht
Diese Anleitung beschreibt, wie der KI-Assistent in PhpStorm eingerichtet wird, um automatisch die Projekt-Guidelines zu verwenden.
## Methode 1: Über die PhpStorm-Einstellungen
1. Öffne PhpStorm und gehe zu **Settings/Preferences**
- Windows/Linux: File → Settings
- macOS: PhpStorm → Preferences
2. Navigiere zu **Tools** → **AI Assistant** → **Custom Instructions**
3. Aktiviere die Option **Use custom instructions**
4. Füge in das Textfeld den Inhalt aus der Datei `/docs/ai/GUIDELINES-FÜR-AI-ASSISTANT.md` ein
- Alternativ kannst du auf einen relativen Pfad verweisen
5. Aktiviere die Option **Apply project-specific instructions**, damit diese Einstellungen nur für dieses Projekt gelten
6. Klicke auf **Apply** und dann auf **OK**
## Methode 2: Über die Projektkonfiguration (empfohlen)
Die `.idea/aiAssistant.xml`-Datei ist bereits im Projekt enthalten und konfiguriert den KI-Assistenten automatisch mit den richtigen Einstellungen. Wenn du das Projekt öffnest, sollte der KI-Assistent bereits korrekt eingerichtet sein.
Um zu überprüfen, ob die Einstellungen korrekt übernommen wurden:
1. Öffne die PhpStorm-Einstellungen wie oben beschrieben
2. Navigiere zu **Tools** → **AI Assistant** → **Custom Instructions**
3. Überprüfe, ob **Use custom instructions** aktiviert ist und die Guidelines angezeigt werden
## Testen der Einrichtung
Um zu testen, ob der KI-Assistent die Guidelines korrekt anwendet:
1. Öffne eine PHP-Datei im Projekt
2. Drücke `Alt+A` (Windows/Linux) oder `Option+A` (macOS) um den KI-Assistenten zu öffnen
3. Bitte den Assistenten, eine neue Klasse zu erstellen
4. Überprüfe, ob die generierte Klasse den Guidelines entspricht:
- Sie sollte als `final` und wenn möglich `readonly` deklariert sein
- Constructor Property Promotion sollte verwendet werden
- Es sollten keine externen Abhängigkeiten importiert werden
## Fehlerbehebung
Falls die Guidelines nicht korrekt angewendet werden:
1. Stelle sicher, dass du die neueste Version von PhpStorm verwendest
2. Überprüfe, ob die AI Assistant-Funktion aktiviert ist
3. Versuche, das Projekt neu zu öffnen
4. Führe einen Cache-Clear in PhpStorm durch: File → Invalidate Caches

174
docs/ai/GUIDELINES-FÜR-AI-ASSISTANT.md Normal file
View File

@@ -0,0 +1,174 @@
# Guidelines für KI-Assistenten
## Übersicht
Diese Guidelines helfen dir, dem KI-Assistenten, konsistenten, modernen und qualitativ hochwertigen PHP-Code zu generieren, der den Projektstandards entspricht.
## Verwendung in PhpStorm
Diese Guidelines können in PhpStorm so eingerichtet werden, dass sie automatisch vom KI-Assistenten verwendet werden:
1. Gehe zu **Settings/Preferences** → **Tools** → **AI Assistant** → **Custom Instructions**
2. Aktiviere **Use custom instructions**
3. Füge im Textfeld den Inhalt dieser Datei ein oder verwende einen relativen Pfad zu dieser Datei
4. Optional: Aktiviere **Apply project-specific instructions** für projektspezifische Einstellungen
Alternativ kann die Datei `.idea/aiAssistant.xml` angepasst werden, um diese Guidelines als Standardeinstellung für das Projekt zu verwenden.
## Kernprinzipien
### Abhängigkeitsvermeidung
- **Keine externen Abhängigkeiten** außer den explizit freigegebenen
- Eigene Implementierungen gegenüber externen Bibliotheken bevorzugen
- Bei Bedarf nach externen Funktionen zuerst prüfen, ob eine eigene Implementierung möglich ist
- Erlaubte Abhängigkeiten sind auf die vorhandenen Composer-Pakete beschränkt
## Architekturprinzipien
Bei der Codeanalyse und -generierung sind folgende Architekturprinzipien zu beachten:
1. **Modularer Aufbau**: Das Projekt ist in Module unter `/src/Framework/` organisiert
2. **Service-orientierte Architektur**: Funktionalitäten als unabhängige Services implementieren
3. **Dependency Injection**: Abhängigkeiten werden per Constructor Injection bereitgestellt
4. **Event-basierte Kommunikation**: Module kommunizieren über den EventDispatcher
5. **Selbstständigkeit**: Module sollten möglichst unabhängig von externen Bibliotheken sein
## Coding-Standards
### Klassen
- **IMMER `final` verwenden**, außer bei zwingenden Gründen für Vererbung
- **KEINE abstrakten Klassen** verwenden - stattdessen Interfaces und Kompositionen
- Klassen und Properties wenn möglich als `readonly` deklarieren
- Bevorzuge Interfaces für Vertragsgestaltung zwischen Komponenten
```php
// RICHTIG
final readonly class AnalyticsService implements AnalyticsInterface
{
// ...
}
// FALSCH
abstract class BaseAnalytics
{
// ...
}
```
### Properties und Methoden
- Private `readonly` Properties mit Typisierung
- Return-Types immer angeben
- Parameter-Types immer angeben
- Union Types und Nullable Types nutzen
```php
// RICHTIG
private readonly LoggerInterface $logger;
public function process(?int $id): Result|null
{
// ...
}
// FALSCH
public $logger;
public function process($id)
{
// ...
}
```
### Moderne PHP-Features
Nutze aktiv die neuesten PHP-Features:
- Constructor Property Promotion
- Match Expressions statt Switch
- Named Arguments
- Enums statt Konstanten
- Nullsafe Operator (`?->`) wo sinnvoll
- Typed Properties
## Klassenaufbau
Folgende Reihenfolge für Klassenelemente:
1. Konstanten
2. Properties
3. Constructor
4. Öffentliche Methoden
5. Private/Protected Methoden
## Service-Initialisierung
Services werden durch Initializer-Klassen registriert:
```php
#[Initializer]
final readonly class ServiceInitializer
{
public function __construct(
private Configuration $config,
private DependencyInterface $dependency
) {}
public function __invoke(Container $container): ServiceInterface
{
return new Service(
$this->config->get('service'),
$this->dependency
);
}
}
```
## Fehlerbehandlung
- Spezifische Exception-Klassen werfen
- Early Return Pattern bevorzugen
- Defensive Programmierung mit Validierung
## Testing
Bei Test-Vorschlägen Pest-Framework nutzen:
```php
test('method does something correctly', function () {
// Arrangement
$service = new Service($dependency);
// Action
$result = $service->method();
// Assertion
expect($result)->toBe('expected');
});
```
## Dokumentation
- PHPDoc für alle öffentlichen Methoden
- Kurze, präzise Beschreibungen
- Parameter und Return-Types in PHPDoc
## Zu vermeidende Praktiken
- Globale Zustände und statische Methoden
- Tiefe Vererbungshierarchien
- Lange, komplexe Methoden
- Magische Methoden (`__call`, etc.) ohne triftigen Grund
- Unnötige Abstraktionen
## Bei Codeanalyse und -vorschlägen
1. **Aktuellen Stil beibehalten**: Bei Vorschlägen den vorhandenen Codierungsstil beibehalten
2. **Standards berücksichtigen**: Auf Einhaltung der hier definierten Guidelines achten
3. **Modernisierung vorschlagen**: Auf Möglichkeiten zur Modernisierung hinweisen
4. **Begründen**: Bei Empfehlungen die Gründe erläutern
5. **Vollständigkeit**: Vollständige Lösungen anbieten, nicht nur Fragmente
Diese Guidelines sind als lebendiges Dokument zu betrachten, das mit der Evolution des Projekts und von PHP weiterentwickelt wird.

54
docs/ai/index.md Normal file
View File

@@ -0,0 +1,54 @@
# KI-Assistent Dokumentation
## Übersicht
Diese Dokumentation beschreibt die Einrichtung und Verwendung des KI-Assistenten im Projekt. Der KI-Assistent hilft bei der Entwicklung durch Code-Generierung, Refactoring-Vorschläge und mehr, während er die Projektstandards einhält.
## Inhalte
- [Guidelines für KI-Assistenten](/ai/GUIDELINES-FÜR-AI-ASSISTANT.md) - Richtlinien für den KI-Assistenten
- [PhpStorm Einrichtung](/ai/EINRICHTUNG-PHPSTORM.md) - Anleitung zur Einrichtung in PhpStorm
## KI-Assistent Guidelines
Die [Guidelines für KI-Assistenten](/ai/GUIDELINES-FÜR-AI-ASSISTANT.md) stellen sicher, dass der KI-generierte Code den Projektstandards entspricht:
- Einhaltung der Coding-Standards
- Vermeidung externer Abhängigkeiten
- Verwendung moderner PHP-Features
- Konsistente Klassenstruktur
- Korrekte Fehlerbehandlung
## Einrichtung in PhpStorm
Die [PhpStorm Einrichtungsanleitung](/ai/EINRICHTUNG-PHPSTORM.md) führt Sie durch den Prozess der Integration des KI-Assistenten in Ihre IDE:
- Konfiguration der Custom Instructions
- Verwendung der projektspezifischen Einstellungen
- Testen der korrekten Einrichtung
- Fehlerbehebung bei Problemen
## Effektive Nutzung des KI-Assistenten
### Best Practices
1. **Klare Anfragen stellen**: Je präziser die Anfrage, desto besser das Ergebnis
2. **Kontext bereitstellen**: Dem Assistenten relevanten Kontext geben
3. **Ergebnisse überprüfen**: Generierte Code immer prüfen und verstehen
4. **Iterativ arbeiten**: Bei komplexen Aufgaben schrittweise vorgehen
### Häufige Anwendungsfälle
- Erstellung neuer Klassen und Interfaces
- Implementierung von Tests
- Refactoring bestehenden Codes
- Dokumentation generieren
- Code-Optimierung
## Datenschutz und Sicherheit
Beim Umgang mit dem KI-Assistenten sollten Sie folgende Punkte beachten:
- Keine sensiblen Daten oder Geschäftsgeheimnisse teilen
- Keine Passwörter, API-Schlüssel oder Zugangsdaten teilen
- Bei Unsicherheit den KI-Assistenten nicht verwenden

149
docs/architecture/STRUKTUR-DOKUMENTATION.md Normal file
View File

@@ -0,0 +1,149 @@
# Projektstruktur-Dokumentation
## Übersicht
Diese Dokumentation bietet einen Überblick über die Architektur und Struktur des Projekts. Die Anwendung folgt einer modularen, serviceorientierten Architektur mit klarer Trennung von Verantwortlichkeiten.
## Hauptverzeichnisse
### `/src`
Das Hauptverzeichnis für den Anwendungscode, unterteilt in mehrere Unterverzeichnisse:
#### `/src/Framework`
Enthält das Framework mit grundlegenden Infrastrukturkomponenten:
- **Analytics**: System zur Erfassung und Analyse von Anwendungsdaten
- **Attributes**: Attribute/Annotations für Metadaten
- **Cache**: Caching-Mechanismen
- **CommandBus**: Command-Handling-Komponenten
- **Config**: Konfigurationsverwaltung
- **Console**: Konsolenanwendung und -befehle
- **Core**: Kernkomponenten und Events
- **DI**: Dependency-Injection-Container
- **ErrorHandling**: Fehlerbehandlungsmechanismen
- **EventBus**: Event-Handling-System
- **Exception**: Framework-Exceptions
- **Filesystem**: Dateisystemoperationen
- **Http**: HTTP-Request/Response-Handling
- **HttpClient**: HTTP-Client für externe API-Aufrufe
- **Logging**: Logging-Infrastruktur
- **Performance**: Performance-Monitoring
- **Queue**: Nachrichtenwarteschlangen
- **Redis**: Redis-Integration
- **Router**: URL-Routing
- **StaticSite**: Statische Site-Generation
- **Validation**: Datenvalidierung
- **View**: Template-Rendering
#### `/src/Application`
Anwendungsspezifische Komponenten, die das Framework nutzen.
#### `/src/Domain`
Domain-Modelle, Entities und Business-Logik.
#### `/src/Infrastructure`
Infrastrukturkomponenten, die externe Systeme integrieren.
#### `/src/Config`
Konfigurationsdateien für verschiedene Module.
## Framework-Architektur
### Dependency Injection
Das System nutzt einen leistungsfähigen DI-Container zur Verwaltung von Services:
```php
#[Initializer]
class ServiceInitializer
{
public function __invoke(Container $container): Service
{
// Service erstellen und zurückgeben
}
}
```
### Event-System
Ein Event-System ermöglicht lose Kopplung zwischen Komponenten:
```php
$eventDispatcher->addHandler(EventClass::class, function($event) {
// Event verarbeiten
});
```
### HTTP-Pipeline
HTTP-Requests durchlaufen eine Middleware-Pipeline:
```php
class CustomMiddleware implements Middleware
{
public function process(Request $request, callable $next): Response
{
// Request verarbeiten
$response = $next($request);
// Response verarbeiten
return $response;
}
}
```
## Module und ihre Interaktionen
### Analytics-Modul
Das Analytics-Modul erfasst und analysiert Anwendungsdaten:
- **Events tracken**: `$analytics->track('event_name', $properties)`
- **HTTP-Tracking**: Automatisch durch `AnalyticsMiddleware`
- **Error-Tracking**: Integration mit dem Error-Handling-System
- **Dashboard**: Admin-Interface zur Datenvisualisierung
### Konfigurationssystem
Konfigurationen werden zentral verwaltet und injiziert:
```php
class Service
{
public function __construct(private Configuration $config)
{
$settings = $this->config->get('module_name', $defaults);
}
}
```
## Erweiterbarkeit
### Neue Module hinzufügen
1. Erstellen Sie ein neues Verzeichnis unter `/src/Framework`
2. Implementieren Sie eine Initializer-Klasse mit dem `#[Initializer]`-Attribut
3. Erstellen Sie eine entsprechende Konfigurationsdatei unter `/src/Config`
### Middleware hinzufügen
```php
// In Ihrer Anwendungsklasse
public function bootstrap(): void
{
$this->addMiddleware(YourMiddleware::class);
}
```
## Best Practices
- **Dependency Injection**: Verwenden Sie Constructor-Injection für Abhängigkeiten
- **Interfaces**: Definieren Sie Interfaces für alle Services
- **Events**: Nutzen Sie Events für lose Kopplung zwischen Modulen
- **Konfiguration**: Externalisieren Sie Konfigurationen in dedizierte Dateien
- **Typsicherheit**: Nutzen Sie strenge Typisierung und readonly-Properties

70
docs/architecture/index.md Normal file
View File

@@ -0,0 +1,70 @@
# Architektur-Dokumentation
## Übersicht
Diese Dokumentation beschreibt die Architektur und Struktur des Projekts. Sie bietet einen Überblick über die wichtigsten Komponenten, deren Beziehungen und die zugrundeliegenden Architekturprinzipien.
## Inhalte
- [Projektstruktur](/architecture/STRUKTUR-DOKUMENTATION.md) - Überblick über die Struktur des Projekts
## Architekturprinzipien
Das Projekt folgt diesen grundlegenden Architekturprinzipien:
1. **Modulare Architektur**: Klare Trennung von Verantwortlichkeiten in Modulen
2. **Service-orientiertes Design**: Funktionalitäten als unabhängige Services
3. **Dependency Injection**: Abhängigkeiten werden explizit injiziert
4. **Event-basierte Kommunikation**: Lose Kopplung durch Events
5. **Schichtenarchitektur**: Trennung von Präsentation, Anwendungslogik und Daten
## Hauptkomponenten
### Framework-Kern
Der Framework-Kern stellt grundlegende Infrastrukturkomponenten bereit:
- **DI-Container**: Verwaltung von Service-Abhängigkeiten
- **Event-System**: Event-basierte Kommunikation
- **HTTP-Komponenten**: Request/Response-Handling
- **Routing**: URL-zu-Controller-Mapping
### Anwendungsschicht
Die Anwendungsschicht implementiert die Geschäftslogik:
- **Services**: Implementierung von Anwendungsfunktionen
- **Commands/Queries**: Command-Query-Separation-Prinzip
- **Controllers**: HTTP-Request-Handling
### Domainschicht
Die Domainschicht enthält die Kerngeschäftslogik:
- **Entities**: Geschäftsobjekte mit Identität
- **Value Objects**: Unveränderliche Wertobjekte
- **Domain Services**: Domänenspezifische Logik
### Infrastrukturschicht
Die Infrastrukturschicht bietet technische Funktionen:
- **Persistenz**: Datenbankzugriff und -verwaltung
- **Messaging**: Externe Kommunikation
- **Integration**: Anbindung an externe Systeme
## Datenfluss
Ein typischer Datenfluss im System:
1. HTTP-Request wird vom Router empfangen
2. Middleware-Pipeline verarbeitet den Request
3. Controller erhält den Request und delegiert an Services
4. Services implementieren die Geschäftslogik
5. Domain-Objekte repräsentieren den Geschäftszustand
6. Repositories speichern/laden Daten
7. Response wird erstellt und zurückgegeben
## Weitere Informationen
Für detailliertere Informationen zur Architektur siehe die [Projektstruktur-Dokumentation](/architecture/STRUKTUR-DOKUMENTATION.md).

14
docs/framework/ANALYTICS.md Normal file
View File

@@ -0,0 +1,14 @@
# Analytics-Framework
> **Dokumentationshinweis:** Die vollständige Dokumentation für das Analytics-Framework finden Sie im Ordner [/docs/framework/analytics](/docs/framework/analytics/).
## Schnellzugriff
- [Übersicht und Einstieg](/docs/framework/analytics/index.md)
- [Detaillierte Architektur](/docs/framework/analytics/architecture.md)
- [Anwendungsbeispiele](/docs/framework/analytics/usage.md)
- [Migrationsleitfaden](/docs/framework/analytics/migration.md)
## Implementierungsdetails
Die Code-Dokumentation befindet sich in der [README-Datei des Frameworks](/Framework/Analytics1/README.md).

200
docs/framework/ERWEITERUNGSPATTERN.md Normal file
View File

@@ -0,0 +1,200 @@
# Erweiterungsmuster im Framework
## Übersicht
Dieses Dokument beschreibt die verschiedenen Muster und Techniken, um das Framework zu erweitern oder anzupassen, ohne den Kern-Code zu verändern.
## Event-basierte Erweiterungen
### Event-Listener
Die primäre Methode zur Erweiterung des Frameworks ist das Lauschen auf System-Events:
```php
// Event-Listener registrieren
public function __construct(private readonly EventDispatcher $eventDispatcher)
{
$this->eventDispatcher->addHandler(
'App\Framework\Core\Events\ApplicationBooted',
[$this, 'onApplicationBooted']
);
}
// Event-Handler-Methode
public function onApplicationBooted(ApplicationBooted $event): void
{
// Erweiterungslogik implementieren
}
```
### Eigene Events
Benutzerdefinierte Events erstellen:
```php
final readonly class UserRegistered
{
public function __construct(
public string $userId,
public string $email,
public \DateTimeImmutable $timestamp
) {}
}
// Event auslösen
$this->eventDispatcher->dispatch(new UserRegistered(
$user->getId(),
$user->getEmail(),
new \DateTimeImmutable()
));
```
## Middleware
HTTP-Anfragen können durch Middleware-Klassen erweitert werden:
```php
final readonly class CustomMiddleware implements Middleware
{
public function process(Request $request, callable $next): Response
{
// Vor der Anfrageverarbeitung
$modifiedRequest = $this->modifyRequest($request);
// Anfrage weiterleiten
$response = $next($modifiedRequest);
// Nach der Anfrageverarbeitung
return $this->modifyResponse($response);
}
}
// Middleware registrieren
$app->addMiddleware(CustomMiddleware::class);
```
## Service-Erweiterungen
### Service-Ersetzen
Standardimplementierungen durch eigene ersetzen:
```php
#[Initializer]
final readonly class CustomStorageInitializer
{
public function __invoke(Container $container): StorageInterface
{
return new CustomStorage();
}
}
```
### Service-Decorator
Bestehende Services erweitern ohne Änderung der Original-Implementierung:
```php
#[Initializer]
final readonly class LoggingAnalyticsInitializer
{
public function __construct(
private readonly Configuration $config,
private readonly LoggerInterface $logger
) {}
public function __invoke(Container $container): Analytics
{
// Original-Analytics-Service erstellen
$originalAnalytics = new Analytics(
new AnalyticsManager($this->config->get('analytics'), new FileStorage($path)),
$container->get(EventDispatcher::class)
);
// Mit Logging-Decorator umhüllen
return new LoggingAnalyticsDecorator($originalAnalytics, $this->logger);
}
}
// Decorator-Implementierung
final readonly class LoggingAnalyticsDecorator implements AnalyticsInterface
{
public function __construct(
private Analytics $analytics,
private LoggerInterface $logger
) {}
public function track(string $event, array $properties = [], ?string $userId = null): void
{
$this->logger->debug("Tracking event: {$event}", [
'properties' => $properties,
'user_id' => $userId
]);
$this->analytics->track($event, $properties, $userId);
}
// Andere Methoden implementieren
}
```
## Plugin-System
### Plugin-Interface
```php
interface PluginInterface
{
public function register(Application $app): void;
public function boot(Application $app): void;
}
// Plugin-Implementierung
final readonly class CustomPlugin implements PluginInterface
{
public function register(Application $app): void
{
// Services registrieren
}
public function boot(Application $app): void
{
// Nach Initialisierung der Anwendung
}
}
// Plugin registrieren
$app->registerPlugin(new CustomPlugin());
```
## Konfigurationserweiterungen
### Konfigurationsquellen
Benutzerdefinierte Konfigurationsquellen implementieren:
```php
final readonly class EnvironmentConfigSource implements ConfigSourceInterface
{
public function load(string $key, mixed $default = null): mixed
{
$envKey = strtoupper(str_replace('.', '_', $key));
return $_ENV[$envKey] ?? $default;
}
}
// Konfigurationsquelle registrieren
$config->addSource(new EnvironmentConfigSource());
```
## Zusammenfassung
Die bevorzugten Erweiterungsmuster sind:
1. **Event-Listener** für reaktive Erweiterungen
2. **Middleware** für HTTP-Anfrageverarbeitung
3. **Service-Initializer** zum Ersetzen oder Dekorieren von Services
4. **Plugins** für umfassendere Funktionalitätserweiterungen
5. **Konfigurationsquellen** für benutzerdefinierte Konfigurationen
Diese Muster ermöglichen es, das Framework zu erweitern, ohne den Kern zu modifizieren, was zu einer besseren Wartbarkeit und einfacheren Updates führt.

73
docs/framework/MODUL-CHECKLISTE.md Normal file
View File

@@ -0,0 +1,73 @@
# Framework-Modul Checkliste
## Übersicht
Diese Checkliste dient als Leitfaden für die Erstellung neuer Module im Framework. Sie hilft sicherzustellen, dass alle Module den Projektstandards entsprechen und konsistent implementiert werden.
## Strukturelle Anforderungen
- [ ] Modul in eigenem Verzeichnis unter `/src/Framework/`
- [ ] Konsistente Namensgebung im PascalCase (z.B. `CacheManager` statt `Cache_manager`)
- [ ] README.md mit Modul-Dokumentation
- [ ] Interface(s) für öffentliche API
- [ ] Implementierungsklassen als `final readonly`
- [ ] Initializer-Klasse mit `#[Initializer]`-Attribut
## Abhängigkeiten
- [ ] Minimale externe Abhängigkeiten (idealerweise keine)
- [ ] Klar definierte Abhängigkeiten zu anderen Framework-Modulen
- [ ] Keine zirkulären Abhängigkeiten
- [ ] Verwendung des DI-Containers für Abhängigkeiten
## Konfiguration
- [ ] Konfigurationsdatei unter `/src/Config/{modul-name}.php`
- [ ] Standardkonfiguration in der Initializer-Klasse
- [ ] Dokumentierte Konfigurationsoptionen
## Code-Qualität
- [ ] Vollständige Typisierung (Parameter, Rückgabewerte, Properties)
- [ ] PHPDoc für öffentliche Methoden und Klassen
- [ ] Keine abstrakten Klassen oder Vererbung (außer Interfaces)
- [ ] Immutable Objekte wo möglich
- [ ] Spezifische Exceptions für Fehlerbehandlung
## Tests
- [ ] Unit-Tests mit Pest für alle öffentlichen Methoden
- [ ] Integrationstests für Modul-Interaktionen
- [ ] Testabdeckung für Fehlerfälle
## Integration
- [ ] Event-Listener für relevante System-Events
- [ ] Erweiterungspunkte für andere Module
- [ ] Keine direkten Abhängigkeiten zu Domain-Klassen
## Dokumentation
- [ ] Beispiele für Verwendung
- [ ] Architektur-Beschreibung
- [ ] API-Dokumentation
- [ ] Konfigurationsreferenz
## Performance
- [ ] Lazy-Loading für ressourcenintensive Operationen
- [ ] Caching-Strategie (falls relevant)
- [ ] Performancekritische Teile identifiziert und optimiert
## Sicherheit
- [ ] Validierung aller externen Eingaben
- [ ] Keine sensiblen Daten in Logs
- [ ] Schutz vor bekannten Sicherheitslücken
## Wartbarkeit
- [ ] Kleine, fokussierte Klassen
- [ ] Klare Trennung von Verantwortlichkeiten
- [ ] Konsistente Fehlerbehandlung
- [ ] Logging an strategischen Stellen

158
docs/framework/analytics/README.md Normal file
View File

@@ -0,0 +1,158 @@
# Analytics-Modul Dokumentation
## Übersicht
Das Analytics-Modul ist ein internes Tracking- und Analysesystem, das ohne externe Abhängigkeiten Benutzeraktivitäten, Systemereignisse und Leistungsdaten erfasst und analysiert.
## Kernkomponenten
### Analytics (Analytics.php)
Die Hauptklasse, die als zentraler Einstiegspunkt für das Tracking von Events dient.
**Hauptfunktionen:**
- `track()`: Zeichnet ein generisches Event auf
- `page()`: Spezifisch für Seitenaufrufe
- `user()`: Verfolgt Benutzeridentifikation
- `performance()`: Erfasst Leistungsmetriken
- `error()`: Protokolliert Fehler und Ausnahmen
### AnalyticsManager (AnalyticsManager.php)
Verwaltet die Verarbeitung und Speicherung von Events.
**Hauptfunktionen:**
- `track()`: Verarbeitet Events und wendet Middleware an
- `addMiddleware()`: Fügt Verarbeitungsfunktionen hinzu
- `flush()`: Schreibt gepufferte Events in den Speicher
### StorageInterface und FileStorage
Das Interface definiert die Speichermethoden, FileStorage implementiert die Speicherung in Dateien.
**Hauptoperationen:**
- `store()`: Speichert Events
- `retrieve()`: Ruft Events mit Filtern ab
- `clear()`: Löscht alle gespeicherten Daten
### AnalyticsInitializer (AnalyticsInitializer.php)
Konfiguriert und initialisiert den Analytics-Service beim Anwendungsstart.
**Konfigurationsoptionen:**
- Aktivierung/Deaktivierung
- Auto-Flush und Batch-Größe
- Storage-Typ und Pfad
### AnalyticsMiddleware (AnalyticsMiddleware.php)
HTTP-Middleware zum automatischen Tracking von Requests und Responses.
### AnalyticsDashboard (AnalyticsDashboard.php)
Stellt Methoden für Datenanalyse und -aggregation bereit:
- `getEventStats()`: Ereignisstatistiken
- `getTopPages()`: Meistbesuchte Seiten
- `getUserStats()`: Benutzerstatistiken
- `getErrorStats()`: Fehlerstatistiken
- `getPerformanceStats()`: Leistungsmetriken
### Events
Vordefinierte Event-Typen:
- `AnalyticsEvent`: Basis-Event-Klasse
- `PageViewEvent`: Speziell für Seitenaufrufe
### Controllers
`AdminAnalyticsController`: Stellt das Admin-Dashboard bereit mit:
- Übersichtsseite
- Seitenstatistiken
- Fehlerstatistiken
- Leistungsstatistiken
### Console
`AnalyticsClearCommand`: Konsolenbefehl zum Löschen von Analytics-Daten.
## Konfiguration
Die Konfiguration erfolgt in `src/Config/analytics.php` mit folgenden Optionen:
```php
return [
'enabled' => true, // Aktiviert/deaktiviert das Tracking
'auto_flush' => true, // Automatisches Speichern nach Batch-Größe
'batch_size' => 50, // Anzahl Events pro Batch
'storage' => 'file', // Storage-Backend
'storage_path' => '...', // Speicherpfad
'anonymize_ip' => true, // IP-Anonymisierung
'track_events' => [...] // Zu trackende Events
];
```
## Verwendung
### Basis-Tracking
```php
// Event tracken
$analytics->track('button_click', ['button' => 'signup']);
// Seitenaufruf tracken
$analytics->page('/dashboard', ['section' => 'analytics']);
// Benutzer identifizieren
$analytics->user('user123', ['plan' => 'premium']);
```
### Middleware einrichten
```php
$this->addMiddleware(App\Framework\Analytics\AnalyticsMiddleware::class);
```
### Eigene Middleware hinzufügen
```php
$analyticsManager->addMiddleware(function(array $event) {
// Daten verarbeiten oder filtern
return $event;
});
```
## Datenschutz
Das System bietet integrierte Funktionen zur Anonymisierung personenbezogener Daten:
- IP-Adressen-Anonymisierung (letztes Oktett wird entfernt)
- Konfigurierbare Filterung sensibler Daten durch Middleware
## Erweiterbarkeit
### Eigene Storage-Provider
Implementieren Sie das `StorageInterface` für benutzerdefinierte Speicherlösungen:
```php
class CustomStorage implements StorageInterface
{
public function store(array $events): void { /* ... */ }
public function retrieve(array $filters = []): array { /* ... */ }
public function clear(): void { /* ... */ }
}
```
### Event-Typen erweitern
Erstellen Sie benutzerdefinierte Event-Klassen, die von `AnalyticsEvent` erben:
```php
class CustomEvent extends AnalyticsEvent
{
public function __construct(string $customData, array $additionalProps = [])
{
parent::__construct('custom_event',
array_merge(['custom_data' => $customData], $additionalProps));
}
}
```

102
docs/framework/analytics/architecture.md Normal file
View File

@@ -0,0 +1,102 @@
# Analytics-Framework: Architektur
## Überblick
Das Analytics-Framework verwendet eine Schichtenarchitektur mit klaren Verantwortlichkeiten:
```
┌─────────────────────────────────────────────────────┐
│ Öffentliche API │
│ (Analytics) │
└───────────────────────┬─────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────┐
│ Event-Verarbeitung │
│ (AnalyticsManager) │
└───────────────────────┬─────────────────────────────┘
│
┌──────────────┴──────────────┐
│ │
┌────────▼─────────┐ ┌─────────▼────────┐
│ Middleware │ │ Storage-Layer │
│ (Pipeline) │ │ (StorageInterface)│
└──────────────────┘ └──────────────────┘
```
## Komponenten im Detail
### Analytics (Frontend)
Bietet eine benutzerfreundliche API für Tracking-Operationen. Diese Klasse ist der primäre Einstiegspunkt für Anwendungscode und abstrahiert die Komplexität der Eventverarbeitung.
Verantwortlichkeiten:
- Bereitstellung der öffentlichen API (`track`, `page`, `user`, `error`)
- Integration mit dem Event-Dispatcher des Frameworks
- Typ-Konvertierung zwischen benutzerdefinierten Ereignissen und dem internen Datenformat
### AnalyticsManager (Verarbeitung)
Der Manager ist das Herzstück des Systems und verantwortlich für:
- Anwendung von Middleware-Transformationen auf Events
- Eventpufferung für effiziente Speicherung
- Verwaltung der Konfiguration
- Steuerung des Storage-Layers
Der Manager implementiert einen Event-Buffer, der Daten sammelt und bei Erreichen einer konfigurierbaren Größe automatisch speichert.
### Middleware-System
Eine Kette von Verarbeitungsfunktionen, die auf jedes Event angewendet werden:
- Datenfilterung und -transformation
- Anonymisierung persönlicher Daten
- Validierung und Anreicherung von Events
Jede Middleware kann Events modifizieren oder komplett verwerfen.
### Storage-Layer
Abstraktion für verschiedene Speichermethoden durch das `StorageInterface`:
```php
interface StorageInterface
{
public function store(array $events): void;
public function retrieve(array $filters = []): array;
public function clear(): void;
}
```
Implementierungen:
- `FileStorage`: Speichert Events in JSON-Dateien mit täglicher Rotation
- Erweiterbar für andere Backends (Datenbank, Redis, etc.)
### HTTP-Integration
`AnalyticsMiddleware` integriert Analytics in den HTTP-Request-Lifecycle:
- Tracking von eingehenden Requests
- Erfassung von Antwortzeiten und Statuscodes
- Fehlererfassung bei Exceptions
### Admin-Dashboard
`AnalyticsDashboard` und `AdminAnalyticsController` bieten:
- Datenaggregation und -analyse
- Visualisierung von Metriken
- Filterung nach Zeiträumen
- Verschiedene spezialisierte Ansichten (Seiten, Fehler, Performance)
## Datenfluss
1. Event wird durch `Analytics::track()` oder ähnliche Methoden erstellt
2. `AnalyticsManager` wendet Middleware-Pipeline an
3. Event wird zum Buffer hinzugefügt
4. Bei Buffer-Füllung oder explizitem `flush()` werden Events an Storage übergeben
5. Storage speichert Events im konfigurierten Backend
6. `AnalyticsDashboard` ruft Daten bei Bedarf vom Storage ab und aggregiert sie
## Erweiterungspunkte
- **Storage-Provider**: Neue Implementierungen von `StorageInterface`
- **Middleware**: Funktionen für Filterung/Transformation
- **Event-Typen**: Spezialisierte Event-Klassen für typsicheres Tracking
- **Dashboard-Views**: Zusätzliche Visualisierungen und Berichte

114
docs/framework/analytics/index.md Normal file
View File

@@ -0,0 +1,114 @@
# Analytics-Framework
> **Dokumentationshinweis:** Diese Dokumentation ist vollständig aktualisiert und stellt die aktuelle Implementierung des Analytics-Frameworks korrekt dar.
## Übersicht
Das Analytics-Framework ist ein eigenständiges Tracking- und Analysesystem, das vollständig in die Anwendung integriert ist und ohne externe Dienste auskommt. Es ermöglicht die Erfassung, Speicherung und Analyse von:
- Benutzeraktivitäten (Seitenaufrufe, Interaktionen)
- Systemereignissen (Anwendungsstart, Fehler)
- Leistungsdaten (Speicherverbrauch, Ausführungszeit, Datenbankabfragen)
## Hauptkomponenten
### Analytics-Klasse
Die zentrale API für Tracking-Operationen:
```php
// Klasse initialisieren
$analytics = new Analytics($analyticsManager, $eventDispatcher);
// Event tracken
$analytics->track('event_name', ['property' => 'value']);
// Seite tracken
$analytics->page('/pfad/zur/seite', ['eigenschaft' => 'wert']);
// Benutzer identifizieren
$analytics->user('user_id', ['eigenschaft' => 'wert']);
// Fehler tracken
$analytics->error($exception);
```
### AnalyticsManager
Verarbeitet und speichert Events:
- Wendet Middleware auf Events an
- Puffert Events für effiziente Speicherung
- Verwaltet die Konfiguration
- Steuert die Speicherung in verschiedenen Backends
### Storage-System
Basierend auf dem `StorageInterface` mit verschiedenen Implementierungen:
- `FileStorage`: Speichert Events in Dateien
- Erweiterbar für Datenbank, Redis oder andere Backends
### Middleware-System
```php
$analyticsManager->addMiddleware(function(array $event) {
// Event verarbeiten oder filtern
return $event; // oder null um zu verwerfen
});
```
### HTTP-Middleware
Automatisches Tracking von HTTP-Requests und -Responses:
```php
// In Bootstrap oder Application-Klasse
$app->addMiddleware(AnalyticsMiddleware::class);
```
### Dashboard und Berichterstattung
Das `AnalyticsDashboard` bietet Methoden zur Datenanalyse:
- `getEventStats()`: Statistiken zu Events
- `getTopPages()`: Meistbesuchte Seiten
- `getUserStats()`: Benutzerstatistiken
- `getErrorStats()`: Fehlerstatistiken
- `getPerformanceStats()`: Leistungsmetriken
Das Admin-Dashboard ist unter `/admin/analytics` verfügbar.
### Konsolen-Befehle
```bash
# Analytics-Daten löschen
php console analytics:clear [--force]
```
## Integration
### Service-Container
Der Analytics-Service wird automatisch registriert und kann per Dependency Injection verwendet werden:
```php
public function __construct(private readonly Analytics $analytics) {}
```
### Event-Integration
Standardmäßig werden folgende Anwendungsereignisse getrackt:
- Anwendungsstart (`application_booted`)
- Fehlerbehandlung (`error_occurred`)
- Request-Verarbeitung (`request_started`, `request_completed`)
## Konfiguration
Detaillierte Konfigurationsoptionen finden Sie in der [Framework-README](/Framework/Analytics1/README.md).
## Weitere Informationen
- [Framework-Erweiterungsmuster](/docs/framework/ERWEITERUNGSPATTERN.md)
- [Modul-Checkliste](/docs/framework/MODUL-CHECKLISTE.md)

160
docs/framework/analytics/migration.md Normal file
View File

@@ -0,0 +1,160 @@
# Analytics-Framework: Migrationsleitfaden
## Von Version 1.x zu 2.x
### Überblick der Änderungen
Die Version 2.x des Analytics-Frameworks führt mehrere wichtige Verbesserungen und Änderungen ein:
- **Typsicherheit**: Neue Event-Klassen statt Arrays
- **Dependency Injection**: Verbesserte Integration mit dem Container
- **Storage-Abstraktion**: Flexiblere Speichermethoden
- **Fehlerbehandlung**: Robustere Exception-Handling
- **Middleware-System**: Standardisierte Middleware-Pipeline
### Notwendige Migrationsschritte
#### 1. Konfiguration aktualisieren
**Alt (1.x):**
```php
return [
'enabled' => true,
'auto_flush' => true,
'batch_size' => 50,
'storage' => 'file',
'storage_path' => '/pfad/zum/speicher',
];
```
**Neu (2.x):**
```php
return [
'enabled' => true,
'auto_flush' => true,
'batch_size' => 50,
'storage_driver' => 'file', // Umbenannt
'storage_config' => [ // Neue Struktur
'path' => '/pfad/zum/speicher',
],
'excluded_paths' => [], // Neue Option
'excluded_user_agents' => [], // Neue Option
'max_file_size' => 10 * 1024 * 1024, // Neue Option
];
```
#### 2. Event-Objekte (falls genutzt)
**Alt (1.x):**
```php
$analytics->track('custom_event', ['property' => 'value']);
```
**Neu (2.x) - Option 1 (abwärtskompatibel):**
```php
// Weiterhin unterstützt
$analytics->track('custom_event', ['property' => 'value']);
```
**Neu (2.x) - Option 2 (typsicher):**
```php
use App\Framework\Analytics\Events\CustomEvent;
$event = new CustomEvent('wert', ['weitere' => 'daten']);
$analytics->trackEvent($event);
```
#### 3. Eigene Storage-Provider
**Alt (1.x):**
```php
class CustomStorage implements StorageInterface
{
public function store(array $events): void
{
// Implementation
}
public function retrieve(array $filters = []): array
{
// Implementation
}
public function clear(): void
{
// Implementation
}
}
```
**Neu (2.x):**
```php
use Psr\Log\LoggerInterface;
class CustomStorage implements StorageInterface
{
public function __construct(
private readonly array $config,
private readonly LoggerInterface $logger
) {}
public function store(array $events): void
{
try {
// Implementation mit Fehlerbehandlung
} catch (\Exception $e) {
$this->logger->error('Storage error', ['exception' => $e]);
throw new StorageException('Failed to store events', 0, $e);
}
}
// Andere Methoden analog
}
```
#### 4. Middleware anpassen
**Alt (1.x):**
```php
$analyticsManager->addMiddleware(function(array $event) {
// Verarbeitung
return $event;
});
```
**Neu (2.x) - Option 1 (abwärtskompatibel):**
```php
// Weiterhin unterstützt
$analyticsManager->addMiddleware(function(array $event) {
// Verarbeitung
return $event;
});
```
**Neu (2.x) - Option 2 (typsicher):**
```php
use App\Framework\Analytics\Middleware\AnalyticsMiddleware;
use App\Framework\Analytics\Events\AnalyticsEvent;
class CustomMiddleware implements AnalyticsMiddleware
{
public function process(AnalyticsEvent $event): ?AnalyticsEvent
{
// Verarbeitung
return $event;
}
}
// Registrierung
$analyticsManager->addMiddleware(new CustomMiddleware());
```
### Automatisierte Tests
Führen Sie die folgenden Tests durch, um sicherzustellen, dass die Migration erfolgreich war:
```bash
php console test:run --group=analytics
```
Weitere Informationen zur Migration finden Sie in den Änderungsprotokollen im Quellcode-Repository.

269
docs/framework/analytics/usage.md Normal file
View File

@@ -0,0 +1,269 @@
# Analytics-Framework: Anwendungsbeispiele
## Grundlegende Verwendung
### Events tracken
```php
// Über Dependency Injection
public function __construct(private readonly Analytics $analytics) {}
// Einfaches Event tracken
$this->analytics->track('login_attempt', [
'success' => true,
'user_type' => 'admin',
'method' => 'password'
]);
// Seitenaufruf tracken
$this->analytics->page('/produkte/kategorie/elektronik', [
'referrer' => 'homepage',
'search_query' => 'smartphones'
]);
// Benutzer identifizieren
$this->analytics->user($user->getId(), [
'email' => $user->getEmail(),
'plan' => $user->getSubscriptionPlan(),
'registered_since' => $user->getCreatedAt()->format('Y-m-d')
]);
```
### Fehler tracken
```php
try {
// Fehleranfälliger Code
$result = $this->riskyOperation();
return $result;
} catch (\Exception $e) {
// Fehler tracken
$this->analytics->error($e);
// Fehler behandeln
$this->logger->error($e->getMessage());
return $this->fallbackOperation();
}
```
### Performance tracken
```php
// Manuelles Performance-Tracking
$startTime = microtime(true);
$startMemory = memory_get_usage();
// Operation durchführen
$result = $this->heavyOperation();
// Performance-Metriken tracken
$this->analytics->performance([
'operation' => 'heavy_operation',
'execution_time' => microtime(true) - $startTime,
'memory_used' => memory_get_usage() - $startMemory,
'result_size' => is_countable($result) ? count($result) : 0
]);
```
## Erweiterte Anwendungsfälle
### Benutzerdefinierte Middleware
```php
// In einem Service Provider oder Initializer
public function initialize(AnalyticsManager $manager): void
{
// DSGVO-Middleware zur Anonymisierung personenbezogener Daten
$manager->addMiddleware(function(array $event) {
// E-Mail-Adressen anonymisieren
if (isset($event['properties']['email'])) {
$parts = explode('@', $event['properties']['email']);
if (count($parts) === 2) {
$event['properties']['email'] = substr($parts[0], 0, 1) .
'***@' . $parts[1];
}
}
// Passwörter und Tokens entfernen
foreach (['password', 'token', 'api_key', 'secret'] as $key) {
if (isset($event['properties'][$key])) {
$event['properties'][$key] = '[redacted]';
}
}
return $event;
});
// Spam-Filter
$manager->addMiddleware(function(array $event) {
// Zu viele Events von einem Benutzer filtern
static $userCounts = [];
$userId = $event['user_id'] ?? $event['session_id'] ?? null;
if ($userId) {
$userCounts[$userId] = ($userCounts[$userId] ?? 0) + 1;
// Mehr als 100 Events pro Session ist verdächtig
if ($userCounts[$userId] > 100) {
return null; // Event verwerfen
}
}
return $event;
});
}
```
### Integration mit dem Domain-Layer
```php
// In einem Domain-Service
namespace App\Domain\Shop\Services;
use App\Framework\Analytics\Analytics;
class ProductService
{
public function __construct(private readonly Analytics $analytics) {}
public function viewProduct(string $productId, ?string $userId): Product
{
$product = $this->productRepository->find($productId);
if (!$product) {
throw new ProductNotFoundException($productId);
}
// Produktansicht tracken
$this->analytics->track('product_view', [
'product_id' => $product->getId(),
'product_name' => $product->getName(),
'product_price' => $product->getPrice(),
'product_category' => $product->getCategory()->getName(),
'in_stock' => $product->isInStock()
], $userId);
return $product;
}
public function addToCart(string $productId, int $quantity, ?string $userId): Cart
{
// Implementation...
// Event tracken
$this->analytics->track('add_to_cart', [
'product_id' => $productId,
'quantity' => $quantity,
'cart_value' => $cart->getTotalValue()
], $userId);
return $cart;
}
}
```
### Verwendung im Controller
```php
namespace App\Application\Controllers;
use App\Framework\Analytics\Analytics;
use App\Framework\Http\Request;
use App\Framework\Http\Response;
use App\Framework\Attributes\Route;
class CheckoutController
{
public function __construct(
private readonly Analytics $analytics,
private readonly CheckoutService $checkoutService
) {}
#[Route('/checkout/complete', method: 'POST')]
public function completeCheckout(Request $request): Response
{
$userId = $request->getSession()->get('user_id');
$cartId = $request->getSession()->get('cart_id');
try {
$order = $this->checkoutService->completeCheckout($cartId, $userId);
// Erfolgreichen Checkout tracken
$this->analytics->track('checkout_complete', [
'order_id' => $order->getId(),
'order_value' => $order->getTotalValue(),
'items_count' => count($order->getItems()),
'payment_method' => $order->getPaymentMethod(),
'shipping_method' => $order->getShippingMethod()
], $userId);
return new Response([
'success' => true,
'order_id' => $order->getId()
], 200);
} catch (\Exception $e) {
// Fehler beim Checkout tracken
$this->analytics->track('checkout_error', [
'error' => $e->getMessage(),
'cart_id' => $cartId
], $userId);
// Auch den Exception-Stack tracken
$this->analytics->error($e);
return new Response([
'success' => false,
'error' => $e->getMessage()
], 400);
}
}
}
```
## Analyse der Daten
### Dashboard-Controller
```php
namespace App\Application\Controllers;
use App\Framework\Analytics\AnalyticsDashboard;
use App\Framework\Http\Request;
use App\Framework\Http\Response;
use App\Framework\View\ViewRenderer;
use App\Framework\Attributes\Route;
class AnalyticsDashboardController
{
public function __construct(
private readonly AnalyticsDashboard $dashboard,
private readonly ViewRenderer $viewRenderer
) {}
#[Route('/admin/analytics/conversion')]
public function conversionReport(Request $request): Response
{
$from = $request->getQueryParam('from');
$to = $request->getQueryParam('to');
// Benutzerdefinierte Analyse für Conversion-Funnel
$pageViews = $this->dashboard->getEventCountByType('page_view', $from, $to);
$productViews = $this->dashboard->getEventCountByType('product_view', $from, $to);
$addToCarts = $this->dashboard->getEventCountByType('add_to_cart', $from, $to);
$checkouts = $this->dashboard->getEventCountByType('checkout_complete', $from, $to);
// Conversion-Raten berechnen
$data = [
'total_visitors' => $pageViews,
'product_view_rate' => $pageViews > 0 ? $productViews / $pageViews : 0,
'add_to_cart_rate' => $productViews > 0 ? $addToCarts / $productViews : 0,
'checkout_rate' => $addToCarts > 0 ? $checkouts / $addToCarts : 0,
'overall_conversion' => $pageViews > 0 ? $checkouts / $pageViews : 0,
'from_date' => $from,
'to_date' => $to
];
return $this->viewRenderer->render('admin/analytics/conversion', $data);
}
}
```

45
docs/framework/core/README.md Normal file
View File

@@ -0,0 +1,45 @@
# Core-Modul Dokumentation
## Übersicht
Das Core-Modul bildet das Herzstück des Frameworks und stellt grundlegende Funktionalitäten bereit, die von anderen Modulen genutzt werden.
## Hauptkomponenten
### Events und EventDispatcher
Das Event-System ermöglicht die Kommunikation zwischen Komponenten über einen zentralen Event-Bus.
**Kernklassen:**
- `EventDispatcher`: Zentraler Service zum Registrieren und Auslösen von Events
- Bekannte Events:
- `ApplicationBooted`
- `ErrorOccurred`
- `BeforeHandleRequest`
- `AfterHandleRequest`
**Beispielverwendung:**
```php
// Event-Handler registrieren
$eventDispatcher->addHandler('App\Framework\Core\Events\ApplicationBooted', function($event) {
// Event verarbeiten
});
```
### PathProvider
Stellt Pfadinformationen für verschiedene Bereiche der Anwendung bereit.
**Hauptfunktionen:**
- `getDataPath()`: Liefert Pfade zu Datenverzeichnissen
## Integration mit anderen Modulen
Das Core-Modul wird von vielen anderen Modulen verwendet, wie z.B.:
- **Analytics-Modul**: Nutzt den EventDispatcher zum Tracking von Systemereignissen
- **DI-Container**: Nutzt Core-Komponenten für die Initialisierung von Services
## Architektur
Das Core-Modul folgt einer ereignisgesteuerten Architektur, bei der Komponenten über Events miteinander kommunizieren können, anstatt direkte Abhängigkeiten zu haben.

89
docs/framework/di/README.md Normal file
View File

@@ -0,0 +1,89 @@
# Dependency Injection Modul
## Übersicht
Das DI-Modul implementiert ein Dependency-Injection-Container-System, das die automatische Auflösung und Verwaltung von Abhängigkeiten ermöglicht.
## Hauptkomponenten
### Container
Der zentrale Service-Container, der Instanzen erstellt und verwaltet.
**Hauptfunktionen:**
- Service-Erstellung und -Auflösung
- Singleton-Verwaltung
- Rekursive Abhängigkeitsauflösung
### Initializer-Attribut
Das `#[Initializer]`-Attribut kennzeichnet Klassen, die Services im Container registrieren können.
**Beispiel:**
```php
#[Initializer]
readonly class AnalyticsInitializer
{
public function __invoke(Container $container): Analytics
{
// Service erstellen und konfigurieren
return $analytics;
}
}
```
## Verwendung
### Service definieren
```php
// Service-Interface
interface MyServiceInterface
{
public function doSomething(): void;
}
// Konkrete Implementierung
class MyService implements MyServiceInterface
{
public function doSomething(): void
{
// Implementierung
}
}
```
### Service registrieren
```php
#[Initializer]
class MyServiceInitializer
{
public function __invoke(Container $container): MyServiceInterface
{
return new MyService();
}
}
```
### Service verwenden
```php
class MyController
{
public function __construct(
private readonly MyServiceInterface $myService
) {}
public function action(): void
{
$this->myService->doSomething();
}
}
```
## Prinzipien
- **Automatische Auflösung**: Abhängigkeiten werden anhand von Typ-Hints automatisch aufgelöst
- **Lazy Loading**: Services werden erst erstellt, wenn sie benötigt werden
- **Singleton-Modus**: Standardmäßig werden Services als Singletons verwaltet

92
docs/framework/http/README.md Normal file
View File

@@ -0,0 +1,92 @@
# HTTP-Modul Dokumentation
## Übersicht
Das HTTP-Modul stellt Komponenten für die Verarbeitung von HTTP-Anfragen und -Antworten bereit.
## Hauptkomponenten
### Request
Repräsentiert eine HTTP-Anfrage mit Methoden zum Zugriff auf:
- HTTP-Methode (`getMethod()`)
- Pfad (`getPath()`)
- Query-Parameter (`getQueryParams()`)
- Request-Body
- Headers
### Response
Repräsentiert eine HTTP-Antwort mit:
- Status-Code (`getStatusCode()`)
- Headers
- Body
### Middleware
Ein Interface für HTTP-Middleware-Komponenten, die die Request-Verarbeitung verändern können:
```php
interface Middleware
{
public function process(Request $request, callable $next): Response;
}
```
**Beispiel-Middleware:**
```php
class AnalyticsMiddleware implements Middleware
{
public function __construct(
private readonly Analytics $analytics
) {}
public function process(Request $request, callable $next): Response
{
// Request tracken
$this->analytics->track('http_request', [
'method' => $request->getMethod(),
'path' => $request->getPath(),
]);
// Request weiterleiten
$response = $next($request);
// Response tracken
$this->analytics->track('http_response', [
'status_code' => $response->getStatusCode(),
]);
return $response;
}
}
```
## Integration mit anderen Modulen
- **Router**: Routing von HTTP-Requests zu Controllers
- **Analytics**: Tracking von HTTP-Requests und -Responses
- **Validation**: Validierung von Request-Daten
## Middlewares registrieren
In der Anwendungsklasse:
```php
$this->addMiddleware(LoggingMiddleware::class);
$this->addMiddleware(AnalyticsMiddleware::class);
$this->addMiddleware(AuthenticationMiddleware::class);
```
## Responses erzeugen
```php
// JSON-Response
return new JsonResponse(['success' => true]);
// HTML-Response
return new HtmlResponse('<html><body>Hello World</body></html>');
// Redirect
return new RedirectResponse('/dashboard');
```

42
docs/framework/index.md Normal file
View File

@@ -0,0 +1,42 @@
# Framework-Dokumentation
## Übersicht
Diese Dokumentation beschreibt die Architektur, Komponenten und Verwendung des Framework-Kerns des Projekts.
## Hauptmodule
- [Analytics](/framework/analytics/README.md) - System zur Erfassung und Analyse von Anwendungsdaten
- [Core](/framework/core/README.md) - Kernkomponenten und Event-System
- [DI (Dependency Injection)](/framework/di/README.md) - Container und Service-Management
- [HTTP](/framework/http/README.md) - HTTP-Request/Response-Handling
## Richtlinien und Muster
- [Modul-Checkliste](/framework/MODUL-CHECKLISTE.md) - Leitfaden für die Erstellung neuer Module
- [Erweiterungsmuster](/framework/ERWEITERUNGSPATTERN.md) - Muster zur Erweiterung des Frameworks
## Modulare Architektur
Das Framework ist modular aufgebaut, mit klaren Verantwortlichkeiten für jedes Modul. Module kommunizieren über klar definierte Interfaces und den Event-Dispatcher.
### Neues Modul erstellen
Um ein neues Modul zu erstellen, folgen Sie der [Modul-Checkliste](/framework/MODUL-CHECKLISTE.md) und beachten Sie die folgenden Kernprinzipien:
1. Klare Verantwortlichkeiten definieren
2. Dependency Injection verwenden
3. Interface-basiertes Design umsetzen
4. Event-basierte Kommunikation nutzen
5. Externe Abhängigkeiten minimieren
### Framework erweitern
Es gibt verschiedene Möglichkeiten, das Framework zu erweitern:
1. **Middleware**: HTTP-Request-Pipeline erweitern
2. **Event-Listener**: Auf System-Events reagieren
3. **Service-Provider**: Eigene Services registrieren
4. **Plugin-System**: Umfangreichere Erweiterungen implementieren
Weitere Details finden Sie im Dokument [Erweiterungsmuster](/framework/ERWEITERUNGSPATTERN.md).

169
docs/guidelines/PERFORMANCE-GUIDELINES.md Normal file
View File

@@ -0,0 +1,169 @@
# Performance-Richtlinien
## Übersicht
Diese Richtlinien beschreiben Best Practices für die Optimierung der Anwendungsleistung im Framework.
## Grundprinzipien
### 1. Frühe Optimierung vermeiden
- Code zuerst korrekt und lesbar schreiben
- Optimierungen auf Basis von Messungen durchführen
- Performance-Engpässe mit dem Profiler identifizieren
### 2. Caching strategisch einsetzen
- Ergebnisse teurer Operationen cachen
- Geeignete Cache-Invalidierungsstrategien implementieren
- Cache-Hierarchie nutzen (Memory → Filesystem → Datenbank)
```php
// Beispiel: Strategisches Caching
public function getExpensiveData(string $key): array
{
$cacheKey = "data_{$key}";
// Prüfen, ob Daten im Cache sind
if ($this->cache->has($cacheKey)) {
return $this->cache->get($cacheKey);
}
// Teure Operation durchführen
$result = $this->performExpensiveOperation($key);
// Ergebnis cachen mit angemessener TTL
$this->cache->set($cacheKey, $result, 3600);
return $result;
}
```
### 3. Lazy Loading
- Ressourcen erst bei Bedarf laden
- Schwere Abhängigkeiten verzögert initialisieren
```php
// Beispiel: Lazy Loading
private ?ExpensiveService $expensiveService = null;
private function getExpensiveService(): ExpensiveService
{
if ($this->expensiveService === null) {
$this->expensiveService = new ExpensiveService($this->config);
}
return $this->expensiveService;
}
```
### 4. Datenstrukturen optimieren
- Passende Datenstrukturen für den Anwendungsfall wählen
- Große Arrays vermeiden, wenn möglich Iteratoren oder Generatoren nutzen
- Bei großen Datenmengen paginieren
```php
// Beispiel: Generator statt Array
public function processLargeDataset(): Generator
{
$handle = fopen($this->largeFile, 'r');
while (($line = fgets($handle)) !== false) {
yield $this->processLine($line);
}
fclose($handle);
}
```
## Spezifische Optimierungen
### Datenbankzugriffe
- Anzahl der Datenbankabfragen minimieren
- Indizes für häufige Abfragen
- N+1 Problem vermeiden durch Eager Loading
- Datenbankverbindungen poolen
### HTTP-Anfragen
- Statische Assets komprimieren und cachen
- HTTP/2 nutzen, wenn möglich
- Content-Kompression aktivieren
- Browser-Caching durch geeignete Header
### Speichernutzung
- Große Objekte nach Gebrauch freigeben (`unset()`)
- Zirkuläre Referenzen vermeiden
- Bei Dateiberarbeitung auf Streaming-Ansätze setzen
### Autoloading
- Composer-Autoloader in Produktionsumgebung optimieren
- Preloading für häufig verwendete Klassen nutzen
```php
// preload.php Beispiel
<?php
declare(strict_types=1);
// Häufig verwendete Klassen vorladen
require_once __DIR__ . '/Framework/Core/Application.php';
require_once __DIR__ . '/Framework/DI/Container.php';
require_once __DIR__ . '/Framework/Http/Request.php';
require_once __DIR__ . '/Framework/Http/Response.php';
```
## Monitoring und Profiling
### Performance messen
- Kritische Code-Pfade instrumentieren
- End-to-End Zeitmessungen durchführen
```php
// Beispiel: Performance-Messung
$startTime = microtime(true);
// Operation durchführen
$result = $this->performOperation();
$duration = microtime(true) - $startTime;
$this->logger->debug("Operation ausgeführt in {$duration}s");
```
### Automatisiertes Monitoring
- Performance-Regressions automatisch erkennen
- Regelmäßige Lasttests durchführen
- Kritische Pfade überwachen
## Umgebungsspezifische Optimierungen
### Entwicklung
- Debug-Tools aktivieren
- Performance-Optimierungen deaktivieren, die Debugging erschweren
### Produktion
- Opcache aktivieren und optimieren
- Fehlerbehandlung optimieren (keine Stack Traces)
- Logging auf nötige Informationen beschränken
```php
// Umgebungsspezifische Einstellungen
if ($environment === 'production') {
ini_set('opcache.validate_timestamps', 0);
ini_set('display_errors', 0);
error_reporting(E_ERROR | E_WARNING | E_PARSE);
} else {
ini_set('opcache.validate_timestamps', 1);
ini_set('display_errors', 1);
error_reporting(E_ALL);
}
```

181
docs/guidelines/TESTING-GUIDELINES.md Normal file
View File

@@ -0,0 +1,181 @@
# Testing-Richtlinien
## Übersicht
Diese Richtlinien beschreiben die Standards und Best Practices für Tests im Framework.
## Grundprinzipien
### 1. Testarten
- **Unit Tests**: Testen einzelner Komponenten isoliert
- **Integrationstests**: Testen des Zusammenspiels mehrerer Komponenten
- **Funktionstests**: Testen ganzer Funktionalitäten aus Benutzersicht
### 2. Pest-Framework
Alle Tests werden mit dem Pest-Framework geschrieben:
```php
test('Analytics::track zeichnet Events korrekt auf', function () {
// Arrange
$manager = new AnalyticsManager(['enabled' => true], new InMemoryStorage());
$analytics = new Analytics($manager, new EventDispatcher());
// Act
$analytics->track('test_event', ['key' => 'value']);
// Assert
expect($manager->getStorage()->retrieve())->toHaveCount(1);
expect($manager->getStorage()->retrieve()[0]['event'])->toBe('test_event');
});
```
### 3. Teststruktur
- Jeder Test folgt dem AAA-Prinzip: Arrange, Act, Assert
- Tests sollten unabhängig voneinander sein
- Tests sollten deterministisch sein (keine zufälligen Ergebnisse)
## Best Practices
### 1. Testabdeckung
- Jede öffentliche Methode sollte getestet werden
- Edge Cases und Fehlersituationen explizit testen
- Fokus auf Business-Logik und kritische Pfade
### 2. Mocking
- Externe Abhängigkeiten mocken
- Eigene Test-Implementierungen für Interfaces erstellen
- Mock-Objekte nur für die spezifischen Testfälle konfigurieren
```php
// Beispiel: Test mit Mock
test('Fehlerbehandlung bei Storage-Ausfall', function () {
// Arrange
$storage = new class implements StorageInterface {
public function store(array $events): void
{
throw new \RuntimeException('Storage-Fehler');
}
public function retrieve(array $filters = []): array
{
return [];
}
public function clear(): void
{
}
};
$manager = new AnalyticsManager(['enabled' => true], $storage);
// Act & Assert
expect(fn() => $manager->flush())->toThrow(\RuntimeException::class);
});
```
### 3. Fixtures und Factories
- Testdaten mit Factories erstellen
- Komplexe Objekte über Helpers aufbauen
- Wiederverwendbare Fixtures für ähnliche Tests
```php
// Beispiel: Test-Factory
function createAnalyticsManager(array $config = []): AnalyticsManager
{
$defaultConfig = ['enabled' => true, 'auto_flush' => false];
return new AnalyticsManager(
array_merge($defaultConfig, $config),
new InMemoryStorage()
);
}
test('Auto-Flush funktioniert korrekt', function () {
// Arrange
$manager = createAnalyticsManager(['auto_flush' => true, 'batch_size' => 2]);
// Act
$manager->track('event1', []);
$manager->track('event2', []);
// Assert
expect($manager->getStorage()->retrieve())->toHaveCount(2);
});
```
### 4. Datenbankzugriffe
- In Unit-Tests Datenbankzugriffe vermeiden oder mocken
- In Integrationstests separate Testdatenbank verwenden
- Testdatenbank nach Tests zurücksetzen
### 5. Asynchrone Tests
- Timeouts für asynchrone Tests setzen
- Auf Async-Events warten, statt feste Wartezeiten
## Testorganisation
### 1. Dateistruktur
- Tests in `/tests`-Verzeichnis mit gleicher Struktur wie `/src`
- Dateinamen mit `Test`-Suffix
### 2. Testgruppen
- Tests mit Attributen in Gruppen einteilen
- Langsame Tests markieren
```php
#[Group('analytics')]
#[Group('slow')]
test('große Datenmenge verarbeiten', function () {
// Test mit vielen Daten
});
```
## CI/CD-Integration
- Tests in CI-Pipeline automatisiert ausführen
- Testabdeckung messen und überwachen
- Pull Requests nur mit erfolgreichen Tests mergen
## Fehlersuche
### 1. Debugging-Techniken
- Pest-Debugging aktivieren mit `->dump()`
- PHPUnit-Assertions für detaillierte Fehlermeldungen
```php
test('komplexes Objekt validieren', function () {
$result = processData();
// Bei Fehlern Kontext ausgeben
if (!expect($result->isValid())->toBeTrue()->isSuccess()) {
dump($result->getErrors());
}
});
```
### 2. Problematische Tests
- Flaky Tests identifizieren und beheben
- Tests isolieren mit `only` oder `skip`
```php
test('problematischer Test', function () {
// Test-Code
})->skip('Wird untersucht');
```
## Zusammenfassung
- Tests sind ein integraler Bestandteil der Codebase
- Qualität und Wartbarkeit der Tests sind genauso wichtig wie die des Produktionscodes
- Tests dienen als lebende Dokumentation der Funktionalität

43
docs/guidelines/index.md Normal file
View File

@@ -0,0 +1,43 @@
# Entwicklungsrichtlinien
## Übersicht
Diese Richtlinien bieten Best Practices und Standards für die Entwicklung innerhalb des Projekts. Sie helfen, qualitativ hochwertigen, wartbaren und leistungsfähigen Code zu schreiben.
## Verfügbare Richtlinien
- [Performance-Richtlinien](/guidelines/PERFORMANCE-GUIDELINES.md) - Optimierung der Anwendungsleistung
- [Testing-Richtlinien](/guidelines/TESTING-GUIDELINES.md) - Standards und Best Practices für Tests
## Performance-Optimierung
Leistungsoptimierung ist ein wichtiger Aspekt der Anwendungsentwicklung. Die [Performance-Richtlinien](/guidelines/PERFORMANCE-GUIDELINES.md) bieten Einblicke in:
- Strategisches Caching
- Lazy Loading
- Optimierung von Datenbankabfragen
- Effiziente Datenstrukturen
- Speichernutzung
## Teststrategien
Testen ist ein integraler Bestandteil des Entwicklungsprozesses. Die [Testing-Richtlinien](/guidelines/TESTING-GUIDELINES.md) decken folgende Themen ab:
- Unit Tests mit Pest-Framework
- Integrationstests
- Test-Fixtures und Factories
- Mocking-Strategien
- Testorganisation und -struktur
## Anwendung der Richtlinien
Diese Richtlinien sollten in allen Phasen der Entwicklung berücksichtigt werden:
1. **Planungsphase**: Frühzeitige Berücksichtigung von Performance und Testbarkeit
2. **Implementierungsphase**: Anwendung der Best Practices während der Entwicklung
3. **Review-Phase**: Überprüfung des Codes anhand der Richtlinien
4. **Refactoring**: Verbesserung bestehenden Codes gemäß den Richtlinien
## Continuous Improvement
Diese Richtlinien werden kontinuierlich verbessert und aktualisiert. Wenn Sie Vorschläge zur Verbesserung haben, zögern Sie nicht, diese einzubringen.

35
docs/index.md Normal file
View File

@@ -0,0 +1,35 @@
# Projekt-Dokumentation
## Willkommen zur Projektdokumentation
Diese Dokumentation bietet umfassende Informationen zu Coding-Standards, Architektur, Best Practices und Framework-Komponenten des Projekts.
## Schnellzugriff
- [Coding-Guidelines](/standards/CODING-GUIDELINES.md)
- [Sicherheitsrichtlinien](/standards/SICHERHEITS-GUIDELINES.md)
- [Projektstruktur](/architecture/STRUKTUR-DOKUMENTATION.md)
- [Performance-Optimierung](/guidelines/PERFORMANCE-GUIDELINES.md)
- [KI-Assistent Einrichtung](/ai/EINRICHTUNG-PHPSTORM.md)
## Dokumentationsstruktur
Die Dokumentation ist in verschiedene Bereiche unterteilt:
- **Standards und Guidelines**: Grundlegende Prinzipien und Richtlinien für die Entwicklung
- **Framework-Module**: Dokumentation zu den einzelnen Framework-Komponenten
- **Entwicklungsrichtlinien**: Detaillierte Anleitungen zu Performance, Testing und mehr
- **Architektur**: Übersicht und Details zur Systemarchitektur
- **KI-Assistent-Integration**: Anleitung zur Verwendung des KI-Assistenten
## Für neue Entwickler
Wenn Sie neu im Projekt sind, empfehlen wir Ihnen, mit folgenden Dokumenten zu beginnen:
1. [Projektstruktur](/architecture/STRUKTUR-DOKUMENTATION.md) - Um einen Überblick zu bekommen
2. [Coding-Guidelines](/standards/CODING-GUIDELINES.md) - Um die Coding-Standards zu verstehen
3. [Modul-Checkliste](/framework/MODUL-CHECKLISTE.md) - Um die Modularisierung zu verstehen
## Beitragen zur Dokumentation
Die Dokumentation ist ein lebendiges Dokument. Wenn Sie Fehler finden oder Verbesserungen vorschlagen möchten, erstellen Sie bitte einen Pull Request mit Ihren Änderungen.

234
docs/standards/CODING-GUIDELINES.md Normal file
View File

@@ -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

187
docs/standards/SICHERHEITS-GUIDELINES.md Normal file
View File

@@ -0,0 +1,187 @@
# Sicherheitsrichtlinien
## Übersicht
Diese Richtlinien definieren Standards und Best Practices für sichere Softwareentwicklung im Projekt.
## Grundprinzipien
### 1. Defense in Depth
- Mehrere Sicherheitsschichten implementieren
- Nicht auf eine einzelne Sicherheitsmaßnahme vertrauen
- Fail-Safe-Mechanismen einbauen
### 2. Least Privilege
- Minimale Berechtigungen für Funktionen und Benutzer
- Ressourcenzugriff nur bei Bedarf gewähren
- Temporäre Berechtigungen nach Gebrauch entziehen
### 3. Input-Validierung
- Alle Benutzereingaben validieren und bereinigen
- Whitelist-Ansatz bevorzugen (erlaubte Eingaben definieren)
- Typprüfung und Formatvalidierung durchführen
```php
// Beispiel: Sichere Input-Validierung
public function processUserInput(string $input): string
{
// Länge prüfen
if (strlen($input) > 100) {
throw new ValidationException('Input zu lang (max 100 Zeichen)');
}
// Inhalt validieren (Whitelist-Ansatz)
if (!preg_match('/^[a-zA-Z0-9\s\-_]+$/', $input)) {
throw new ValidationException('Input enthält ungültige Zeichen');
}
// Bereinigung
return htmlspecialchars($input, ENT_QUOTES, 'UTF-8');
}
```
## Spezifische Sicherheitsmaßnahmen
### 1. SQL-Injection-Prävention
- Prepared Statements für alle Datenbankabfragen
- Keine dynamischen SQL-Queries
- ORM-Framework bevorzugen
```php
// Sicher
$stmt = $pdo->prepare("SELECT * FROM users WHERE email = ?");
$stmt->execute([$email]);
// Unsicher - NIEMALS SO MACHEN
$query = "SELECT * FROM users WHERE email = '{$email}'";
```
### 2. Cross-Site Scripting (XSS) Prävention
- Output-Escaping für alle benutzergenerierten Inhalte
- Content-Security-Policy (CSP) implementieren
- HttpOnly und Secure Flags für Cookies
```php
// Ausgabe in HTML
echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
// Ausgabe in JavaScript
echo json_encode($userInput, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP);
```
### 3. Cross-Site Request Forgery (CSRF) Schutz
- CSRF-Token für alle ändernden Anfragen
- SameSite-Attribut für Cookies
```php
// CSRF-Token generieren
public function generateCsrfToken(): string
{
$token = bin2hex(random_bytes(32));
$_SESSION['csrf_token'] = $token;
return $token;
}
// CSRF-Token validieren
public function validateCsrfToken(string $token): bool
{
return hash_equals($_SESSION['csrf_token'] ?? '', $token);
}
```
### 4. Sichere Authentifizierung
- Passwörter mit starken Algorithmen hashen (Argon2id)
- Multi-Faktor-Authentifizierung anbieten
- Ratelimiting für Login-Versuche
```php
// Passwort hashen
public function hashPassword(string $password): string
{
return password_hash($password, PASSWORD_ARGON2ID);
}
// Passwort verifizieren
public function verifyPassword(string $password, string $hash): bool
{
return password_verify($password, $hash);
}
```
### 5. Sichere Datenspeicherung
- Sensible Daten verschlüsseln
- Separate Schlüssel für unterschiedliche Daten
- Schlüsselrotation implementieren
```php
// Daten verschlüsseln
public function encrypt(string $data, string $purpose): string
{
$key = $this->getEncryptionKey($purpose);
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$cipher = sodium_crypto_secretbox(
$data,
$nonce,
$key
);
return base64_encode($nonce . $cipher);
}
// Daten entschlüsseln
public function decrypt(string $encrypted, string $purpose): string
{
$key = $this->getEncryptionKey($purpose);
$decoded = base64_decode($encrypted);
$nonce = mb_substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, '8bit');
$cipher = mb_substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, null, '8bit');
return sodium_crypto_secretbox_open(
$cipher,
$nonce,
$key
);
}
```
## Sicherheitstests
### 1. Automatisierte Sicherheitstests
- Static Application Security Testing (SAST)
- Dynamic Application Security Testing (DAST)
- Dependency-Scanning für bekannte Schwachstellen
### 2. Penetrationstests
- Regelmäßige Sicherheitsaudits
- Manuelle Penetrationstests
- Bug-Bounty-Programme
## Sicherheitskultur
### 1. Entwicklerschulungen
- Regelmäßige Sicherheitsschulungen
- Code-Reviews mit Sicherheitsfokus
- Sicherheits-Champions im Team
### 2. Incident Response
- Sicherheitsvorfälle dokumentieren
- Prozess für Sicherheitsmeldungen
- Notfallpläne für Sicherheitsvorfälle
## Zusammenfassung
Sicherheit ist ein kontinuierlicher Prozess, keine einmalige Aufgabe. Diese Richtlinien sollten regelmäßig überprüft und aktualisiert werden, um neuen Bedrohungen zu begegnen.

50
docs/standards/index.md Normal file
View File

@@ -0,0 +1,50 @@
# Coding-Standards und Richtlinien
## Übersicht
Diese Standards und Richtlinien definieren die grundlegenden Prinzipien für die Codierung und Sicherheit im Projekt. Sie gewährleisten Konsistenz, Wartbarkeit und Sicherheit des Codes.
## Verfügbare Standards
- [Coding Guidelines](/standards/CODING-GUIDELINES.md) - Allgemeine Coding-Standards für das Projekt
- [Sicherheitsrichtlinien](/standards/SICHERHEITS-GUIDELINES.md) - Standards für sichere Softwareentwicklung
## Coding Guidelines
Die [Coding Guidelines](/standards/CODING-GUIDELINES.md) definieren die technischen Standards für die Codeentwicklung, einschließlich:
- Klassenstruktur und -design
- Property- und Methodendefinitionen
- Nutzung moderner PHP-Features
- Fehlerbehandlung
- Dokumentation
- Namenskonventionen
## Sicherheitsrichtlinien
Die [Sicherheitsrichtlinien](/standards/SICHERHEITS-GUIDELINES.md) bieten umfassende Anleitungen zur sicheren Softwareentwicklung:
- Input-Validierung
- SQL-Injection-Prävention
- XSS-Schutz
- CSRF-Schutz
- Sichere Authentifizierung
- Sichere Datenspeicherung
- Session-Management
## Anwendung der Standards
Alle Teammitglieder sind verpflichtet, diese Standards in ihrer Arbeit anzuwenden. Sie dienen als Grundlage für Code-Reviews und Qualitätssicherung.
## Abweichungen von Standards
In Ausnahmefällen können Abweichungen von diesen Standards erforderlich sein. Solche Abweichungen sollten:
1. Dokumentiert werden
2. Begründet werden
3. Im Team besprochen werden
4. Auf ein Minimum beschränkt werden
## Aktualisierungen
Diese Standards werden regelmäßig überprüft und aktualisiert, um sicherzustellen, dass sie den neuesten Best Practices und Technologien entsprechen.