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.
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.
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.
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)
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.
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.
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.
docker run -d --name flare-daemon -p 8787:8787 ghcr.io/spatie/flare-daemonphp daemon.pharBy 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 --verbosedocker run -d --name flare-daemon -p 8787:8787 ghcr.io/spatie/flare-daemon --verboseAll configuration is done through environment variables:
| Variable | Default | Description |
|---|---|---|
FLARE_DAEMON_LISTEN |
127.0.0.1:8787 |
Address to listen on |
FLARE_DAEMON_UPSTREAM |
https://ingress.flareapp.io |
Flare ingress URL |
FLARE_DAEMON_BUFFER_BYTES |
262144 (256 KB) |
Size threshold per buffer (used by maintenance safety net) |
FLARE_DAEMON_FLUSH_AFTER_SECONDS |
10 |
Seconds before maintenance flushes oldest buffered items (safety net) |
FLARE_DAEMON_UPSTREAM_TIMEOUT_SECONDS |
10 |
Timeout in seconds for upstream requests |
FLARE_COMPOSER_LOCK |
(none) | Path to composer.lock — daemon stops when the file changes |
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_KEYThe 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.
bash build.shThis downloads Box (if needed) and compiles the PHAR.
Maintainers can use RELEASING.md for the GitHub-release-driven artifact publishing process.
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.jsOn an M-series Mac the daemon sustains ~18,000 reports/sec with p95 latency under 11ms. See loadtest/README.md for details.
composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.