Vorgio

PHP SDK — vorgio/vorgio-php

A thin, framework-agnostic wrapper over the Vorgio REST API with optional Laravel auto-discovery. Targets PHP 8.2+ (broader than Vorgio itself) so plugin authors can ship it on shared hosting.

The SDK forwards JSON, attaches authentication and idempotency headers, decodes the response, and turns 4xx / 5xx into typed exceptions. It does not retry, cache, or validate inputs locally — those decisions belong to your application.

#Install

 1composer require vorgio/vorgio-php

#Quick start

 1use Vorgio\VorgioClient;
 2
 3$vorgio = new VorgioClient(
 4    token: getenv('VORGIO_TOKEN'),                          // act_…
 5    baseUrl: 'https://app.vorgio.example',                  // omit for the default public host
 6);
 7
 8$result = $vorgio->checkouts()->create([
 9    'client'   => [/* … */],
10    'invoice'  => [/* … */],
11    'send'     => ['subject' => 'Your invoice', 'body' => 'Hello {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_…

Every resource method returns the decoded JSON response as a PHP array. The full request / response shape per endpoint lives in the Scribe API reference.

Idempotency-Key is auto-generated as a UUIDv7 if you don't supply one — the right default for genuinely new requests. Pass an explicit key when you want safe replays:

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

If you ship the same idempotency key twice within the server's retention window, you get back the original response with an Idempotency-Replay: true header.

#Resource methods

Method REST endpoint
$vorgio->checkouts()->create($body, ?$idempotencyKey) POST /v1/checkouts
$vorgio->invoices()->list($query) GET /v1/invoices
$vorgio->invoices()->create($body, ?$idempotencyKey) POST /v1/invoices
$vorgio->invoices()->retrieve($id) GET /v1/invoices/{id}
$vorgio->invoices()->update($id, $body) PATCH /v1/invoices/{id}
$vorgio->invoices()->delete($id) DELETE /v1/invoices/{id}
$vorgio->invoices()->send($id, $body, ?$idempotencyKey) POST /v1/invoices/{id}/send
$vorgio->invoices()->markPaid($id, $body = [], ?$idempotencyKey) POST /v1/invoices/{id}/mark-paid
$vorgio->clients()->list($query) GET /v1/clients
$vorgio->clients()->create($body, ?$idempotencyKey) POST /v1/clients
$vorgio->clients()->retrieve($id) GET /v1/clients/{id}
$vorgio->clients()->update($id, $body) PATCH /v1/clients/{id}
$vorgio->clients()->delete($id) DELETE /v1/clients/{id}

$vorgio->invoices()->update() works on drafts, recurring templates and offers. A finalised invoice cannot be changed, metadata included: the call throws a VorgioValidationException with an empty $errors map and a problemType() URL ending in /invoice-not-editable. Reverse the invoice via POST /v1/invoices/{id}/cancel instead. See the error reference.

#Webhook signature verification

 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,                                   // seconds; default 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 is a Vorgio\WebhookEvent value object with public readonly properties id, type, createdAt, data, metadata, and rawPayload.

The verifier mirrors Stripe's Webhook::constructEvent API one-to-one, so any developer who has integrated Stripe webhooks before will recognise it instantly. The signature scheme matches the server byte-for-byte: HMAC-SHA256 over <unix_ts>.<raw_body>, with a 5-minute default replay tolerance window.

For test fixtures, the SDK also exposes a low-level signer:

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

#Exceptions

Exception When
Vorgio\Exception\VorgioApiException Any non-2xx response — has $statusCode, $problem (parsed RFC 7807 body), $rawBody, $requestId, plus problemType()
Vorgio\Exception\VorgioValidationException extends above 422 — adds typed $errors field-to-messages map
Vorgio\Exception\VorgioRateLimitedException extends above 429 — adds $retryAfter in seconds (defaults to 60 if Retry-After is missing)
Vorgio\Exception\VorgioSignatureException Webhook signature verification failure
Vorgio\Exception\VorgioException Base class for all of the above and for transport-level errors (DNS / connection refused / etc.)

The SDK never retries on its own — pick a strategy that fits your runtime (queue back-off, sync retry with jitter, etc.) and act on $retryAfter for rate-limit responses.

#Laravel integration (optional)

When the package is installed inside a Laravel app it auto-registers a service provider via Composer auto-discovery. Publish the config and set the env vars:

 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];

Then resolve the client wherever you need it — through dependency injection, the container, or the facade:

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

The Laravel layer is gated behind Composer's extra.laravel discovery, so the package stays usable in WordPress, Symfony, and standalone PHP.

#CI / supported PHP versions

Tested against PHP 8.2 / 8.3 / 8.4 in CI. No framework dependency. The HTTP layer is built on guzzlehttp/guzzle ^7.5; for tests, you can inject your own Guzzle-compatible ClientInterface via the httpClient: constructor argument and drive it with a MockHandler:

 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);

#Source

The package will live at github.com/vorgio/vorgio-php once published. Watch the repo to be notified when it ships.