next steps
This commit is contained in:
Troy Grunt
123
NEXT_STEPS.md
Normal file
123
NEXT_STEPS.md
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
# Next Steps
|
||||||
|
|
||||||
|
## Issue Drafts (Ready for Gitea/GitHub)
|
||||||
|
|
||||||
|
### 1) Enable strict types + typed signatures
|
||||||
|
- Aufwand: `M`
|
||||||
|
- Labels: `quality`, `refactor`
|
||||||
|
- Ziel: Konsistente Typen und weniger implizite Typfehler.
|
||||||
|
- Akzeptanzkriterien:
|
||||||
|
- Alle PHP-Dateien starten mit `declare(strict_types=1);` (wo kompatibel).
|
||||||
|
- Oeffentliche Funktionen erhalten Rueckgabe-/Parameter-Typen.
|
||||||
|
- Inkompatible Stellen sind dokumentiert oder angepasst.
|
||||||
|
|
||||||
|
### 2) 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.
|
||||||
|
|
||||||
|
### 3) 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.
|
||||||
|
|
||||||
|
### 4) 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
|
||||||
66
README.md
66
README.md
@@ -1,2 +1,68 @@
|
|||||||
# php-func-lib
|
# php-func-lib
|
||||||
|
|
||||||
|
Kleine PHP-Utility-Bibliothek mit wiederverwendbaren Helfern fuer:
|
||||||
|
|
||||||
|
- Strings und einfache Sanitization
|
||||||
|
- Zahlenformatierung
|
||||||
|
- SQL-Zugriffe (mysqli + prepared statements)
|
||||||
|
- Mailversand
|
||||||
|
- Link/OpenGraph-Metadaten
|
||||||
|
- Debug-Helfer
|
||||||
|
- Troy-/Gitea-API-Aufrufe
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Als Git-Submodule in ein Projekt einbinden:
|
||||||
|
|
||||||
|
```bash
|
||||||
git submodule add https://git.seemsleg.it/pub/php-func-lib lib
|
git submodule add https://git.seemsleg.it/pub/php-func-lib lib
|
||||||
|
```
|
||||||
|
|
||||||
|
Danach je nach Bedarf einzelne Dateien einbinden oder zentral ueber `_func.php` laden.
|
||||||
|
|
||||||
|
## Schnellstart
|
||||||
|
|
||||||
|
```php
|
||||||
|
<?php
|
||||||
|
include_once __DIR__ . '/lib/_func.php';
|
||||||
|
|
||||||
|
echo shortener("Ein sehr langer Text", 10); // "Ein sehr..."
|
||||||
|
echo decade(12345); // "12.345 K" (je nach PHP-Konvertierung)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Module
|
||||||
|
|
||||||
|
- `string.php`: String-Helfer (`shortener`, `onlyAlpha`, `startsWith`, `endsWith`, `linkify`, ...)
|
||||||
|
- `numbers.php`: Zahlen-Helfer (`decade`, `onlyNumeric`)
|
||||||
|
- `sql.php`: Klasse `SQL` fuer Datenbankzugriffe (`get`, `single`, `list`, `keyval`, `set`)
|
||||||
|
- `mail.php`: Mailfunktionen (`send_mail`, `send_html_mail`, `send_php_mail`)
|
||||||
|
- `link-meta.php`: URL-Validierung, Fetching, Meta-Parsing, Bilddownload, Tag-Sanitization
|
||||||
|
- `og.php`: Einfacher OG-Scan (`scanOG`)
|
||||||
|
- `troy-api.php`: API-Helfer fuer Troy/Gitea (`sendToTroy`, `sendToGitea`)
|
||||||
|
- `debug.php`: Cookie-basierte Debug-Ausgabe
|
||||||
|
- `markdown.php`: einfache Markdown-nahe Formatierung (`md`)
|
||||||
|
|
||||||
|
## Konfiguration
|
||||||
|
|
||||||
|
Einige Module erwarten ein lokales `secret.php` (siehe `secret.php.example`), z. B. fuer:
|
||||||
|
|
||||||
|
- SQL-Zugangsdaten in `sql.php`
|
||||||
|
- optionale Absenderadresse in `mail.php`
|
||||||
|
- Gitea-Parameter in `troy-api.php`
|
||||||
|
|
||||||
|
## Beispiel: Seitenmetadaten lesen
|
||||||
|
|
||||||
|
```php
|
||||||
|
<?php
|
||||||
|
include_once __DIR__ . '/lib/link-meta.php';
|
||||||
|
|
||||||
|
$info = getPageInfo('https://example.org');
|
||||||
|
if ($info['ok']) {
|
||||||
|
echo $info['title'];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Hinweise
|
||||||
|
|
||||||
|
- Die Bibliothek ist bewusst leichtgewichtig und ohne Composer-Setup gehalten.
|
||||||
|
- Einzelne Funktionen sind historisch gewachsen; fuer geplante Verbesserungen siehe `next_steps.md`.
|
||||||
|
|||||||
Reference in New Issue
Block a user