Download the PHP package nowo-tech/beacon-bundle without Composer

Beacon Bundle

⭐ Found this useful? Install from Packagist and give the repo a star on GitHub.

Symfony client for Symfony Beacon, the self-hosted error-tracking server from Nowo. BeaconBundle sends Envelope requests to any Beacon host described by a DSN and provides both manual APIs and an optional automatic exception listener.

This bundle is FrankenPHP worker mode friendly.

Features

• DSN-driven ingest with host, optional port, public key, required secret, and project id
• Empty DSN disables reporting without changing application code
• Envelope transport to POST /api/{project_id}/envelope/ with X-Beacon-Auth + envelope DSN auth
• Delivery modes: transport.mode sync (default), async (finalize on terminate), or messenger (queue)
• Versioned User-Agent (beacon-bundle/{composer-version})
• Manual APIs through BeaconClientInterface
• Optional kernel.exception listener for uncaught HTTP exceptions
• ignore_exceptions / ignore_paths support for listener-side filtering (defaults align with Beacon host infra exclusions + Chrome DevTools probe)
• Configurable outbound context (send.*: stacktrace, request, user, PHP/Symfony versions, OS, …)
• Message events can include current stacktrace; frames may include source context when files are readable
• HTTP events attach request URL/method (and safe headers) when available
• Breadcrumbs (addBreadcrumb) and performance transactions (captureTransaction)
• Public tags API (setTag / setTags) and optional before_send scrubbing hook
• Opt-in Doctrine SQL + HttpClient request spans / breadcrumbs (instrumentation.*)
• Database exceptions attach contexts.db (SQLSTATE / SQL) without requiring Doctrine instrumentation
• Optional console / Messenger failure listeners (nested console extras; optional Scheduler ScheduledStamp context) and optional Monolog handler
• Optional automatic HTTP request transactions (auto_http_transaction)
• Console command nowo:beacon:test to probe DSN connectivity (sync Envelope; --check-only available)
• Precise timestamps (fractional Unix + ISO-8601 with microseconds)
• Local FrankenPHP demo covering messages, exceptions, full context, fingerprints, breadcrumbs, user, transactions / N+1, auto HTTP tx, Monolog, Messenger failures, and console errors

Installation

Symfony Flex registers the bundle, creates config/packages/nowo_beacon.yaml, and adds an empty BEACON_DSN entry to your env file.

Quick start

Full walkthrough (create a Beacon project, copy the DSN, verify events): Getting started.

See Configuration for the full send.* reference.

Verify the DSN:

For local self-signed HTTPS only:

DSN format

project_id is a positive numeric legacy id or a canonical project UUID (Symfony Beacon settings / buildDsn).

Generate keys in Beacon project settings, or run make seed in the symfony-beacon repository to create demo data and print a DSN (includes secret).

FrankenPHP worker

This bundle is compatible with FrankenPHP worker mode when the kernel is not reset between requests (scenario B). Request-scoped breadcrumbs, spans, tags, trace ids, auto HTTP transactions and async pending POSTs are cleared without relying on Symfony’s services_resetter. Details: FrankenPHP worker audit.

The bundled demo uses FrankenPHP. Default FRANKENPHP_MODE=worker; set classic for Caddyfile.dev (hot-reload friendly). See Demo/FrankenPHP.

Documentation

• Installation
• Configuration
• PSR evaluation (REQ-CS-007)
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit

Additional documentation

• Getting started (Symfony Beacon + bundle)
• Demo/FrankenPHP
• FrankenPHP worker audit (reset_kernel false)
• GitHub CI
• Performance

Tests and coverage

Run the test suite with:

or, in the Docker-based maintainer workflow:

Coverage (Lines): 100.00% (measured with make test-coverage / PCOV).