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.