php-func-lib/NEXT_STEPS.md

Next Steps

Issue Drafts (Ready for Gitea/GitHub)

• #TODO Define unified error strategy

• Aufwand: M

• Labels: quality, api

• Ziel: Einheitliches Verhalten bei Fehlern.

• Akzeptanzkriterien:

• ADR/kurze Doku: wann null/false, wann Exception.

• sql.php, link-meta.php, troy-api.php folgen derselben Strategie.

• Mindestens 3 Beispiele in README.md dokumentiert.

• #TODO Expand README with runnable examples

• Aufwand: S

• Labels: docs

• Ziel: Schnellere Nutzung ohne Code-Lesen.

• Akzeptanzkriterien:

• Pro Modul mindestens 1 kurzes Copy/Paste-Beispiel.

• Abschnitt "Konfiguration" mit secret.php-Feldern vorhanden.

• Abschnitt "Known limitations" ergaenzt.

• #TODO Complete secret.php.example

• Aufwand: S

• Labels: docs, config

• Ziel: Vollstaendige Vorlagedatei fuer lokale Setups.

• Akzeptanzkriterien:

• Alle erwarteten Variablen aus sql.php, mail.php, troy-api.php enthalten.

• Jede Variable hat kurzen Kommentar.

• Dateiformat entspricht direkt nutzbarer Vorlage.

5) Remove @ error suppression incrementally

• Aufwand: M
• Labels: quality, safety
• Ziel: Fehler sichtbar und kontrolliert behandeln.
• Akzeptanzkriterien:
• Alle @-Operatoren inventarisiert.
• Ersetzungen mit explizitem Error-Handling umgesetzt.
• Keine neue @-Verwendung in geaenderten Dateien.

2) Sicherheit und Robustheit

6) Harden URL fetching against SSRF

• Aufwand: M
• Labels: security, network
• Akzeptanzkriterien:
• Private/loopback ranges werden blockiert.
• Optionales Host-Allowlist-Feature vorhanden.
• Tests fuer geblockte und erlaubte Ziele vorhanden.

7) Prevent mail header injection

• Aufwand: S
• Labels: security, mail
• Akzeptanzkriterien:
• Empfaenger/Betreff/From werden validiert.
• CRLF-Injection wird abgefangen.
• Fehlerfall ist dokumentiert.

8) Centralize HTTP limits (timeout/redirect/size)

• Aufwand: S
• Labels: robustness, network
• Akzeptanzkriterien:
• Eine zentrale Konfiguration fuer HTTP-Limits.
• og.php und link-meta.php nutzen dieselben Limits.
• Default-Werte sind in README dokumentiert.

9) Improve SQL error handling + logging

• Aufwand: M
• Labels: sql, robustness
• Akzeptanzkriterien:
• prepare()/execute()-Fehler werden explizit behandelt.
• Fehler enthalten Query-Kontext ohne Secrets.
• Verhalten entspricht der definierten Error-Strategie.

10) Replace fragile HTML allowlist sanitizer

• Aufwand: M
• Labels: security, string
• Akzeptanzkriterien:
• onlySimpleHTML() wird durch robusteren Ansatz ersetzt.
• Erlaubte Tags sind konfigurierbar dokumentiert.
• Regression-Tests fuer typische Eingaben vorhanden.

3) Code-Qualitaet

• Sammel-Issue: Naming-Konvention, SQL-Binding-Refactor, Legacy-Markierung, Markdown-Konsolidierung, klare Modulgrenzen.
• Aufwand: L
• Empfehlung: in 3-5 Unter-Issues aufteilen.

4) Tests und Tooling

11) Bootstrap test/tooling baseline

• Aufwand: M
• Labels: testing, ci
• Akzeptanzkriterien:
• PHPUnit laeuft lokal mit ersten Smoke-Tests.
• PHPStan/Psalm auf niedriger Stufe integriert.
• CI fuehrt mindestens Lint + Tests bei Push aus.

5) Mittelfristige Architektur

12) Prepare Composer + namespace migration path

• Aufwand: L
• Labels: architecture
• Akzeptanzkriterien:
• Vorschlag fuer Zielstruktur (src/, namespaces, autoload).
• Migrationsplan fuer prozedurale Helfer zu Klassen.
• Konfigurationsobjekt und HTTP-Adapter als Zielbild beschrieben.

Empfohlene Reihenfolge

1. #1 bis #5 (kurzfristig, hoher Hebel)
2. #6 bis #10 (Sicherheit/Robustheit)
3. #11 (Tests + CI als Guardrail)
4. #12 und Sammel-Issue aus Abschnitt 3