README

⭐ 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.*)
Optional console / Messenger failure listeners (nested console extras; optional Scheduler ScheduledStamp context) 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

Additional documentation

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)

nowo-tech / beacon-bundle

Maintainers

Package info

Statistics

Security