README

Framework-agnostic PHP error-tracking and log aggregation SDK for AppLogger — the EU-hosted, privacy-first application monitoring platform. This package is the core that framework adapters (e.g. dennisvanbeersel/symfony-logger-client) build on. It speaks PSR-3 (log interface), PSR-18 (HTTP client), and PSR-17 (HTTP factories), and is designed to never throw into the host application under any circumstances.

Features

• Exception and message capture with automatic fingerprinting and deduplication (captureException, captureMessage, captureEvent).
• Structured log aggregation via a PSR-3 LoggerInterface returned by logger() — ships log records to AppLogger's ClickHouse-backed log pipeline independently of the error pipeline.
• Automatic global error and fatal/OOM handler — opt-in via default_integrations (default: enabled). Registers a shutdown handler and uses MemoryReservation to capture out-of-memory fatals.
• Worker / FastCGI-aware delivery — DeliveryMode auto-detects FrankenPHP, Swoole, RoadRunner, FastCGI and standard CLI; chooses the correct post-response or shutdown flush strategy.
• Breadcrumbs and scope — attach tags, user context, and extra data via configureScope/withScope; add breadcrumbs with addBreadcrumb.
• GDPR-compliant data scrubbing (DataScrubber) — key-name-based field redaction, known-prefix token redaction (Bearer, sk_log_, pk_, AKIA*, ghp_, PEM private keys), URL/query-string scrubbing, embedded-credential stripping, and IPv4/IPv6 anonymization.
• Proxy-aware context collection — request context collected from PHP globals with sensitivity scrubbing applied before capture.
• Circuit breaker + rate limiter + bounded buffering — filesystem-backed state; SDK backs off automatically when the ingest endpoint is unreachable; events beyond max_buffered_events are discarded without blocking.
• before_send hook — inspect and mutate or discard any Event before it is sent.
• diagnose() self-check — programmatic diagnostics returning a DiagnosticReport; also exposed as the vendor/bin/applogger CLI.
• Resilient by design — every public method is total: it never propagates exceptions into the host. Rule #1 is inviolable.

Requirements

• PHP ^8.3
• A discoverable PSR-18 HTTP client (e.g. symfony/http-client, guzzlehttp/guzzle with php-http/guzzle7-adapter).
  • nyholm/psr7 (PSR-17 request/response factories) ships as a direct dependency and is always available.
  • If no PSR-18 client is discoverable at runtime, the SDK silently degrades to a NullTransport — telemetry is disabled but the host application continues unaffected. Install a PSR-18 client to actually send events.
• ext-json, ext-mbstring

Installation

composer require applogger/sdk-core

Stability note: until a stable tagged release is published this package tracks dev-master. Consumers that have "minimum-stability": "stable" (the Composer default) must add:

"minimum-stability": "dev",
"prefer-stable": true

Framework adapters that already require the bundle (e.g. dennisvanbeersel/symfony-logger-client) typically pin a compatible stability themselves.

Quick Start

Global function API

The global functions in src/functions.php are auto-loaded by Composer and provide the fastest integration path for plain PHP applications.

use function ApplicationLogger\Sdk\{init, captureException, captureMessage, addBreadcrumb, configureScope, withScope, flush, logger};
use ApplicationLogger\Sdk\{Breadcrumb, Severity};

// 1. Initialise once (typically in your bootstrap / front-controller).
init([
    'dsn'         => 'https://your-ingest-host.example.com/your-project-id',
    'api_key'     => 'your-api-key',
    'environment' => 'production',
    'release'     => '1.4.2',
]);

// 2. Capture exceptions.
try {
    riskyOperation();
} catch (\Throwable $e) {
    captureException($e);
}

// 3. Capture a plain message.
captureMessage('Checkout completed', Severity::Info);

// 4. Add a breadcrumb.
addBreadcrumb(new Breadcrumb(
    category: 'db',
    message:  'User record loaded',
    level:    Severity::Debug,
    data:     ['user_id' => 42],
    timestamp: new \DateTimeImmutable(),
));

// 5. Enrich the current scope (tags, user, extra).
configureScope(function (\ApplicationLogger\Sdk\Scope $scope): void {
    $scope->setTag('plan', 'premium');
    $scope->setUser(['id' => 42, 'email' => 'alice@example.com']);
    $scope->setExtra('memory_mb', memory_get_usage(true) / 1048576);
});

// 6. Use an isolated scope for one block (does not affect the global scope).
withScope(function (\ApplicationLogger\Sdk\Scope $scope): void {
    $scope->setTag('component', 'payment');
    captureMessage('Payment gateway timeout', Severity::Warning);
});

// 7. PSR-3 logger for structured log aggregation (requires log_endpoint + log_token).
$log = logger();
$log->info('Order {id} placed', ['id' => 99]);
$log->error('Unexpected response', ['status' => 503]);

// 8. Flush pending events (useful in CLI scripts or before process termination).
flush(budget: 2.0); // optional wall-clock budget in seconds

Hub — DI / framework-adapter entry point

Framework adapters use Hub directly instead of the global functions, so they can wire the hub into the DI container.

use ApplicationLogger\Sdk\Hub;

// After init() (or after a framework adapter has constructed its own Hub):
$hub = Hub::getCurrent();

$hub->captureException($throwable);
$hub->captureMessage('Something happened', \ApplicationLogger\Sdk\Severity::Warning);
$hub->configureScope(function (\ApplicationLogger\Sdk\Scope $scope): void {
    $scope->setTag('tenant', 'acme');
});
$hub->withScope(function (\ApplicationLogger\Sdk\Scope $scope): void {
    // isolated scope
});

The Symfony bundle (dennisvanbeersel/symfony-logger-client) constructs a Hub via its DI container and never calls the global init(); it uses Hub::setCurrent() so the global functions still delegate to the same instance.

DSN Format

scheme://host[:port]/projectId

Examples:

https://ingest.applogger.eu/01J9X3K5QV8N2P7G4HZYWEM6BF
https://localhost:8080/my-project

Important: the DSN must NOT contain userinfo (user@ or user:pass@). A DSN with a @ in the authority is explicitly rejected by Dsn::tryParse() and resolves to null, which causes the SDK to use a NullTransport (no events sent, no error thrown).

Authentication is passed via the api_key option, which the SDK sends as the X-Application-Logger-Api-Key request header. The dsn option carries only the routing information (host + project ID).

Configuration Reference

All options are passed as a flat array to init() (or Options::fromArray()). Unknown keys are warned via the configured logger and silently ignored.

Log Aggregation

The SDK ships two independent pipelines through a single init() call:

1. Error tracking — captureException / captureMessage → POST {dsn-host}/api/v1/errors (PostgreSQL, fingerprinted + grouped). Auth: X-Application-Logger-Api-Key.
2. Log aggregation — logger() PSR-3 bridge → buffered → POST {log_endpoint}/v1/logs/batch (ClickHouse). Auth: X-Api-Key header with log_token.

Logging is disabled when either log_endpoint or log_token is absent — logger() returns a NullLogger and no network calls are made.

init([
    'dsn'          => 'https://ingest.applogger.eu/my-project',
    'api_key'      => 'my-api-key',
    'log_endpoint' => 'https://logs.applogger.eu',
    'log_token'    => 'sk_log_xxxxx',
    'app_name'     => 'my-app',
    'environment'  => 'production',
]);

$log = logger(); // PSR-3 LoggerInterface
$log->info('User signed in', ['user_id' => 123]);
$log->critical('Payment processor unreachable');

Log records are flushed automatically on shutdown when default_integrations is enabled.

Resilience and Design Guarantees

• Rule #1 — never throws into the host. Every public surface is wrapped in try/catch (\Throwable). On any internal failure the SDK logs to its internal logger (if configured) and returns a safe default.
• Circuit breaker — after failure_threshold consecutive transport failures the circuit opens for timeout seconds, skipping all outbound calls. It self-resets via the half-open probe.
• Rate limiter + dedup — bounded event volume; repeated identical events within a window are counted but not re-sent.
• Bounded buffers — max_buffered_events caps in-memory storage; oldest events are dropped when the buffer is full.
• before_send hook — return null from the closure to drop an event entirely. This is the extension point for server-side filtering (e.g. ignore 404s, drop health-check noise).
• Data scrubbing defaults — sensitive field names (password, passwd, secret, token, api_key, auth, credential) are redacted recursively in all captured context. URL userinfo and known token prefixes are scrubbed from text values. IP addresses are anonymized (IPv4: last octet zeroed; IPv6: last 80 bits zeroed).
• Delivery mode awareness — DeliveryMode::AUTO detects FrankenPHP (frankenphp_handle_request), Swoole (\Swoole\Coroutine), RoadRunner (RR_MODE env), and FastCGI (fastcgi_finish_request). Worker mode registers a shutdown flush; web mode relies on the framework's terminate event (e.g. kernel.terminate in Symfony) to drain after the response is sent.

CLI / Diagnostics

vendor/bin/applogger is a zero-dependency CLI that runs a self-check against an SDK configuration.

# Human-readable output
vendor/bin/applogger diagnose \
  --dsn=https://ingest.applogger.eu/my-project \
  --log-endpoint=https://logs.applogger.eu \
  --log-token=sk_log_xxxxx

# Machine-readable JSON (exit 0 = healthy, 1 = a check failed)
vendor/bin/applogger diagnose --dsn=https://… --json

# Skip sending a real test event
vendor/bin/applogger diagnose --dsn=https://… --no-send

# Options can also be supplied via environment variables:
# APPLOGGER_DSN, APPLOGGER_LOG_ENDPOINT, APPLOGGER_LOG_TOKEN,
# APPLOGGER_APP_NAME, APPLOGGER_CACHE_DIR

The CLI runs five checks and prints a [OK] / [WARN] / [FAIL] / [INFO] line for each:

The same checks are available programmatically:

use function ApplicationLogger\Sdk\diagnose;

$report = diagnose([
    'dsn'     => 'https://ingest.applogger.eu/my-project',
    'api_key' => 'my-api-key',
], sendTestEvent: true);

if (!$report->isHealthy()) {
    foreach ($report->checks as $check) {
        if ($check->status === 'fail') {
            echo $check->name.': '.$check->detail.PHP_EOL;
        }
    }
}

Versioning

This package follows Semantic Versioning once a stable tag is published. It is currently pre-release (dev-master / 1.0-dev). Breaking changes within the 1.x series will not be made without a major-version bump.

License

MIT — see LICENSE.

Links

• Homepage: https://applogger.eu
• Source / issues: https://github.com/dennisvanbeersel/applogger-php-core
• Symfony bundle: https://github.com/dennisvanbeersel/symfony-logger-client