MAIL HARDENING

README.md

@@ -24,7 +24,7 @@ Danach je nach Bedarf einzelne Dateien einbinden oder zentral ueber `_func.php`
 
 ```php
 <?php
-include_once __DIR__ . '/lib/_func.php';
+include_once __DIR__ . '/_func.php';
 
 echo shortener("Ein sehr langer Text", 10); // "Ein sehr..."
 echo decade(12345);                         // "12.345 K" (je nach PHP-Konvertierung)
@@ -44,25 +44,144 @@ echo decade(12345);                         // "12.345 K" (je nach PHP-Konvertie
 
 ## Konfiguration
 
-Einige Module erwarten ein lokales `secret.php` (siehe `secret.php.example`), z. B. fuer:
+Einige Module erwarten ein lokales `secret.php` (siehe `secret.php.example`).
+Folgende Felder werden verwendet:
 
-- SQL-Zugangsdaten in `sql.php`
-- optionale Absenderadresse in `mail.php`
-- Gitea-Parameter in `troy-api.php`
+- `$_m['host']`, `$_m['user']`, `$_m['pass']`, `$_m['data']`, `$_m['pre']`, `$_m['salt']` fuer `sql.php`
+- `$_sendermail`, optional `$_smtp['srv']`, `$_smtp['user']`, `$_smtp['pw']` fuer `mail.php`
+- `$giteaUrl`, `$giteaOwner`, `$giteaRepo`, `$giteaToken` fuer `troy-api.php`
 
-## Beispiel: Seitenmetadaten lesen
+Beispiel:
 
 ```php
 <?php
-include_once __DIR__ . '/lib/link-meta.php';
+// secret.php im selben Verzeichnis wie die Bibliothek ablegen
+if (!defined('SQL_LOG')) define('SQL_LOG', 0);
+$giteaUrl = 'https://git.example.org';
+$giteaOwner = 'org';
+$giteaRepo = 'repo';
+$giteaToken = 'token';
+```
+
+## Runnable Examples
+
+### `string.php`
+
+```php
+<?php
+include_once __DIR__ . '/string.php';
+
+echo shortener('Ein sehr langer Text', 12) . PHP_EOL;
+echo onlyAlpha('Hi! #42?') . PHP_EOL;
+echo linkify('Mehr Infos: https://example.org') . PHP_EOL;
+```
+
+### `numbers.php`
+
+```php
+<?php
+include_once __DIR__ . '/numbers.php';
+
+echo decade(15320) . PHP_EOL;
+echo onlyNumeric('EUR -12.50') . PHP_EOL;
+```
+
+### `sql.php`
+
+```php
+<?php
+if (!defined('SQL_LOG')) define('SQL_LOG', 0);
+include_once __DIR__ . '/sql.php';
+
+$sql = new SQL();
+$row = $sql->single('SELECT 1 AS ok');
+var_export($row);
+```
+
+### `mail.php`
+
+```php
+<?php
+include_once __DIR__ . '/mail.php';
+
+send_mail('user@example.org', 'Test', 'Hallo Welt', 'ok', 'error');
+```
+
+### `link-meta.php`
+
+```php
+<?php
+include_once __DIR__ . '/string.php';
+include_once __DIR__ . '/link-meta.php';
 
 $info = getPageInfo('https://example.org');
 if ($info['ok']) {
-    echo $info['title'];
+    echo $info['title'] . PHP_EOL;
+    echo $info['description'] . PHP_EOL;
 }
 ```
 
+### `og.php`
+
+```php
+<?php
+include_once __DIR__ . '/og.php';
+
+$og = scanOG('https://example.org');
+print_r($og);
+```
+
+### `troy-api.php`
+
+```php
+<?php
+include_once __DIR__ . '/troy-api.php';
+
+$res = sendToTroy(['msg' => 'hello']);
+var_dump($res);
+```
+
+```php
+<?php
+include_once __DIR__ . '/troy-api.php';
+
+try {
+    $issue = sendToGitea('Test issue', 'Automatisch erstellt.');
+    print_r($issue);
+} catch (Exception $e) {
+    echo $e->getMessage();
+}
+```
+
+### `debug.php`
+
+```php
+<?php
+include_once __DIR__ . '/debug.php';
+
+debugCookie(true);
+debug(['foo' => 'bar']);
+```
+
+### `markdown.php`
+
+```php
+<?php
+include_once __DIR__ . '/string.php';
+include_once __DIR__ . '/markdown.php';
+
+echo md("! Titel\n\n* Punkt A\n* Punkt B");
+```
+
+## Known Limitations
+
+- Kein Composer/Autoload; Includes muessen manuell gesetzt werden.
+- `sql.php` erwartet `secret.php` im Bibliotheksverzeichnis und nutzt `mysqli`.
+- Netzwerkfunktionen (`link-meta.php`, `og.php`, `troy-api.php`) nutzen `file_get_contents` und haben keine SSRF-Allowlist.
+- Mehrere Funktionen sind historisch gewachsen und nutzen teils inkonsistentes Error-Handling (`false`, `null`, Exceptions).
+- `markdown.php` und `onlySimpleHTML()` sind einfache Parser/Sanitizer, nicht vollstaendige Markdown- oder HTML-Sicherheitsloesungen.
+
 ## Hinweise
 
 - Die Bibliothek ist bewusst leichtgewichtig und ohne Composer-Setup gehalten.
-- Einzelne Funktionen sind historisch gewachsen; fuer geplante Verbesserungen siehe `next_steps.md`.
+- Fuer geplante Verbesserungen siehe `NEXT_STEPS.md`.