php-func-lib/README.md

# 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
```

Danach je nach Bedarf einzelne Dateien einbinden oder zentral ueber `_func.php` laden.

## Schnellstart

```php
<?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)
```

## 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`)
- `http-limits.php`: Zentrale HTTP-Limits (`httpLimits`)
- `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`).
Folgende Felder werden verwendet:

- `$_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:

```php
<?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';
```

HTTP-Defaults fuer Netzwerkmodule (`link-meta.php`, `og.php`):

- `LIB_HTTP_TIMEOUT = 8` (Sekunden)
- `LIB_HTTP_MAX_REDIRECTS = 4`
- `LIB_HTTP_MAX_BYTES = 5242880` (5 MiB)

Optional vor dem Include ueberschreiben:

```php
<?php
define('LIB_HTTP_TIMEOUT', 10);
define('LIB_HTTP_MAX_REDIRECTS', 5);
define('LIB_HTTP_MAX_BYTES', 8 * 1024 * 1024);
```

## 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'] . 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.
- Fuer geplante Verbesserungen siehe `NEXT_STEPS.md`.