Download the PHP package getfaultline/faultline-php without Composer

getfaultline/faultline-php

The PHP SDK for Faultline, a self-hostable error-tracking platform. It captures exceptions, PHP errors and messages, adds context (stack traces with source, breadcrumbs, request data, user, tags), scrubs secrets, and sends batched, gzip-compressed events to the Faultline ingest API.

• No runtime dependencies. Needs only ext-json and ext-curl. ext-zlib (gzip) and ext-apcu (shared rate-limit state) are used when present.
• Never crashes your app. Every public method is exception-safe, and internal errors are logged only when debug: true.
• Never slows your requests. Events are queued in memory and sent in one batch at shutdown, after fastcgi_finish_request() under PHP-FPM, so the user does not wait.
• Laravel integration (auto-discovered) and a PSR-15 middleware for Slim and Mezzio.
• PHP >= 8.1.

Quickstart

That is all a plain PHP app needs: no middleware. init() installs an exception handler, an error handler and a fatal-error shutdown handler, so uncaught exceptions, warnings and fatal errors are reported automatically. Everything is sent at the end of the request.

Every function is also available as a static method: \Faultline\Faultline::init([...]), Faultline::captureException($e), and so on.

A runnable script is in examples/plain.php:

CLI scripts and workers

There is nothing extra to do for a script: the queue is flushed when it exits. Call \Faultline\flush() to send immediately, for example before a long sleep(). In CLI processes the queue is also sent automatically once it holds 20 events, so long-running workers never hold events for long. The Laravel integration flushes between queue jobs.

Laravel

The service provider is auto-discovered. Add your key to .env:

Optionally publish the config file to config/faultline.php:

What you get:

• Exceptions are reported through Laravel's exception handler with a reportable() callback, so dontReport, shouldReport() and report throttling are respected (404s and validation errors are not sent). Laravel keeps logging as usual.
• Request data: method, URL, headers (scrubbed) and query string, plus the route name, URI and action in contexts.route and a route tag.
• User: the authenticated user's id and email (and IP with send_default_pii).
• Breadcrumbs: log messages (log), executed SQL (query, without bindings unless send_default_pii) and the matched route (navigation).
• Delivery after the response was sent (terminating), and between queue jobs. Each job gets its own breadcrumbs and a job context.

Without FAULTLINE_API_KEY the SDK stays disabled, which is handy for local development. Capture manually anywhere with \Faultline\captureException($e). The config keys are snake_case versions of the options below (api_key, sample_rate, ignore_errors, before_send, ...), plus breadcrumbs.logs and breadcrumbs.queries. before_send takes a container-resolved callable: an invokable class name, "Class@method" or [Class::class, 'method'], so php artisan config:cache keeps working.

Slim, Mezzio and other PSR-15 apps

The middleware forks a scope per request, attaches request data and a navigation breadcrumb, captures any Throwable that escapes the inner handler, and re-throws it unchanged. It needs psr/http-server-middleware.

PSR-3: wrap any logger with new Faultline\Integrations\Psr3\BreadcrumbLogger($logger) to turn log calls into log breadcrumbs (needs psr/log 2 or 3).

API

setUser, setTag, setContext, setExtra and addBreadcrumb write to the current scope. Outside withScope (or the PSR-15 middleware) that is the global scope, which in PHP lives for exactly one request.

Options

Invalid options never throw:

• An invalid optional value falls back to its default.
• A missing apiKey or an unusable endpoint disables the SDK.
• Run with debug: true to see why.

PHP handlers

• exceptionHandler: set_exception_handler(). Uncaught exceptions are captured at level fatal. A previously registered handler is chained and keeps the final say; without one, the exception is re-thrown so PHP prints its usual message and exits with 255.

• errorHandler: set_error_handler(). Errors silenced with @ or excluded by error_reporting() are ignored. The previous handler is always called, and PHP's standard handler still runs, so display and logging are unchanged.

  PHP error	Becomes
  E_WARNING, E_USER_WARNING	event (ErrorException), level warning
  E_USER_ERROR, E_RECOVERABLE_ERROR	event (ErrorException), level error
  E_NOTICE, E_USER_NOTICE, E_DEPRECATED, E_USER_DEPRECATED	log breadcrumb

• fatalErrorHandler: register_shutdown_function() + error_get_last() for E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR and friends (type FatalError, level fatal). A small memory reserve is released first, and after "Allowed memory size exhausted" the limit is raised slightly so the event can still be built and sent.

Self-hosting

Set endpoint to your server's base URL. The SDK posts to {endpoint}/api/v1/ingest/events:

In Laravel, set FAULTLINE_ENDPOINT.

What gets sent

Each event follows the shared Faultline event contract: eventId (uuid v4), timestamp, level, platform: "php", exception (type = class name, value, frames ordered oldest → newest, the getPrevious() chain as cause), message, tags, user, request, contexts (runtime, os, plus your own), breadcrumbs, extra, fingerprint, environment, release, serverName, and sdk: { name: "getfaultline/faultline-php", version }.

Frames come from Throwable::getTrace() plus the throw location, with function names like App\Http\Controllers\OrderController->show or App\Support\Str::slug. Frames outside /vendor/ are marked inApp and get ±5 lines of source context.

The SDK enforces the pinned limits before sending:

Scrubbing (client side, same rules as the server and the Node SDK):

• Values under keys matching /(authorization|cookie|set-cookie|password|passwd|secret|token|api[_-]?key|x-faultline-key)/i become "[Filtered]". This applies to request headers and query, extra, contexts, tags and breadcrumb data.
• Credit-card-like strings in request, extra and breadcrumb data are also filtered, as are sensitive URL query parameters.

Delivery:

• capture*() only queues the event (max 100, oldest dropped). Nothing touches the network while your code runs.
• At shutdown the queue is sent in gzip-compressed batches of at most 50 events / 1 MB. Under PHP-FPM (and LiteSpeed) the response is finished first with fastcgi_finish_request().
• Each request times out after 5s (2s to connect). 5xx, 408 and network errors are retried with exponential backoff and jitter, within the flush deadline.
• A 429 stores its Retry-After deadline in APCu (when enabled) or a temp file, so every PHP-FPM worker skips sends until then.
• A 401 or 413 response drops the batch. With debug: true the SDK logs the reason.
• Identical consecutive errors within 1s are sent once.

Architecture

The SDK follows Clean Architecture. Dependencies point inward only, and tests/Unit/ArchitectureTest.php enforces this in CI.

See ARCHITECTURE.md for the decision log.

Development

Every produced payload is validated against tests/Fixtures/event.schema.json, a test-only JSON Schema that mirrors the shared contract.

The SDK reads no environment variables of its own; everything is passed to init. The example script and the Laravel config read FAULTLINE_API_KEY and FAULTLINE_ENDPOINT.

Publishing

Packagist only publishes packages from a public Git repository. To release:

1. Push this repository to a public host, e.g. github.com/getfaultline/faultline-php.
2. Submit the repository URL at packagist.org/packages/submit (once), and enable the GitHub hook so new tags are picked up automatically.
3. Tag a release: git tag v0.1.0 && git push --tags. Packagist versions come from tags; composer.json has no version field on purpose.

License

MIT