michaelschiemer/docs/FRAMEWORK_IMPROVEMENTS_ROADMAP.md

Framework-Verbesserungen: Feature-Vorschläge und Refactoring-Roadmap

Dieses Dokument sammelt konkrete, priorisierte Vorschläge für neue Features im Framework sowie Refactorings. Ziel ist es, Stabilität, Performance, Developer Experience (DX) und Sicherheit weiter zu erhöhen, ohne den bestehenden Stil (DDD, klare Layer) zu brechen.

Inhalt

• Leitprinzipien
• Quick Wins (0–2 Tage)
• Mittelfristig (3–10 Tage)
• Größere Vorhaben (>10 Tage)
• Detaillierte Vorschläge je Komponente
• Querschnittsthemen (Code-Qualität, Tests, Security)
• Migrations- und Deprecation-Strategie

Leitprinzipien

• Stabilität zuerst: Abwärtskompatibilität, saubere Deprecation-Pfade
• Sichtbare Wirkung: Quick Wins priorisieren, die Sicherheits- und Performance-Gewinne bringen
• Messbarkeit: Jede Maßnahme mit Akzeptanzkriterien (Tests, Metriken)
• Standards nutzen: PSR (3/6/7/11/14/15/16/17), OpenTelemetry, Problem+JSON

Quick Wins (0–2 Tage)

1. HTTP-Härtung und Caching-Header (Http)

• Feature: Standard-Response-Header: Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options (konfigurierbar), Referrer-Policy, Permissions-Policy
• Feature: ETag/Last-Modified Support in Responses (konditionelle Requests)
• Akzeptanz: Pest-Tests für Header-Präsenz und ETag-Validierung; Konfiguration via config/

2. Rate Limiting Middleware (Http/Security)

• Token Bucket oder Sliding Window pro IP/Route
• Akzeptanz: Tests für 200/429-Flows, Reset-Logik, Redis-Backend optional

3. Standardisierte Fehlerantworten (Error Handling)

• Feature: RFC 7807 Problem+JSON (application/problem+json) für 4xx/5xx
• Akzeptanz: Tests prüfen Struktur (type, title, status, detail, instance)

4. Validation: Konsistente Fehlermeldungen und i18n-Keys (Validation)

• Feature: Nachrichtenschlüssel mit Platzhaltern; deutsche Default-Texte
• Akzeptanz: Tests für Regeln, Übersetzungen, Platzhalterersetzung

5. PHPStan-Level erhöhen (Code Quality)

• Level schrittweise von aktuellem Baseline-Stand her anheben; neue generische Typen ergänzen
• Akzeptanz: composer phpstan läuft ohne neue Fehler; aktualisierte Baseline minimal

Mittelfristig (3–10 Tage) 6) PSR-7/15/17-Kompatibilität (Http)

• Adapter-Schicht bereitstellen, sodass Requests/Responses als PSR-Objekte nutzbar sind
• Akzeptanz: Interop-Tests; Middleware-Pipeline kompatibel

7. Cache-Verbesserungen (Cache)

• PSR-16 SimpleCache und PSR-6 Caching Pools
• Stampede-Protection (Early Recompute, Jitter), Tagging, TTL-Strategien
• Akzeptanz: Konkurrierende Zugriffe in Tests, Hit/Miss-Statistiken

8. Datenbank-Transaktions- und Retry-Policy (Database)

• Einheitliche Transaktions-API (begin/commit/rollback) mit dekorierbaren Retries (Exponential Backoff, Deadlock-Erkennung)
• Read/Write-Splitting und Failover-Konfiguration
• Akzeptanz: Tests mit simulierten Deadlocks/Fehlercodes; idempotente Retries

9. Observability (Framework/Observability)

• PSR-3 Logging-Bridge, strukturierte Logs (JSON), Kontextfelder
• OpenTelemetry-Exporter (Trace/Span), Request/DB/Cache-Instrumentierung
• Akzeptanz: Beispiel-Trace sichtbar; Logs enthalten Korrelation-IDs

10. Konsistentes Config-System (Config)

• Typisierte Konfiguration mit Env-Mapping, Defaults, Validatoren
• Akzeptanz: Fehlkonfigurations-Tests, Fallbacks greifen

Größere Vorhaben (>10 Tage) 11) Job/Queue-Subsystem (Infrastructure)

• Abstraktion mit Redis/MariaDB-Backend, Delayed Jobs, Retries, Dead-Letter-Queue, Rate Limits, Worker-Signale (graceful shutdown)
• Akzeptanz: End-to-End-Tests; At-Least-Once-Garantie; Sichtbarkeit im Admin

12. WAF-Regel-Engine (Waf)

• Modular: IP-Reputation, Anomalie-Scoring, Ratelimit je Route, Request-Body-Inspektion (größenbegrenzt), Safe-List/Block-List
• Akzeptanz: Tests für False-Positive-Vermeidung, Audit-Logs, Bypass für Admin-Routen

13. View-System-Verbesserungen (View)

• Template-Precompilation/Caching, Komponenten/Slots, CSRF-Helfer, sichere Auto-Escapes
• Akzeptanz: Render-Performance-Benchmark, XSS-Schutz-Tests

14. Datenbank-Migrationsmodul (Database)

• Versionierte Migrationen, Seeders, Rollbacks, Dry-Run, Checksum-Prüfung
• Akzeptanz: Migrator-Tests, Konflikterkennung, sichere Re-Runs

15. Filesystem-Abstraktion (Infrastructure)

• Lokales FS, S3 kompatibel; Stream-Support, signierte URLs, Limits
• Akzeptanz: Integrationstests mit Mock-Storage; Fehlerpfade

Detaillierte Vorschläge je Komponente

Analytics

• Pageview/Event-API, Sampling, Anonymisierung (IP-Hash), Opt-Out-Cookie
• Akzeptanz: Events werden im Backend gezählt, DSGVO-Optionen konfigurierbar

Cache

• PSR-16/6, Tagging, Stampede-Schutz (probabilistic early refresh), Cache Warmer, Locking
• Redis als Primärbackend, APCu als In-Memory

Console

• Auto-Discovery von Commands per Attribute, Lazy-Loading, Progress/Spinner-UX, Table-Helper
• Akzeptanz: discoverbare Commands ohne manuelle Registrierung

Database

• Verbindungs-Pool (persistent), Read/Write-Splitting, Retry-Policy, Type-Mapping (DateTimeImmutable, Uuid VO)
• Unit-of-Work optional

DateTime

• Clock-Interface ist vorhanden; ergänzen: Freeze/Travel-Helfer im Test-Kit; monotone Timer für Metriken

Http

• Middleware-Pipeline, PSR-Adapter, konditionelle Antworten (304), Streaming-Responses, Content-Negotiation

Random

• CSPRNG-Wrapper (random_bytes) + Testable Generator (existiert): ergänzen: hex(), int(min,max), uuidV7()

Security

• CSP-Builder, SameSite=strict Cookies, Secure/Httponly Defaults, Secrets-Management (Key-Rotation), Passwort-Hash-Policy (argon2id), CSRF-Token Middleware

Validation

• Regel-Objekte, Composable Rules, i18n-Messages, Custom Rule Registry, ValidationResult Value Object

View

• Komponenten/Slots, Layout-Inheritance, Asset-Helper (integrity Attrs), Template-Cache, Escaping-Policies

Waf

• Regel-Engine, Score-basierte Entscheidungen, einstellbare Schweregrade, Beobachtungsmodus vs. Blocken

Observability

• Request-ID, Correlation-ID, Trace-Propagation (W3C), Metriken (Latenzen, Error-Rates), Export nach OTLP

Config

• Typed Config Klassen mit Validierung, sichere Defaults, Secrets via Env/Files

Fehlerbehandlung

• Problem+JSON, saubere Exception-Hierarchie (Domain, Infra, Http), Mapping auf Statuscodes, Fehlerseiten

Queue/Jobs

• Wiederholungen, Dead-Letter, Backoff, deduplizierte Jobs, Schedule/CRON-ähnlich

Filesystem

• Adapter-Interface, Streams, Limits, Prüfsummen, sichere Upload-Pfade, Virenscan-Hook (optional)

Feature Flags

• Boolean und Gradual Rollouts (Percentage, Targeting), Config-gesteuert, In-Memory + Redis Store

Health Checks

• Readiness/Liveness Endpoints, DB/Cache/Ping, Build-Info (Git SHA, Time)

Scheduler

• Cron-DSL, verteilte Locks, Missed-Run-Catching, Backfill

Querschnittsthemen (Code-Qualität, Tests, Security)

• Tests: Pest Coverage für Kernmodule; Integrationstests mit Docker Services (DB/Redis)
• Static Analysis: PHPStan Regeln für generics, Psalm optional; Stricte Types überall
• DX: Makefile/Composer Skripte für häufige Tasks; Vorlagen für neue Module
• Security: Secure Defaults, Threat Modeling pro Modul, Security-Header als Middleware

Migrations- und Deprecation-Strategie

• Semver beachten; @deprecated Tags mit Ersatz und Removal-Version
• Feature-Flags für riskante Änderungen
• Migrationsleitfaden in docs/CHANGES.md mit Codebeispielen

Priorisierung (Kurzfassung)

• Jetzt: (1) Security/HTTP-Header, (2) Rate Limiting, (3) Problem+JSON, (4) Validation i18n
• Als Nächstes: (6) PSR-7/15, (7) Cache, (8) DB-Transaktionen/Retry, (9) Observability, (10) Config
• Großprojekte: (11) Queue, (12) WAF, (14) Migrations, (13) View-Verbesserungen

Akzeptanzkriterien (Beispielschablone je Ticket)

• Was: Kurzbeschreibung
• Warum: Nutzen/Impact
• Done:
  • Pest-Tests decken Erfolg und Fehler ab
  • Dokumentation in docs/ aktualisiert
  • Konfiguration via config/ möglich
  • Kein Bruch bestehender APIs oder Deprecation-Hinweis vorhanden