php/README.md

# hightrusted CAPTURE — PHP SDK

> **Status:** v0.1 Preview — API stabil, SDK in aktiver Entwicklung

Offizielles PHP-SDK für die [hightrusted CAPTURE API](https://capture.hightrusted.net) —
forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

**Made in Germany.** Server in Deutschland. DSGVO-nativ. Quelloffen unter MIT.

## Installation

```bash
composer require hightrusted/capture
```

## Quickstart

```php
<?php
use Hightrusted\Capture\Client;

$client = new Client(['api_key' => 'ht_live_...']);

// Synchron — wartet bis zu 30 s auf das fertige PDF
$capture = $client->capture(['url' => 'https://example.com']);

echo $capture['id'];
echo $capture['verify_url'];
echo $capture['timestamp']['issued_at'];

// PDF herunterladen
$client->downloadPdf($capture['id'], './beweis.pdf');
```

## Drei Aufruf-Modi

### Synchron (Default)
```php
$capture = $client->capture(['url' => 'https://example.com']);
```

### Asynchron mit Polling
```php
$capture = $client->captureAsync(
    ['url' => 'https://example.com', 'reference' => 'case-001'],
    waitForReady: true,
    maxWaitSec: 60.0,
);
```

### Webhook
```php
$job = $client->captureWebhook([
    'url' => 'https://example.com',
    'webhook_url' => 'https://your-app.tld/webhooks/capture',
    'reference' => 'case-001',
]);
```

## Verifikation (kostenlos, ohne Quota)

```php
// Per Capture-ID
$result = $client->verify(source: 'cap_...');

// Per Verify-URL
$result = $client->verify(source: 'https://verify.hightrusted.net/c/...');

// Per PDF-Upload
$result = $client->verify(pdfPath: './beweis.pdf');

echo $result['valid'] ? 'gültig' : 'ungültig';
```

## Webhook-Signatur prüfen

```php
use Hightrusted\Capture\Webhook;

// In deinem Webhook-Endpoint:
$body = file_get_contents('php://input');  // RAW body!
$sig = $_SERVER['HTTP_X_HIGHTRUSTED_SIGNATURE'] ?? '';

if (!Webhook::verifySignature($body, $sig, 'wh_secret_...')) {
    http_response_code(401);
    exit('invalid_signature');
}

$payload = json_decode($body, true);
// ...
```

## Fehler-Behandlung

```php
use Hightrusted\Capture\{
    Client,
    InvalidApiKeyException,
    QuotaExceededException,
    RateLimitedException,
    UnreachableUrlException,
};

try {
    $capture = $client->capture(['url' => 'https://example.com']);
} catch (InvalidApiKeyException $e) {
    echo "API-Key ungültig\n";
} catch (QuotaExceededException $e) {
    echo "Quota erschöpft\n";
} catch (RateLimitedException $e) {
    echo "Rate-limited, retry in {$e->retryAfterSeconds}s\n";
} catch (UnreachableUrlException $e) {
    echo "Quelle nicht erreichbar\n";
}
```

## API-Key

Bearer-Token, Erzeugung unter
https://capture.hightrusted.net/dashboard/api-keys

```php
$client = new Client(['api_key' => 'ht_live_...']);
// alternativ über Umgebungsvariable HIGHTRUSTED_API_KEY
$client = new Client();
```

## Voraussetzungen

- PHP 8.1 oder höher
- `ext-curl`, `ext-json`, `ext-hash`

## Entwicklung

```bash
git clone ssh://git@git.hightrusted.net:2222/hightrusted-capture/php.git
cd php
composer install
composer test
```

## Roadmap

- [x] v0.1 — Basis-Client, Verify, Download, typisierte Exceptions
- [ ] v0.2 — PSR-18-kompatibel (HTTP-Client austauschbar)
- [ ] v0.3 — Laravel Service-Provider als separates Package
- [ ] v1.0 — Stabile API, semantische Versionierung

## Verwandte Repositorys

**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):

- [`openapi`](https://git.hightrusted.net/hightrusted-capture/openapi) — OpenAPI 3.1 Spec
- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen (inkl. WordPress-Plugin)
- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK
- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK

**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):

- [`platform`](https://git.hightrusted.net/hightrusted/platform)
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal)
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance)

## Support

- **Doku:** https://capture.hightrusted.net/api/docs
- **Status:** https://status.hightrusted.net
- **Developer Support:** developers@hightrusted.net
- **Sicherheit:** siehe [SECURITY.md](./SECURITY.md)

## Lizenz

MIT — siehe [LICENSE](./LICENSE).

---

**hightrusted GmbH** — *The European Trust Infrastructure.*
Made in Germany. DSGVO-nativ. eIDAS-konform.