README

Framework-agnostic PHP SDK for Ranetrace: error tracking, centralized logging, event tracking and frontend JavaScript error capture. It has no framework dependency, buffers everything it captures to a local file spool, and ships the batches to the Ranetrace API from a flush you schedule, so a slow or unreachable API never slows down a request.

Using Laravel? Reach for ranetrace/ranetrace-laravel instead. It wires the same capture into the framework for you, and adds page-visit analytics.

Installation

composer require ranetrace/ranetrace-php

Requires PHP 8.4 or newer, ext-curl, ext-json and Monolog 3.

Quickstart

use Monolog\Logger;
use Ranetrace\Php\Ranetrace;

$ranetrace = Ranetrace::init(['key' => getenv('RANETRACE_KEY') ?: '']);

$ranetrace->registerErrorHandlers();                       // uncaught exceptions and fatal errors

$ranetrace->report($exception);                            // a handled exception
$ranetrace->trackEvent('newsletter_signup', ['source' => 'footer']);
$ranetrace->events()->sale(orderId: 'ORDER-1', totalAmount: 89.97);

$logger = new Logger('app');
$logger->pushHandler($ranetrace->monologHandler());        // application logs

Captured items are buffered locally and drained when the process shuts down. On anything busier than a quiet site, flush from cron as well:

* * * * * /path/to/app/vendor/bin/ranetrace-flush >/dev/null 2>&1

What it captures

Errors: uncaught exceptions, fatal errors and exceptions you report yourself, with a source preview, the stack trace and its structured frames, the chain of previous exceptions, allowlisted request headers, console context and the current user.
Logs: any Monolog record, from notice up by default, with context and extra secret-scrubbed and size-capped.
Events: custom business events, with a validated snake_case name and hashed visitor fingerprints. No raw IP, no cookies.
JavaScript errors: a browser capture script with breadcrumbs, sampling and deduplication, posting to a relay you mount at any URL of your choosing.

Errors send source lines by default: a few lines around each frame in your own code and around each throw site, secret-scrubbed like everything else. Scrubbing catches a secret under a sensitive key, passed to a call whose name says so (setApiKey('...')) or passed to a known credential-taking call such as new PDO($dsn, 'root', 'hunter2'), mysqli_connect(...) or the parent::__construct(...) of a class that extends PDO or mysqli. It does not catch a credential passed by position to any other call, such as your own connect($host, 'root', 'hunter2'). Two kinds of secret are recognised by their value alone, wherever they stand in a source line, a message or any string in log context, event properties, breadcrumbs or an exception's context(): the password in a URL, with the user name and host kept (pgsql://app:secret@db/app arrives as pgsql://app:[REDACTED]@db/app), and a token whose prefix says it is a credential: Stripe sk_live_ and rk_live_ keys, AWS AKIA and ASIA access key ids, GitHub ghp_, gho_ and github_pat_ tokens, Slack xoxa-, xoxb-, xoxp- and xoxr- tokens, GitLab glpat- tokens and JWTs. Any other secret under a name it does not know, such as $pin = '4821', is sent as written. Add such names to scrubbing.extra_keys (RANETRACE_SCRUBBING_EXTRA_KEYS). Stack frames never carry argument values (the text trace is PHP's own getTraceAsString(), which shows shortened ones unless zend.exception_ignore_args is on), and frames in vendor/ carry no source. Set RANETRACE_ERRORS_CAPTURE_SOURCE=false (or 'errors' => ['capture_source' => false]) to send no source line at all.

Every feature has its own switch. Logging and JavaScript errors are off until you turn them on. Secrets are redacted by the name they sit under, and a few by their value, before anything leaves your host (what that misses is listed above), and capture failures are swallowed and written to the SDK's own diagnostics file, never raised into your application.

Documentation

Agents working in an application that uses this package should read AGENTS.md, which is the same surface condensed into a reference: the full config table, the required wiring and the pitfalls.

License

The MIT license. See LICENSE.md.

ranetrace / ranetrace-php

Package info

Security

Statistics