Download the PHP package livck/cloud-php without Composer

LIVCK Cloud PHP SDK

The PHP client for the LIVCK Cloud API: uptime monitoring, status pages on statuspage.de or your own domain, and the incident and maintenance history behind them. It talks to LIVCK Cloud (api.livck.cloud) only; LIVCK Self-Hosted is a separate product with its own API.

Requirements

• PHP 8.3 or later
• A PSR-18 HTTP client with PSR-17 factories. Guzzle 7 is used automatically when it is installed; any other client is found through php-http/discovery or passed in.
• An API token of your organization (lvk_…, under Settings → Organization → API tokens). API access starts with the Team plan.

Installation

No HTTP client in the project yet: composer require livck/cloud-php guzzlehttp/guzzle.

Quick start

The client keeps no global state and never changes after construction, so one instance can serve a long-running worker (Octane, RoadRunner, queues). Type against CloudClientInterface.

Built for resellers

The API works on your whole organization; what separates one end customer from the next is a tag. Give every customer exactly one, customer:<number>, and the rest follows from it: tags()->ensure() finds or creates it on every provisioning run, services carry it, ServiceQuery::make()->withTag('customer:4711') lists exactly that customer's services, a synced group fills the customer's status page from it, and incidents and maintenance are filtered through the customer's service ids. The plan caps the number of tags; reaching the cap is a ValidationException on tags, or on the entry (tags.2) of a service's tag list that would create one more.

The examples put this together. They read LIVCK_CLOUD_TOKEN (and LIVCK_CLOUD_BASE_URI if set), and the ones that write can safely run again:

Services and the ServiceBuilder

There is one factory per check type (http(), tcp(), dns(), icmp(), ssl(), manual()). Each builder offers only the options of its type, conditions are typed per type, and every setter returns a new builder.

tags() takes Tag objects, tag ids and tag names (critical, customer:4711, env=prod) in any mix, and a name that does not exist yet is created with the service. The one exception is an entry that looks like a tag id (21 letters, digits, _ or -, with at least one uppercase letter): it must be an existing tag's id or name, otherwise the server answers with a ValidationException on that entry (tags.2). Tag keys are always lowercase, so names are never affected.

With a catalog, config keys, options, condition fields, operators and the type's interval range are checked before sending, and every problem is listed in one CatalogValidationException. The plan's limits (minimum interval, locations, conditions) stay the server's and come back as a ValidationException on the field. For options newer than this SDK, config(), setting(), attribute() and Condition::custom() send any key.

Updating a service

UpdateService sends only what you set. settings.config is merged per key, and a key you send replaces that whole block (headers, auth, conditions). Secrets are never read back; a service shows __LIVCK_KEEP_UNCHANGED__ (KeepSecret::keep()) in their place, and sending that back keeps them. basedOn() starts from the stored settings, secrets kept:

Status pages

A new page goes online at once when the plan has a free published slot, otherwise it is created unpublished. The caps on pages and published pages are reported as a ValidationException (on name and is_published). findBySlug() returns the page with exactly that slug or null (StatuspageQuery::withSlug() on the list). A domain activates itself once LIVCK sees the records (verify() asks right away), and $page->url then switches to it.

History: checks, incidents, maintenance

An empty withServiceIds([]) is sent and matches nothing, while null lifts the filter, so a customer without services never sees everybody's incidents. maintenances() takes the same filter; uptime(), metrics() and responseTimes() hold a service's figures.

Pagination

list() is one request and returns a Page: its items plus total, lastPage and nextPage(). each() walks every page, fetching the next one when the loop gets there:

Collect into an array before deleting what you iterate, or the pages shift under the loop. The check history is keyset-paginated: a CursorPage with nextCursor and next().

Errors

Every exception implements LIVCK\Cloud\Exceptions\LivckCloudException. getMessage() combines the server's message with status, method and URI; the token never appears in messages, dumps or log lines.

A limit is not a permission problem: PlanLimitException and FeatureNotAvailableException go away with a larger plan or by freeing room, PermissionDeniedException with a token that has the right abilities.

Retries and idempotency

Every POST carries an Idempotency-Key, a UUID reused for each retry of that call; the API keeps the first answer for 24 hours per token and replays it, so a retried create never creates twice. Retried are connection errors (a POST only with a key), 429 (waiting Retry-After up to maxRetryAfter), a 409 while the same key is still being processed, and 502/503/504 for reads, PUT and DELETE. A 5xx after a POST or PATCH is not: check the state before sending such a write again.

Every creating method takes your own key as its last parameter. A stable key, such as an order number, makes the create safe to repeat after a crash, for 24 hours, per token; the same key with a different payload is a ValidationException:

idempotency: false in the options sends no key at all; withoutIdempotencyKey() on a Request does the same for one request sent through send().

Forward compatibility

The API grows between SDK releases, and nothing new breaks your code. Every DTO keeps the payload as received in $raw. An enum value this version does not know becomes the Unrecognized case, with the original string in $raw (sending Unrecognized is refused). Builders take raw keys, and so does UpdateService (withConfig(), withSetting(), withAttribute()). request() reaches any endpoint through the same transport and returns the raw Response:

Configuration

Everything but the token lives in the immutable ClientOptions, e.g. new CloudClient($token, new ClientOptions(locale: 'de', logger: $logger)); $client->withOptions(), withLocale() and withHttpClient() return a new client.

Testing your integration

CloudClient::fake() wires a client to an in-memory HTTP client: nothing leaves the process, retries do not sleep, and every request is recorded.

MockResponse also builds list pages, network errors and replays; $http->recorded() and $http->delays() show what was sent and how long retries would have waited.

Links

• Documentation: docs.livck.cloud
• API reference: api.livck.cloud
• Status pages: statuspage.de

License

MIT. See LICENSE.