PHP SDK — vorgio/vorgio-php

Ein schlanker, framework-agnostischer Wrapper über die Vorgio-REST-API mit optionaler Laravel-Auto-Discovery. Zielt auf PHP 8.2+ (breiter als Vorgio selbst), damit Plugin-Autoren ihn auf Shared Hosting ausliefern können.

Das SDK leitet JSON weiter, hängt Authentifizierungs- und Idempotency-Header an, dekodiert die Antwort und übersetzt 4xx / 5xx in typisierte Exceptions. Es führt keine Retries, kein Caching und keine lokale Validierung durch — diese Entscheidungen gehören in Ihre Anwendung.

#Installation

 1composer require vorgio/vorgio-php

#Schnellstart

 1use Vorgio\VorgioClient;
 2
 3$vorgio = new VorgioClient(
 4    token: getenv('VORGIO_TOKEN'),                          // act_…
 5    baseUrl: 'https://app.vorgio.example',                  // weglassen für den öffentlichen Standard-Host
 6);
 7
 8$result = $vorgio->checkouts()->create([
 9    'client'   => [/* … */],
10    'invoice'  => [/* … */],
11    'send'     => ['subject' => 'Ihre Rechnung', 'body' => 'Hallo {client.name}, …'],
12    'metadata' => ['shop_order_id' => '1234'],
13]);
14
15echo $result['data']['invoice']['number'];   // INV-2026-0042
16echo $result['data']['mail_event_id'];        // me_…

Jede Resource-Methode liefert die dekodierte JSON-Antwort als PHP-array zurück. Die vollständige Request- / Response-Form pro Endpoint finden Sie in der Scribe-API-Referenz.

Idempotency-Key wird automatisch als UUIDv7 erzeugt, wenn Sie keinen angeben — das ist die richtige Vorgabe für tatsächlich neue Anfragen. Geben Sie einen expliziten Schlüssel an, wenn Sie sichere Replays wünschen:

 1$vorgio->checkouts()->create([...], idempotencyKey: 'wc-order-1234-checkout');

Schicken Sie denselben Idempotency-Key zweimal innerhalb des serverseitigen Aufbewahrungsfensters, erhalten Sie die ursprüngliche Antwort mit dem Header Idempotency-Replay: true zurück.

#Resource-Methoden

#Webhook-Signaturprüfung

 1use Vorgio\Webhooks;
 2use Vorgio\Exception\VorgioSignatureException;
 3
 4try {
 5    $event = Webhooks::constructEvent(
 6        payload:   file_get_contents('php://input'),
 7        sigHeader: $_SERVER['HTTP_VORGIO_SIGNATURE'] ?? '',
 8        secret:    getenv('VORGIO_WEBHOOK_SECRET'),
 9        tolerance: 300,                                   // Sekunden; Standard 300
10    );
11} catch (VorgioSignatureException $e) {
12    http_response_code(400);
13    exit('Bad signature');
14}
15
16match ($event->type) {
17    'invoice.sent' => $this->onInvoiceSent($event),
18    'invoice.paid' => $this->onInvoicePaid($event),
19    default => null,
20};

$event ist ein Vorgio\WebhookEvent-Wertobjekt mit den public readonly-Eigenschaften id, type, createdAt, data, metadata und rawPayload.

Der Verifier bildet Stripes Webhook::constructEvent-API eins zu eins ab, sodass jeder Entwickler, der zuvor Stripe-Webhooks integriert hat, ihn sofort wiedererkennt. Das Signaturschema entspricht byte-genau dem Server: HMAC-SHA256 über <unix_ts>.<raw_body>, mit einem standardmäßigen 5-Minuten-Replay-Toleranzfenster.

Für Testfixtures stellt das SDK zusätzlich einen einfachen Signer bereit:

 1$header = Webhooks::sign($payload, $secret, $timestamp = null);

#Exceptions

Das SDK führt keine eigenen Retries aus — wählen Sie eine Strategie, die zu Ihrer Laufzeit passt (Queue-Backoff, synchroner Retry mit Jitter, …) und werten Sie $retryAfter für Rate-Limit-Antworten aus.

#Laravel-Integration (optional)

Wird das Paket in einer Laravel-Anwendung installiert, registriert es per Composer-Auto-Discovery automatisch einen Service Provider. Veröffentlichen Sie die Config und setzen Sie die Env-Variablen:

 1php artisan vendor:publish --tag=vorgio-config

 1// config/vorgio.php
 2return [
 3    'token'          => env('VORGIO_TOKEN'),
 4    'base_url'       => env('VORGIO_BASE_URL', 'https://app.vorgio.example'),
 5    'webhook_secret' => env('VORGIO_WEBHOOK_SECRET'),
 6    'timeout'        => (float) env('VORGIO_TIMEOUT', 30),
 7];

Anschließend können Sie den Client überall auflösen — per Dependency Injection, über den Container oder die Facade:

 1use Vorgio\Laravel\Facades\Vorgio;
 2
 3$result = Vorgio::checkouts()->create([...]);

Die Laravel-Schicht wird ausschließlich über Composers extra.laravel-Discovery aktiviert, sodass das Paket in WordPress, Symfony und Standalone-PHP weiterhin ohne Beanstandung nutzbar bleibt.

#CI / unterstützte PHP-Versionen

In CI gegen PHP 8.2 / 8.3 / 8.4 getestet. Keine Framework-Abhängigkeit. Die HTTP-Schicht baut auf guzzlehttp/guzzle ^7.5; für Tests können Sie über das Konstruktor-Argument httpClient: einen eigenen Guzzle-kompatiblen ClientInterface einschleusen und mit einem MockHandler antreiben:

 1use GuzzleHttp\Client;
 2use GuzzleHttp\Handler\MockHandler;
 3use GuzzleHttp\HandlerStack;
 4use GuzzleHttp\Psr7\Response;
 5
 6$mock = new MockHandler([new Response(201, [], '{"data":{}}')]);
 7$http = new Client(['handler' => HandlerStack::create($mock)]);
 8
 9$vorgio = new VorgioClient(token: 'act_test', httpClient: $http);

#Quellcode

Das Paket wird nach der Veröffentlichung unter github.com/vorgio/vorgio-php zu finden sein. Beobachten Sie das Repository, um beim Release benachrichtigt zu werden.