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 support for listener-side filtering
• 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.*)
• Optional console / Messenger failure listeners and optional Monolog handler
• Optional automatic HTTP request transactions (auto_http_transaction)
• 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

composer require nowo-tech/beacon-bundle

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.

BEACON_DSN=https://PUBLIC_KEY:SECRET_KEY@localhost:9444/1

nowo_beacon:
    enabled: true
    dsn: '%env(string:default::BEACON_DSN)%'
    environment: '%kernel.environment%'
    release: null
    server_name: null
    verify_peer: true
    timeout: 5.0
    register_error_listener: true
    ignore_exceptions: []
    send:
        environment: true
        release: true
        server_name: true
        stacktrace: true
        request: true
        user: false          # opt-in; may include PII
        runtime: true        # PHP version
        framework: true      # Symfony version
        os: true

See Configuration for the full send.* reference.

For local self-signed HTTPS only:

when@dev:
    nowo_beacon:
        verify_peer: false

use Nowo\BeaconBundle\Client\BeaconClientInterface;

final class PaymentService
{
    public function __construct(private readonly BeaconClientInterface $beacon)
    {
    }

    public function charge(): void
    {
        try {
            // ...
        } catch (\Throwable $exception) {
            $this->beacon->captureException($exception, ['order_id' => 42]);
            throw $exception;
        }
    }
}

DSN format

{scheme}://{public_key}:{secret}@{host}[:{port}]/{project_id}

Example	Meaning
https://KEY:SECRET@localhost:9444/1	Local HTTPS Beacon on port 9444, project 1
https://KEY:SECRET@errors.example.com/3	Hosted Beacon over default HTTPS port
http://KEY:SECRET@beacon.internal:9081/2	Internal HTTP Beacon (Docker ingest)

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

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

Documentation

• Installation
• Configuration
• 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
• GitHub CI
• Performance

Tests and coverage

Run the test suite with:

composer test
composer test-coverage

or, in the Docker-based maintainer workflow:

make test
make test-coverage
make test-coverage-100

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

Suite	Status
PHP unit + integration	100.00% Lines
TypeScript / Python	N/A (no frontend or Python in this bundle)

Found this useful?

If BeaconBundle helps your project, please star the repository, report issues, and share feedback:

• Repository: nowo-tech/BeaconBundle
• Package: nowo-tech/beacon-bundle