php-func-lib/NEXT_STEPS.md

Next Steps

• #TODO Unified error strategy (Definition)

• 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.

• Festlegung:

• Exceptions fuer interne/unerwartete Fehler (Konfiguration fehlt, DB/HTTP/JSON-Fehler, Parsing-Fehler, invalide Argumente).

• null nur fuer "kein Ergebnis" als erwarteter Zustand (z. B. URL ohne OG-Metadaten).

• false nur fuer boolesche Checks/Operationen mit reinem Erfolg-Flag; keine Detailfehler ueber false.

• Keine Mischung pro Funktion: jede Funktion dokumentiert exakt einen Fehlerkanal in PHPDoc/README.

• Alle gecatchten Exceptions werden mit Kontext weitergeworfen (ohne Secrets), nicht still geschluckt.

• #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.

• #TODO 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.

• #TODO Sicherheit und Robustheit

• #TODO 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.

• #TODO 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.

• Code-Qualitaet (aufgeteilt in Unter-Issues)

• Aufwand: L

• Labels: quality, refactor

• Unter-Issues:

• Define and enforce naming conventions for functions, files and constants.

• Refactor SQL binding helpers to one consistent, typed API surface.

• Mark legacy functions/modules (@deprecated) and document replacement path.

• Consolidate Markdown docs (README + API notes) into one canonical structure.

• Clarify module boundaries and ownership (I/O, SQL, parsing, formatting).

• Akzeptanzkriterien:

• Kurzer Styleguide in README.md vorhanden und auf bestehende Dateien angewendet.

• Keine neuen Legacy-Einstiege ohne Markierung und Migrationshinweis.

• SQL-Helper nutzen einheitliche Signaturen in geaenderten Modulen.

• Modulgrenzen sind in Doku und Dateistruktur konsistent nachvollziehbar.

• #TODO Tests und Tooling

• #TODO 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.

• #TODO 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