selfwatch PHP SDK

A small, dependency-free PHP client for selfwatch — a self-hosted log/event ingestion platform.

It sends events (messages and exceptions) to selfwatch's store endpoint over HTTP(S) using nothing but curl. The capture methods never throw on transport errors, so adding logging can't crash your app.

• PHP 8.1+
• No third-party runtime dependencies (uses ext-curl, ext-json)
• PSR-4 namespace Selfwatch\Sdk

---

Install

With Composer

composer require selfwatch/sdk

require 'vendor/autoload.php';

Drop-in, no Composer

The SDK is three small files with no external dependencies. Copy src/ into your project and require the classes directly:

require __DIR__ . '/path/to/src/Dsn.php';
require __DIR__ . '/path/to/src/Severity.php';
require __DIR__ . '/path/to/src/Client.php';

---

The DSN

selfwatch identifies your project with a DSN (Data Source Name):

{scheme}://{TOKEN}@{HOST}/{PROJECT_ID}

Example:

http://cd9ef67832d31a28fe50260fc1c85bc1f278e8b3734b05a9@localhost:8003/1

Part	Meaning
scheme	http or https
TOKEN	the project's ingestion key
HOST	host, optionally with a port (e.g. localhost:8003)
PROJECT_ID	the integer project id

The SDK derives the store endpoint from the DSN:

POST {scheme}://{HOST}/api/{PROJECT_ID}/store/

http is only allowed for loopback hosts (127.0.0.1, ::1, localhost). A non-loopback host must use https, otherwise constructing the Dsn throws an InvalidArgumentException. This mirrors the server, which rejects insecure transport for everything except loopback.

---

Quick start

use Selfwatch\Sdk\Client;
use Selfwatch\Sdk\Severity;

$client = new Client(getenv('SELFWATCH_DSN'), [
    'environment' => 'production',
    'release'     => '1.4.2',
    'tags'        => ['service' => 'checkout'],
]);

// Send a message — returns the event id (string) or null on failure.
$id = $client->captureMessage('Cache warmed', Severity::INFO);

// Capture an exception (walks the getPrevious() chain automatically).
try {
    doSomethingRisky();
} catch (\Throwable $e) {
    $eventId = $client->captureException($e, Severity::ERROR, [
        'order_id' => 1234,
    ]);

    if ($eventId === null) {
        // Logging never throws by default; inspect what went wrong:
        error_log('selfwatch send failed: ' . $client->getLastError());
    }
}

---

Public API

Selfwatch\Sdk\Client

new Client(Dsn|string $dsn, array $options = [])

captureMessage(string $message, string $level = 'info', array $extra = []): ?string
captureException(\Throwable $e, string $level = 'error', array $extra = []): ?string
captureEvent(array $event): ?string   // low-level: fills defaults, POSTs, parses
getLastError(): ?string               // reason the last capture failed, or null
getDsn(): Dsn

All capture* methods return the event id on success and null on failure (unless throw_on_error is enabled).

Selfwatch\Sdk\Severity

Level constants: Severity::FATAL, ERROR, WARNING, INFO, DEBUG.

Selfwatch\Sdk\Dsn

new Dsn(string $dsn)            // throws InvalidArgumentException if malformed
Dsn::from(Dsn|string $dsn): Dsn
getScheme(): string
getToken(): string
getHost(): string               // includes port, e.g. "localhost:8003"
getProjectId(): int
getStoreUrl(): string           // {scheme}://{HOST}/api/{PROJECT_ID}/store/

---

Options

Passed as the second argument to new Client($dsn, [...]).

Option	Type	Default	Description
environment	string|null	null	Sets environment on every event (e.g. production).
release	string|null	null	Sets release on every event (e.g. a version or git SHA).
server_name	string|null	gethostname()	Overrides the reported server name.
tags	array<string,string>	[]	Default tags merged into every event (event tags win on conflict).
timeout	int (seconds)	5	Connect + transfer timeout for the HTTP request (minimum 1).
verify_ssl	bool	true	Verify the TLS peer/host. Leave true in production.
throw_on_error	bool	false	If true, capture failures throw RuntimeException instead of null.

---

What the SDK fills in for you

When you call any capture* method, the SDK provides sensible defaults for any field you didn't set:

• event_id — 32 lowercase hex chars (from random_bytes(16))
• timestamp — current time, RFC3339 UTC (gmdate('Y-m-d\TH:i:s\Z'))
• platform — "php"
• level — "info" for messages, "error" for exceptions
• server_name — gethostname() (or the server_name option)
• environment / release — from the matching options
• contexts.runtime — { "name": "php", "version": PHP_VERSION }
• tags — the default tags from options, merged with per-event tags

For exceptions, exception.values is built from the whole getPrevious() chain (innermost cause last, per the wire contract). Each frame carries filename, function, lineno and an in_app flag — in_app is true unless the file lives under a /vendor/ directory.

---

Error handling

By default, transport and server errors are swallowed: the capture method returns null and the reason is available via getLastError(). The server may respond with, among others:

Status	Meaning
401	missing token
403	invalid / mismatched token
400	insecure transport or bad JSON
413	body larger than 2 MiB
429	rate limited (see the Retry-After response header)
500	server error

If you'd rather have failures raise exceptions (handy in tests), construct the client with ['throw_on_error' => true].

---

Running the example

SELFWATCH_DSN="http://<token>@localhost:8003/1" php examples/basic.php

With no SELFWATCH_DSN set it falls back to a local dev DSN.

---

License

MIT — see LICENSE.