Beacon Bundle Laravel Package

Getting Started

• Install with composer require nowo-tech/beacon-bundle. Confirm the package supports your PHP version (the bundle targets PHP >=8.2 and Symfony 7/8; Laravel 11/12 ships PHP 8.2+ so the runtime constraint is usually fine, but the Symfony framework constraint is not a Laravel constraint).
• Look first at the bundle's DI extension and service definitions (typically DependencyInjection/*Extension.php and Resources/config/services.php). The important artifact is the client service that accepts the DSN — that is the piece you can reuse from Laravel.
• Configure a DSN in the form scheme://publicKey:secret@host:port/projectId. Port and secret are optional; project id is required. Keep it in .env (e.g. BEACON_DSN=...) and reference it from config/services.php rather than hard-coding it.
• First use case: report unhandled exceptions from a Laravel app. Because Laravel does not auto-discover Symfony bundles, the minimal path is to instantiate/register the bundle's client yourself in a service provider and call it from bootstrap/app.php's withExceptions callback or a custom reportable.
• Do not expect php artisan vendor:publish, a facade, or a config/beacon.php. If the bundle's client has Symfony-specific constructor dependencies (HTTP client, event dispatcher), check whether those can be satisfied with Laravel equivalents before committing to the integration.

Implementation Patterns

• Service-provider bridge: register the bundle's client as a singleton in a Laravel provider, injecting the DSN from config('services.beacon.dsn'). Keep this wrapper behind your own small interface (e.g. TelemetryClient) so the rest of the app is not coupled to the bundle's concrete class.
• Exception reporting: in bootstrap/app.php, use ->withExceptions(function (Exceptions $exceptions) { $exceptions->report(function (Throwable $e) { app(TelemetryClient::class)->captureException($e); }); }). Guard against reporting the reporter's own failures.
• Queued envelopes: if the Envelope transport is synchronous, dispatch a job that resolves the client and sends. This keeps request latency predictable and gives you retries/backoff without modifying the bundle.
• Envelope mapping: the bundle speaks the Beacon Envelope protocol, not Laravel's exception format. Build a small mapper that adds request id, route, authenticated user id, and environment before handing off to the client; do not assume Sentry-style context is populated automatically.
• Per-environment DSNs: separate project ids for local/staging/production. Disable sending entirely in local and testing via a config flag checked in your wrapper, not by editing bundle config.
• Health check: an Artisan command (e.g. beacon:test) that sends a synthetic envelope is the fastest way to validate DSN, network egress, and server acceptance after deploy.
• Integration tip: if you run a hybrid Symfony/Laravel estate, register the bundle normally in the Symfony app and use this same wrapper interface in Laravel so both sides emit the same envelope shape.

Gotchas and Tips

• Symfony bundle is not a Laravel package. There is no package discovery, no Laravel config merge, and no service provider. The bundle's extension only runs inside a Symfony kernel. Budget time for manual wiring; this is the main reason day-to-day leverage is lower than a native Laravel telemetry package.
• DSN parsing fails at construction time. Validate the DSN in a config check and fail fast outside production. A malformed DSN should not take down request handling in production — wrap client resolution and sends in try/catch and log locally.
• Secrets and ports are optional but position-sensitive. projectId is the last path segment; a missing secret means the publicKey@host form. Test both forms, especially if you rotate keys per environment.
• Do not let telemetry break requests. A self-hosted Beacon may be unreachable during deploys. Prefer queued sends or a bounded timeout, and always degrade silently.
• Laravel config:cache will not see Symfony bundle configuration. Pass the DSN explicitly through Laravel config; do not rely on the bundle reading BEACON_DSN from the environment on its own.
• Zero stars / zero dependents. Treat the API as unstable: pin the version, wrap the client, and add a contract test that asserts your wrapper still sends an envelope after upgrades. This also makes a later swap to Sentry/Bugsnag a one-file change.
• Extension points to respect if you contribute back: public service ids, configuration keys, and compiler-pass wiring are the bundle's BC surface. Keep PHPDoc and public docs in English, preserve existing block structure in Twig/assets, and add a focused test near the changed behavior.
• Debugging: inspect the actual HTTP request/response from the Envelope transport (Guzzle/Symfony HttpClient middleware or a Laravel Http::fake in tests). Most failures are DSN typos, missing project id, TLS/proxy issues, or the self-hosted server rejecting the envelope version — not client code.