LIVCK Cloud

Laravel-Paket Ab Team-Plan

livck/cloud-laravel bindet das PHP-SDK in Laravel ein. Dazu kommen Konfiguration, eine Facade, Dependency Injection, mehrere Verbindungen, ein Fake für Tests und ein Artisan-Befehl, der die Verbindung prüft. Das Paket läuft ab PHP 8.3 mit Laravel 12 oder 13 und steht unter der MIT-Lizenz.

Installation

composer require livck/cloud-laravel

Laravel findet den Service-Provider und die Facade LivckCloud von selbst. Trag deinen API-Token in die .env ein:

LIVCK_CLOUD_TOKEN=lvk_dein-api-token

Mehr als den Token musst du nicht einstellen. Willst du etwas ändern, veröffentliche die Konfiguration nach config/livck-cloud.php:

php artisan vendor:publish --tag=livck-cloud-config

Jeder Schlüssel der Standardverbindung lässt sich auch in der .env setzen, zum Beispiel LIVCK_CLOUD_LOCALE=de für deutsche Inhalte.

Facade und Dependency Injection

Die Facade spricht für die Standardverbindung:

use LIVCK\Cloud\Builders\ServiceBuilder;
use LIVCK\Cloud\Laravel\Facades\LivckCloud;

$tag = LivckCloud::tags()->ensure('kunde', '4711')->tag;

LivckCloud::services()->create(
    ServiceBuilder::http('Onlineshop', 'https://shop.example.com')->interval(60)->tags($tag),
);

Alternativ lässt du dir CloudClientInterface injizieren, etwa in einen Controller oder in die handle()-Methode eines Jobs:

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use LIVCK\Cloud\CloudClientInterface;

final class ProvisionCustomer implements ShouldQueue
{
    use Queueable;

    public function __construct(public readonly string $customer) {}

    public function handle(CloudClientInterface $cloud): void
    {
        $cloud->tags()->ensure('kunde', $this->customer);
    }
}

In der Queue landen nur die Daten des Jobs. Den Client bekommt der Worker erst, wenn er den Job ausführt.

Mehrere Verbindungen

Ein Token gehört immer zu einer Organisation. Betreust du mehrere Organisationen, bekommt jede eine eigene Verbindung mit ihrem Token:

// config/livck-cloud.php
'connections' => [
    'default' => [
        'token' => env('LIVCK_CLOUD_TOKEN'),
        // …
    ],
    'kunde-b' => [
        'token' => env('LIVCK_CLOUD_TOKEN_KUNDE_B'),
        'locale' => 'de',
    ],
],

LivckCloud::connection('kunde-b')->services()->list();

Lässt eine Verbindung einen Schlüssel weg, gilt der Standardwert des SDK.

Tokens aus deiner Datenbank

Liegen die Tokens deiner Kunden in deiner eigenen Datenbank, baut withToken() einen Client mit den Einstellungen einer Verbindung und dem Token deiner Wahl. Ohne zweites Argument nimmt es die Standardverbindung:

use LIVCK\Cloud\Laravel\Facades\LivckCloud;

LivckCloud::withToken($customer->livck_token)->services()->list();

LivckCloud::withToken($customer->livck_token, 'kunde-b')->services()->list();

build() baut einen Client aus einem Array mit denselben Schlüsseln wie eine Verbindung. Was im Array fehlt, kommt aus der Standardverbindung:

$cloud = LivckCloud::build([
    'token' => $customer->livck_token,
    'locale' => 'de',
]);

Ist der übergebene Token leer, wirft der Aufruf eine MissingTokenException. Er weicht nie auf einen konfigurierten Token aus, so landet die Anfrage eines Kunden ohne Token nicht in deiner eigenen Organisation.

Beide Clients hält das Paket nicht vor, jeder Aufruf baut einen neuen. Hol dir den Client deshalb dort, wo du ihn brauchst, etwa im Job für genau diesen Kunden. LivckCloud::fake() fängt auch diese Clients ab.

Tokens verschlüsselt speichern

Leg die Tokens deiner Kunden nicht im Klartext ab. Mit dem Cast encrypted verschlüsselt Laravel die Spalte mit deinem APP_KEY und entschlüsselt sie beim Lesen:

protected function casts(): array
{
    return [
        'livck_token' => 'encrypted',
    ];
}

Verschlüsselte Werte sind deutlich länger als der Token, die Spalte braucht deshalb den Typ text. Wechselst du den APP_KEY, trag den alten in APP_PREVIOUS_KEYS ein. Sonst lassen sich die gespeicherten Tokens nicht mehr lesen.

Testen

LivckCloud::fake() ersetzt jede Verbindung durch den Fake des SDK. Nichts verlässt den Prozess, Wiederholungen warten nicht, und einen Token braucht der Test nicht:

use LIVCK\Cloud\Laravel\Facades\LivckCloud;
use LIVCK\Cloud\Testing\MockResponse;
use LIVCK\Cloud\Testing\RecordedRequest;

test('ein neuer Kunde bekommt seinen Tag', function () {
    $fake = LivckCloud::fake([
        MockResponse::json(['data' => $tagPayload], 201),
    ]);

    ProvisionCustomer::dispatchSync('4711');

    $fake->assertSent(fn (RecordedRequest $request, string $connection): bool =>
        $connection === 'default' && $request->matches('POST', '/v1/tags/ensure'));
});

$tagPayload steht für einen Tag, wie ihn die API liefert. Der Matcher bekommt die Anfrage und den Namen ihrer Verbindung, bei Clients aus withToken() und build() ist das ondemand. Dazu gibt es assertNotSent(), assertSentCount(), assertNothingSent() und assertNoPendingResponses().

Ruf fake() auf, bevor dein Code einen Client holt. Der Fake gilt dann für die Facade, injizierte Clients, alle Verbindungen und die Clients aus withToken() und build(). Eine Anfrage ohne vorbereitete Antwort wirft eine Exception, ein Test sendet also nie mehr als geplant.

Verbindung prüfen

php artisan livck-cloud:check

Der Befehl zeigt die Organisation, Art und Rechte des Tokens, sein Ablaufdatum und die Ratenbegrenzung. Danach fragt er die Standorte ab und prüft so, ob dein Plan API-Zugang hat. Dafür braucht der Token Services anzeigen. Eine andere Verbindung prüfst du mit php artisan livck-cloud:check kunde-b.

Exit-CodeBedeutung
0Die Verbindung funktioniert
1Die API lehnt den Token ab oder ist nicht erreichbar
2Die Konfiguration ist unvollständig, etwa weil der Token fehlt

Weiterführende Themen