LIVCK Cloud

PHP-SDK Ab Team-Plan

livck/cloud-php ist der offizielle PHP-Client für die LIVCK Cloud API. Er läuft ab PHP 8.3 und steht unter der MIT-Lizenz. Statt JSON zu bauen, arbeitest du mit typisierten Objekten. Um Wiederholungen, Fehler und Paginierung kümmert sich der Client.

Installation

composer require livck/cloud-php

Das SDK sendet über einen PSR-18-Client und nutzt Guzzle, wenn es installiert ist. Hat dein Projekt noch keinen HTTP-Client, installiere Guzzle gleich mit:

composer require livck/cloud-php guzzlehttp/guzzle

Client einrichten

Du brauchst einen API-Token deiner Organisation. Hinterlege ihn als Umgebungsvariable oder in einem Secret-Store, nie im Code:

use LIVCK\Cloud\CloudClient;

$client = new CloudClient($token); // lvk_…

Übersetzbare Inhalte wie die Titel von Vorfällen fragst du mit new CloudClient($token, new ClientOptions(locale: 'de')) auf Deutsch an. Der Client ändert sich nach dem Erstellen nicht mehr. Eine Instanz kann deshalb in einem Octane- oder Queue-Worker alle Anfragen bedienen.

Schnellstart

Das Beispiel sorgt für den Tag eines Kunden, legt einen HTTP-Service an und listet danach alle Services dieses Kunden:

use LIVCK\Cloud\Builders\ServiceBuilder;
use LIVCK\Cloud\CloudClient;
use LIVCK\Cloud\Query\ServiceQuery;

$client = new CloudClient($token);

// Findet den Tag kunde:4711 oder legt ihn an
$tag = $client->tags()->ensure('kunde', '4711')->tag;

$client->services()->create(
    ServiceBuilder::http('Onlineshop', 'https://shop.example.com')
        ->interval(60)
        ->tags('kunde:4711', 'env=prod'),
);

foreach ($client->services()->each(ServiceQuery::make()->withTag($tag)) as $service) {
    echo $service->name, ': ', $service->effectiveStatus->value, PHP_EOL;
}

tags() nimmt Tag-Objekte, Tag-IDs und Tag-Namen, auch gemischt. Einen Namen, den es noch nicht gibt, legt die API mit dem Service an. Tag-Namen versteht das SDK ab Version 1.1. Den Tag selbst holst du mit ensure(), etwa weil eine Statuspage-Gruppe, die sich selbst füllt, seine ID braucht.

Für jeden Check-Typ gibt es einen eigenen Builder mit genau dessen Optionen: http(), tcp(), dns(), icmp(), ssl() und manual().

Für Reseller

Die API arbeitet immer auf deiner ganzen Organisation, deine Endkunden trennst du über Tags. Gib jedem Kunden genau einen, etwa kunde:4711: withTag('kunde:4711') listet dann genau seine Services, und eine Statuspage-Gruppe mit diesem Tag füllt sich von selbst.

Was der Client für dich erledigt

ThemaWas passiert
WiederholungenNach einem Verbindungsfehler, bei 429 und bei 502, 503 oder 504 auf GET, PUT und DELETE versucht es der Client bis zu zweimal erneut. Die Pausen werden länger, ein Retry-After der API hat Vorrang.
Idempotency-KeyJedes POST trägt einen Key, jede Wiederholung denselben. Ein wiederholtes Anlegen legt nichts doppelt an.
FehlerJeder Fehler kommt als eigene Exception, zum Beispiel ValidationException bei 422 oder PlanLimitException, wenn ein Limit deines Plans erreicht ist.
Paginierunglist() holt eine Seite. each() geht alle Seiten durch und lädt die nächste erst, wenn die Schleife dort ankommt.

Ein 5xx nach einem POST oder PATCH wiederholt der Client nicht. Prüfe dann selbst, ob die Aktion durchgelaufen ist.

Mit einem eigenen Key, etwa deiner Bestellnummer, kannst du ein Anlegen auch nach einem Absturz deines Skripts wiederholen. Die API kennt den Key 24 Stunden lang:

$client->services()->create($builder, idempotencyKey: 'bestellung-4711-shop');

Alle Exceptions implementieren LivckCloudException. Den Token enthält keine Fehlermeldung und keine Log-Zeile:

use LIVCK\Cloud\Exceptions\PlanLimitException;
use LIVCK\Cloud\Exceptions\ValidationException;

try {
    $client->services()->create($builder);
} catch (ValidationException $e) {
    echo $e->firstError('settings.interval_seconds') ?? $e->errorMessage();
} catch (PlanLimitException $e) {
    echo $e->limitKey(), ': ', $e->usage(), ' von ', $e->limit();
}

Testen

CloudClient::fake() liefert einen Client, der aus einer Liste vorbereiteter Antworten antwortet. Nichts verlässt den Prozess, Wiederholungen warten nicht, und jede Anfrage wird aufgezeichnet:

use LIVCK\Cloud\CloudClient;
use LIVCK\Cloud\Testing\MockResponse;
use LIVCK\Cloud\Testing\RecordedRequest;

[$client, $http] = CloudClient::fake([
    MockResponse::json(['data' => $tagPayload], 201),
    MockResponse::error("Your plan's service limit has been reached.", 403, extra: [
        'limit' => 150,
        'usage' => 150,
        'upsell' => ['reason' => 'limit', 'key' => 'services'],
    ]),
]);

// Deinen Code mit $client ausführen, dann:
$http->assertSentCount(2);
$http->assertSent(fn (RecordedRequest $request): bool => $request->matches('POST', '/v1/tags/ensure'));

$tagPayload steht für einen Tag, wie ihn die API liefert. MockResponse baut außerdem Listen-Seiten (page()) und Verbindungsabbrüche (networkError()).

Weiterführende Themen