makfly/beacon-sdk-php

Beacon telemetry SDK for PHP / Symfony 8 — errors, traces, logs. Home-grown, zero external instrumentation dependency.

v0.3.0 2026-06-17 17:09 UTC

Requires

• php: >=8.2
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^11.0
• symfony/config: ^7.0 || ^8.0
• symfony/dependency-injection: ^7.0 || ^8.0
• symfony/event-dispatcher: ^7.0 || ^8.0
• symfony/http-kernel: ^7.0 || ^8.0

Suggests

• doctrine/dbal: To capture db_query spans via the Beacon Doctrine middleware
• symfony/http-kernel: For the Symfony bundle integration (exception capture, request spans)
• symfony/messenger: To trace queued message handling as entry points

MIT

• symfony
• telemetry
• tracing
• error-tracking
• observability
• otel

README

Beacon telemetry SDK for PHP / Symfony 8 — errors, traces, logs. Home-grown, zero external instrumentation dependency (no open-telemetry/*, no sentry/*). Ships as a Symfony bundle; the PHP namespace is KevStudios\Beacon\.

Install

composer require makfly/beacon-sdk-php
php vendor/makfly/beacon-sdk-php/bin/setup

The setup script auto-configures your Symfony project (idempotent, safe to re-run):

• config/bundles.php — registers BeaconBundle for all environments
• config/packages/beacon.yaml — creates the config with safe defaults
• .env / .env.example — appends BEACON_ENDPOINT and BEACON_TOKEN

That's it. By default the SDK is a silent no-op — zero network calls, zero overhead. Set the env vars to activate:

# .env.local
BEACON_ENDPOINT=https://beacon.example.com
BEACON_TOKEN=priv_my_project

Before the package is on Packagist, add a VCS repository:

"repositories": [{ "type": "vcs", "url": "https://github.com/MakFly/beacon-sdk-php.git" }]

How it works

Env vars set?	Behavior
Both set	Errors, traces and logs are sent to the ingester
Empty or absent	Silent no-op — no cURL, no overhead

Unhandled kernel exceptions are captured automatically via ExceptionSubscriber. The buffer flushes on kernel.terminate (post-response). The transport swallows every failure — telemetry never breaks the host app.

Configuration

All options in config/packages/beacon.yaml (with defaults):

parameters:
    # Default to empty STRING when the env var is unset (prod with no ingester yet).
    # Critical: CurlSender expects a `string` — '' constructs + silently no-ops, whereas
    # `null` (what `%env(default::...)%` returns) throws a TypeError at boot → 500 → rollback.
    env(BEACON_ENDPOINT): ''
    env(BEACON_TOKEN): ''

beacon:
    endpoint: '%env(BEACON_ENDPOINT)%'            # ingester URL (empty = disabled)
    token: '%env(BEACON_TOKEN)%'                  # project token (empty = disabled)
    service_name: 'iautos-api'                    # optional
    service_version: ~                            # optional (null)
    stage: '%kernel.environment%'                 # optional
    application_path: '%kernel.project_dir%'      # optional
    collect_arguments: true                       # capture exception arguments
    traces_sample_rate: 1.0                       # 0.0–1.0
    censor_keys:                                  # scrubbed from attributes
        - password
        - authorization
        - cookie
        - token
        - secret
        - api_key

Versioning & release

SemVer via git tags (Packagist-driven). See CLAUDE.md. Tags are immutable.

License

MIT. Part of the Beacon telemetry suite.