PHP SDK

The official PHP SDK wraps the REST API with typed models, automatic retries, a resolve-and-wait helper, a per-code exception hierarchy, and webhook verification.

Packagist

linkskipper/sdk · v0.2.1

GitHub

Source, issues, and changelog.

Install

composer require linkskipper/sdk

Requires PHP 8.1+ (the SDK uses enums and readonly properties). It works with the built-in cURL transport out of the box, or any PSR-18 HTTP client.

Use the SDK from your server, never client-side, so your API key stays secret. See Authentication.

Initialize

<?php

use LinkSkipper\LinkSkipper;

require __DIR__ . "/vendor/autoload.php";

$client = LinkSkipper::create(getenv("LINKSKIPPER_API_KEY"));

LinkSkipper::create(string $apiKey, string $baseUrl = …) is the quick constructor. For full control over timeouts, polling defaults, retry policy, transport, or clock, build a Config and pass it to new LinkSkipper($config):

<?php

use LinkSkipper\Config;
use LinkSkipper\LinkSkipper;

$client = new LinkSkipper(new Config(
    apiKey: getenv("LINKSKIPPER_API_KEY"),
    timeoutMs: 30000,
    pollIntervalMs: 2000,
    maxWaitMs: 120000,
));

Config options

string

required

Your sk_live_… key. Throws ConfigurationException if empty.

string

default:"https://api.linkskipper.app"

Override the API base URL.

int

default:"30000"

Per-request timeout in milliseconds.

int

default:"2000"

Default poll interval for resolveAndWait.

int

default:"120000"

Default overall deadline for resolveAndWait.

RetryPolicy

Retry tuning. Retries 429 and 5xx, honoring Retry-After, with exponential backoff.

Transport

HTTP transport. Defaults to CurlTransport; pass Psr18Transport to use your own client.

Methods

resolve

resolve(string $url, ?string $idempotencyKey = null): ResolveResult Submits a URL to POST /v1/resolve. Returns immediately — a cached link comes back with status === ResolveStatus::Done, a new one queued with a jobId.

<?php

use LinkSkipper\Enum\ResolveStatus;

$result = $client->resolve("https://ouo.io/abc123", "order-42");

if ($result->status === ResolveStatus::Done) {
    echo $result->targetUrl, PHP_EOL;
    echo $result->cached ? "cached" : "fresh", PHP_EOL;
} else {
    echo "queued: ", $result->jobId, PHP_EOL;
}

ResolveResult exposes jobId, status, url, targetUrl, provider, tier, creditsCharged, cached, balance, queuePosition, pollUrl, and an isDone() helper.

resolveAndWait

resolveAndWait(
    string $url,
    ?string $idempotencyKey = null,
    ?int $pollIntervalMs = null,
    ?int $maxWaitMs = null,
): ResolvedLink

The high-level helper: submits the resolve, polls the job until terminal, and returns the resolved link. A cached hit returns without polling.

<?php

use LinkSkipper\Exception\JobFailedException;
use LinkSkipper\Exception\TimeoutException;

try {
    $link = $client->resolveAndWait(
        "https://ouo.io/abc123",
        maxWaitMs: 60000,
        pollIntervalMs: 2000,
    );

    echo $link->targetUrl, PHP_EOL;
    printf(
        "%s (%s) · %d credits · cached=%s\n",
        $link->provider,
        $link->tier->value,
        $link->creditsCharged,
        $link->cached ? "yes" : "no",
    );
} catch (JobFailedException $exception) {
    fwrite(STDERR, "Resolve failed: " . $exception->reason . PHP_EOL);
} catch (TimeoutException $exception) {
    fwrite(STDERR, "Timed out, still pending: " . $exception->jobId . PHP_EOL);
}

ResolvedLink has a guaranteed targetUrl plus jobId, provider, tier, creditsCharged, balance, and cached.

getJob

getJob(string $jobId): Job Reads GET /v1/jobs/{jobId} once. The returned Job has a JobStatus enum status with an isTerminal() helper.

<?php

use LinkSkipper\Enum\JobStatus;

$job = $client->getJob("9b1d7c0e-2f3a-4b5c-8d6e-1a2b3c4d5e6f");
if ($job->status === JobStatus::Done) {
    echo $job->targetUrl, PHP_EOL;
}

account

account(): Account Reads GET /v1/account: telegramId, balance, subscriptionUntil, and providers.

<?php

$account = $client->account();
printf("%d credits left\n", $account->balance);

providers

providers(): array — a list<ProviderEntry> Reads GET /v1/providers. Each ProviderEntry has provider, label, hosts, tier (enum), and latency.

<?php

foreach ($client->providers() as $p) {
    printf("%s: %s\n", $p->label, implode(", ", $p->hosts));
}

Errors

Every failed API call throws an ApiException subclass keyed to the response error code, under the LinkSkipper\Exception namespace. All extend LinkSkipperException.

Exception	Triggered by
`InvalidRequestException`	`invalid_request` (400)
`InvalidKeyException`	`invalid_key` (401)
`OutOfCreditsException`	`out_of_credits` (402) — `balance()`
`ForbiddenScopeException`	`forbidden_scope` (403)
`NotFoundException`	`not_found` (404)
`LinkRemovedException`	`link_removed` (410)
`UnsupportedLinkException`	`unsupported_link` (422)
`RateLimitedException`	`rate_limited` (429) — `retryAfter()`
`QuotaExceededException`	`quota_exceeded` (429) — `retryAfter()`
`ResolveFailedException`	`resolve_failed` (502)
`ProviderDownException`	`provider_down` (503)
`JobFailedException`	A polled job ended `failed`/`invalid` — `$reason`, `$job`
`TimeoutException`	`resolveAndWait` deadline passed — `$jobId`
`NetworkException`	Transport failure after retries
`ConfigurationException`	Bad client configuration (e.g. empty key)
`WebhookVerificationException`	`Webhook::verify` rejected a payload

Every ApiException exposes the parsed problem via methods: status(), errorCode() (an ErrorCode enum), detail(), retryAfter(), balance(), and the raw $exception->problem.

<?php

use LinkSkipper\Exception\ApiException;
use LinkSkipper\Exception\OutOfCreditsException;
use LinkSkipper\Exception\RateLimitedException;

try {
    $client->resolveAndWait("https://ouo.io/abc123");
} catch (OutOfCreditsException $e) {
    fwrite(STDERR, "Top up — balance: " . $e->balance() . PHP_EOL);
} catch (RateLimitedException $e) {
    fwrite(STDERR, "Back off for " . $e->retryAfter() . " seconds" . PHP_EOL);
} catch (ApiException $e) {
    fwrite(STDERR, $e->errorCode()->value . " " . $e->status() . " " . $e->detail() . PHP_EOL);
}

Webhook verification

Webhook::verify(string $payload, string $signatureHeader, string $secret, int $toleranceSeconds = 300): WebhookEvent checks the X-LinkSkipper-Signature header, the timestamp tolerance, and the HMAC, then returns a typed WebhookEvent. It throws WebhookVerificationException on any failure.

<?php

use LinkSkipper\Webhook;
use LinkSkipper\Enum\WebhookEventName;
use LinkSkipper\Exception\WebhookVerificationException;

$payload   = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_LINKSKIPPER_SIGNATURE"] ?? "";

try {
    $event = Webhook::verify($payload, $signature, getenv("LINKSKIPPER_WEBHOOK_SECRET"));
    if ($event->event === WebhookEventName::ResolveDone) {
        save_target($event->jobId, $event->targetUrl);
    }
    http_response_code(204);
} catch (WebhookVerificationException $exception) {
    http_response_code(400);
}

The WebhookEvent exposes event (a WebhookEventName enum), createdAt, jobId, status (a JobStatus enum), targetUrl, provider, tier, error, creditsCharged, and balance.

Read the raw request body with php://input before any JSON parsing, or the signature won’t match. See Webhooks.

Get started

API

Reference

SDKs

Packagist

GitHub

Install

Initialize

Config options

Methods

resolve

resolveAndWait

getJob

account

providers

Errors

Webhook verification

Packagist

GitHub

​Install

​Initialize

​Config options

​Methods

​resolve

​resolveAndWait

​getJob

​account

​providers

​Errors

​Webhook verification

Install

Initialize

Config options

Methods

resolve

resolveAndWait

getJob

account

providers

Errors

Webhook verification