michaelschiemer/docs/architecture/components.md

Hauptkomponenten

Diese Dokumentation beschreibt die Hauptkomponenten des Frameworks und ihre Verantwortlichkeiten. Jede Komponente ist so konzipiert, dass sie unabhängig verwendet oder durch eine benutzerdefinierte Implementierung ersetzt werden kann.

Kernkomponenten

Container

Der Container ist das Herzstück des Frameworks und verantwortlich für die Dependency Injection. Er bietet folgende Funktionen:

• Registrierung von Diensten
• Auflösung von Abhängigkeiten
• Verwaltung des Lebenszyklus von Diensten

// Beispiel für die Verwendung des Containers
$container = new Container();
$container->bind(LoggerInterface::class, FileLogger::class);
$container->singleton(DatabaseInterface::class, function () {
    return new Database(config('database'));
});

$logger = $container->get(LoggerInterface::class);

Router

Der Router ist verantwortlich für das Mapping von HTTP-Anfragen zu Controller-Aktionen. Er unterstützt:

• Routendefinitionen für verschiedene HTTP-Methoden
• Routengruppen mit gemeinsamen Präfixen und Middleware
• Routenparameter und Einschränkungen
• Namensräume für Routen

// Beispiel für die Verwendung des Routers
$router = new Router();
$router->get('/users', [UserController::class, 'index']);
$router->post('/users', [UserController::class, 'store']);
$router->get('/users/{id}', [UserController::class, 'show'])->where('id', '[0-9]+');

$router->group('/admin', function (Router $router) {
    $router->get('/dashboard', [AdminController::class, 'dashboard']);
})->middleware(AuthMiddleware::class);

Request

Die Request-Klasse kapselt eine HTTP-Anfrage und bietet Methoden für den Zugriff auf:

• Anfrageparameter
• Header
• Cookies
• Dateien
• Sitzungsdaten

// Beispiel für die Verwendung der Request-Klasse
$name = $request->input('name');
$page = $request->query('page', 1);
$token = $request->header('Authorization');
$file = $request->file('avatar');
$remember = $request->cookie('remember', false);
$user = $request->session()->get('user');

Response

Die Response-Klasse repräsentiert eine HTTP-Antwort und bietet Methoden für:

• Setzen von Statuscodes
• Hinzufügen von Headern
• Setzen von Cookies
• Umleitung zu anderen URLs

// Beispiel für die Verwendung der Response-Klasse
$response = new Response('Hello World', 200);
$response->header('Content-Type', 'text/plain');
$response->cookie('visited', true, 60 * 24);

$redirectResponse = new RedirectResponse('/dashboard');
$jsonResponse = new JsonResponse(['name' => 'John']);
$viewResponse = new ViewResponse('welcome', ['user' => $user]);

Middleware

Middleware-Komponenten verarbeiten Anfragen vor und nach der Controller-Aktion. Sie können:

• Anfragen validieren
• Benutzer authentifizieren
• Antworten transformieren
• Anfragen protokollieren

// Beispiel für eine Middleware
class AuthMiddleware implements MiddlewareInterface
{
    public function process(Request $request, RequestHandlerInterface $handler): Response
    {
        if (!$this->isAuthenticated($request)) {
            return new RedirectResponse('/login');
        }
        
        return $handler->handle($request);
    }
}

Datenbankkomponenten

Database

Die Database-Komponente bietet eine Abstraktionsschicht für Datenbankoperationen. Sie unterstützt:

• Verschiedene Datenbanktypen (MySQL, SQLite, PostgreSQL)
• Abfragen mit einem Query Builder
• Transaktionen
• Migrationen
• Seeding

// Beispiel für die Verwendung der Database-Komponente
$users = $database->table('users')
    ->where('active', true)
    ->orderBy('name')
    ->limit(10)
    ->get();

$database->transaction(function ($db) {
    $db->table('users')->insert(['name' => 'John']);
    $db->table('profiles')->insert(['user_id' => $db->lastInsertId()]);
});

Model

Die Model-Komponente bietet eine objektorientierte Schnittstelle für Datenbankoperationen. Sie unterstützt:

• Active Record Pattern
• Beziehungen zwischen Modellen
• Attribute und Mutators
• Ereignisse

// Beispiel für die Verwendung der Model-Komponente
$user = new User();
$user->name = 'John';
$user->email = 'john@example.com';
$user->save();

$users = User::where('active', true)->get();
$user = User::find(1);
$posts = $user->posts()->where('published', true)->get();

Migration

Die Migration-Komponente ermöglicht die Versionierung der Datenbankstruktur. Sie unterstützt:

• Erstellen und Ändern von Tabellen
• Hinzufügen und Entfernen von Indizes
• Rollback von Änderungen

// Beispiel für eine Migration
class CreateUsersTable extends Migration
{
    public function up(): void
    {
        $this->schema->create('users', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->string('password');
            $table->boolean('active')->default(true);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        $this->schema->dropIfExists('users');
    }
}

HTTP-Komponenten

Controller

Controller sind verantwortlich für die Verarbeitung von HTTP-Anfragen und die Rückgabe von Antworten. Sie bieten:

• Zugriff auf Request- und Response-Objekte
• Validierung von Eingaben
• Rendering von Views
• Umleitung zu anderen URLs

// Beispiel für einen Controller
class UserController extends Controller
{
    public function index(Request $request): Response
    {
        $users = User::all();
        return $this->view('users.index', ['users' => $users]);
    }

    public function store(Request $request): Response
    {
        $this->validate($request, [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users,email',
        ]);

        $user = User::create($request->only(['name', 'email']));
        return $this->redirect('/users')->with('success', 'User created');
    }
}

View

Die View-Komponente ist verantwortlich für das Rendering von HTML-Templates. Sie unterstützt:

• Template-Dateien mit PHP-Syntax
• Layouts und Partials
• Template-Vererbung
• Datenübergabe an Templates

// Beispiel für die Verwendung der View-Komponente
$view = new View('users.show');
$view->with('user', $user);
$html = $view->render();

// Oder über den Controller
return $this->view('users.show', ['user' => $user]);

Session

Die Session-Komponente verwaltet Benutzersitzungen. Sie unterstützt:

• Verschiedene Session-Backends (Datei, Datenbank, Redis)
• Flash-Daten
• Session-Regeneration
• Session-Timeout

// Beispiel für die Verwendung der Session-Komponente
$session = new Session();
$session->put('user_id', 1);
$userId = $session->get('user_id');
$session->flash('message', 'Welcome back!');
$session->regenerate();
$session->forget('user_id');

Cookie

Die Cookie-Komponente verwaltet HTTP-Cookies. Sie unterstützt:

• Setzen und Lesen von Cookies
• Verschlüsselung von Cookie-Werten
• Cookie-Parameter (Lebensdauer, Pfad, Domain, Secure, HttpOnly)

// Beispiel für die Verwendung der Cookie-Komponente
$cookie = new Cookie('name', 'value', 60 * 24); // 1 Tag
$cookie->setPath('/');
$cookie->setSecure(true);
$cookie->setHttpOnly(true);

$response->setCookie($cookie);
$value = $request->cookie('name');

Sicherheitskomponenten

Validator

Die Validator-Komponente validiert Benutzereingaben. Sie unterstützt:

• Verschiedene Validierungsregeln
• Benutzerdefinierte Validierungsregeln
• Fehlermeldungen
• Validierung von Arrays und verschachtelten Daten

// Beispiel für die Verwendung der Validator-Komponente
$validator = new Validator($data, [
    'name' => 'required|string|max:255',
    'email' => 'required|email|unique:users,email',
    'password' => 'required|string|min:8|confirmed',
    'age' => 'integer|min:18',
]);

if ($validator->fails()) {
    $errors = $validator->errors();
    // Fehler behandeln
}

Authentication

Die Authentication-Komponente verwaltet die Benutzerauthentifizierung. Sie unterstützt:

• Verschiedene Authentifizierungsmethoden (Session, Token, Basic)
• Mehrere Authentifizierungsquellen
• Remember-Me-Funktionalität
• Passwort-Hashing und -Verifizierung

// Beispiel für die Verwendung der Authentication-Komponente
$auth = new Authentication();
if ($auth->attempt(['email' => $email, 'password' => $password], $remember)) {
    // Erfolgreiche Anmeldung
}

$user = $auth->user();
$auth->logout();

Authorization

Die Authorization-Komponente verwaltet die Benutzerautorisierung. Sie unterstützt:

• Rollenbasierte Zugriffskontrolle
• Fähigkeitsbasierte Zugriffskontrolle
• Richtlinien für komplexe Autorisierungslogik

// Beispiel für die Verwendung der Authorization-Komponente
$authorization = new Authorization();
$authorization->define('edit-post', function (User $user, Post $post) {
    return $user->id === $post->user_id || $user->hasRole('editor');
});

if ($authorization->can($user, 'edit-post', $post)) {
    // Benutzer darf den Beitrag bearbeiten
}

CSRF

Die CSRF-Komponente schützt vor Cross-Site Request Forgery. Sie unterstützt:

• Generierung von CSRF-Tokens
• Validierung von CSRF-Tokens
• Automatische Integration in Formulare

// Beispiel für die Verwendung der CSRF-Komponente
$csrf = new CsrfProtection();
$token = $csrf->generateToken();

// In einem Formular
echo '<input type="hidden" name="_token" value="' . $token . '">';

// Validierung
if (!$csrf->validateToken($request->input('_token'))) {
    // Ungültiges Token
}

WAF

Die Web Application Firewall (WAF) schützt vor gängigen Angriffen. Sie unterstützt:

• Erkennung und Blockierung von SQL-Injection
• Erkennung und Blockierung von XSS
• Erkennung und Blockierung von Command Injection
• Erkennung und Blockierung von Path Traversal
• Maschinelles Lernen zur Erkennung von Anomalien

// Beispiel für die Verwendung der WAF-Komponente
$waf = new WebApplicationFirewall();
$waf->addRule(new SqlInjectionRule());
$waf->addRule(new XssRule());

if ($waf->detect($request)) {
    // Angriff erkannt
    $waf->block($request);
}

Weitere Komponenten

Cache

Die Cache-Komponente bietet eine einheitliche Schnittstelle für verschiedene Cache-Backends. Sie unterstützt:

• Verschiedene Cache-Treiber (Datei, Redis, Memcached, Memory)
• Cache-Tags
• Cache-Invalidierung
• Cache-Prefixing

// Beispiel für die Verwendung der Cache-Komponente
$cache = new Cache();
$cache->put('key', 'value', 60); // 60 Minuten
$value = $cache->get('key', 'default');
$cache->has('key');
$cache->forget('key');
$cache->flush();

$cache->tags(['users', 'profiles'])->put('user:1', $user, 60);

Logger

Die Logger-Komponente protokolliert Anwendungsereignisse. Sie unterstützt:

• Verschiedene Log-Level (Debug, Info, Warning, Error, Critical)
• Verschiedene Log-Handler (Datei, Syslog, Slack, E-Mail)
• Kontextdaten für Log-Einträge
• Log-Rotation

// Beispiel für die Verwendung der Logger-Komponente
$logger = new Logger();
$logger->debug('Debug-Nachricht');
$logger->info('Info-Nachricht');
$logger->warning('Warnung', ['user_id' => 1]);
$logger->error('Fehler', ['exception' => $exception]);
$logger->critical('Kritischer Fehler', ['data' => $data]);

Event

Die Event-Komponente implementiert ein Publish-Subscribe-Muster. Sie unterstützt:

• Ereignisregistrierung und -auslösung
• Ereignislistener
• Ereignisabonnenten
• Ereignispriorisierung

// Beispiel für die Verwendung der Event-Komponente
$eventDispatcher = new EventDispatcher();
$eventDispatcher->addListener(UserRegistered::class, SendWelcomeEmail::class);
$eventDispatcher->addListener(UserRegistered::class, function (UserRegistered $event) {
    // Benutzerdefinierte Logik
});

$eventDispatcher->dispatch(new UserRegistered($user));

Console

Die Console-Komponente bietet ein Kommandozeilen-Interface für die Anwendung. Sie unterstützt:

• Benutzerdefinierte Befehle
• Eingabeargumente und -optionen
• Interaktive Eingabe
• Ausgabeformatierung

// Beispiel für einen Konsolenbefehl
class MigrateCommand extends Command
{
    protected string $name = 'db:migrate';
    protected string $description = 'Run database migrations';

    public function handle(Input $input, Output $output): int
    {
        $output->writeln('Running migrations...');
        // Migrationen ausführen
        $output->success('Migrations completed successfully');
        return 0;
    }
}

Filesystem

Die Filesystem-Komponente bietet eine Abstraktionsschicht für Dateisystemoperationen. Sie unterstützt:

• Lokale und entfernte Dateisysteme
• Datei- und Verzeichnisoperationen
• Dateimetadaten
• Dateispeicherung und -abruf

// Beispiel für die Verwendung der Filesystem-Komponente
$filesystem = new Filesystem();
$filesystem->write('path/to/file.txt', 'Inhalt');
$content = $filesystem->read('path/to/file.txt');
$filesystem->delete('path/to/file.txt');
$filesystem->createDirectory('path/to/directory');
$files = $filesystem->listContents('path/to/directory');

Queue

Die Queue-Komponente ermöglicht die asynchrone Verarbeitung von Aufgaben. Sie unterstützt:

• Verschiedene Queue-Treiber (Datenbank, Redis, Beanstalkd)
• Verzögerte Aufgaben
• Aufgabenpriorisierung
• Fehlerbehandlung und Wiederholungsversuche

// Beispiel für die Verwendung der Queue-Komponente
$queue = new Queue();
$queue->push(new SendEmailJob($user, $message));
$queue->later(60, new CleanupJob()); // 60 Sekunden verzögert

// Verarbeitung einer Aufgabe
class SendEmailJob implements JobInterface
{
    public function __construct(private User $user, private string $message) {}

    public function handle(): void
    {
        // E-Mail senden
    }
}

Weitere Informationen

• Architekturübersicht: Überblick über die Architektur des Frameworks.
• Entwurfsmuster: Erläuterung der im Framework verwendeten Entwurfsmuster.
• Komponentendokumentation: Detaillierte Dokumentation der einzelnen Komponenten.