Flare Daemon

A long-running PHP process that accepts error reports, traces, and logs from your application over a local HTTP connection and forwards them to Flare asynchronously. This removes Flare delivery from the critical path of your requests.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

How it works

PHP app ──HTTP──▸ daemon (local) ──HTTP──▸ Flare ingress

Payloads are buffered per API key and entity type and flushed immediately after being accepted. If the daemon is unreachable, the Flare client falls back to direct delivery automatically.

Architecture

The daemon is a single PHP process built on ReactPHP's event loop:

• HTTP server — listens for local requests on the configured address
• Ingest — validates incoming payloads, routes them to the right buffer
• Buffers — per API key, per entity type (errors/traces/logs), in-memory only
• Flush cycle — a periodic timer (every 1s) checks buffer age and size thresholds
• Upstream — sends buffered payloads to Flare ingress over HTTP
• Quota state — tracks 429/403 responses and pauses ingestion per key/type
• Test payloads — bypass the buffer entirely, make a synchronous upstream request, and return the upstream response to the caller
• Composer.lock watcher — optional periodic timer that triggers graceful shutdown on file changes
• Signal handlers — SIGINT/SIGTERM trigger graceful shutdown (drain buffers, then stop)

Packaging & Versioning

Default install, opt-in transport

The intended integration model is that the daemon is installed by default through Flare's shared PHP client packages, including Laravel integrations that depend on that client layer. The presence of the daemon package should not enable daemon transport automatically.

Runtime activation remains explicit. Installation and onboarding docs may steer new users toward enabling the daemon, especially for logging, but "installed by default" and "enabled by default" are separate decisions.

Distribution channels

Composer is the default application install path. The daemon should expose a stable vendor binary for local execution, process managers, and framework wrappers.

PHAR and Docker are additional operator-facing distribution channels:

• Composer / vendor bin — the default path for app installs
• PHAR — a standalone artifact for operators who want a single-file deployment
• Docker — a container/sidecar artifact for environments such as Kubernetes

Laravel may add convenience wrappers around the daemon binary, but the daemon itself is framework-agnostic and must work for standalone PHP and Laravel users alike.

Versioning model

The daemon should have one canonical version stream owned by this repository's Git tags. Packagist package versions, PHAR releases, and Docker image tags should all track that same daemon version.

Client packages should depend on compatible daemon versions, but should not own the daemon's version number themselves. The daemon release cadence and operator-facing artifacts are defined at the daemon package level.

Installation

Docker

docker run -d --name flare-daemon -p 8787:8787 ghcr.io/spatie/flare-daemon

PHAR

php daemon.phar

Usage

Verbose mode

By default the daemon logs lifecycle events (started, stopped) and a periodic summary of forwarded payloads. Pass --verbose (or -v) to also log every individual payload at DEBUG level:

php daemon.phar --verbose

docker run -d --name flare-daemon -p 8787:8787 ghcr.io/spatie/flare-daemon --verbose

Configuration

All configuration is done through environment variables:

Smoke-testing with a real API key

Start the daemon, then use tests/test.sh to send a real error payload through the full buffering/flushing path:

php src/daemon.php --verbose &
bash tests/test.sh YOUR_API_KEY

The script checks /health, sends a normal error to /v1/errors, and polls /status until the buffer drains. Pass -u URL to target a different daemon address.

Building

bash build.sh

This downloads Box (if needed) and compiles the PHAR.

Maintainers can use RELEASING.md for the GitHub-release-driven artifact publishing process.

Load testing

Start the daemon in test mode (accepts payloads, doesn't forward upstream), then run the k6 script:

php src/daemon.php --test &
k6 run loadtest/loadtest.js

On an M-series Mac the daemon sustains ~18,000 reports/sec with p95 latency under 11ms. See loadtest/README.md for details.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Alex Vanderbist
• All Contributors

License

The MIT License (MIT). Please see License File for more information.