Beacon Bundle Laravel Package

Product Decisions This Supports

Observability backend strategy (build vs. buy vs. self-host). This bundle is the last mile of a "self-hosted error tracking" decision: the Beacon server is the product, and this client is the integration that makes it usable from Symfony. Adopting it is a signal that you have chosen data sovereignty over vendor maturity — errors, stack traces, and project metadata stay inside your own infrastructure instead of a third-party SaaS. That is a road-map-level commitment (ops headcount, storage/retention, on-call), not a library choice.

Vendor concentration and lock-in. DSN-based configuration (host, optional port, public key, secret, project id) means environment-per-service wiring is config-only, so migrating between Beacon instances (dev/staging/prod, or a re-hosted server) is a deploy-time change rather than a code change. That lowers the cost of exiting a SaaS error tracker and the cost of exiting Beacon itself — worth stating explicitly when the alternative is an SDK with deep framework coupling.

Feature-parity decisions for internal platform teams. If you run a shared Symfony platform (many services, one telemetry standard), this bundle defines the "supported client" contract: PHP >=8.2 (<8.6), Symfony ^7.0 || ^8.0. That constrains your framework upgrade calendar — a service on Symfony 6.x cannot standardise on this client without an upgrade. It also becomes the answer to "which error-reporting library do new services get in the skeleton?" — a one-line composer + DSN vs. a bespoke wrapper.

Use cases that justify it:

• Regulated / data-residency workloads (EU-only, public sector, healthcare, finance) where shipping stack traces to a US SaaS is a procurement or legal blocker.
• Air-gapped or on-prem customer deployments where a SaaS DSN is not reachable at all — the self-hosted DSN model is the only viable shape.
• Cost control at high event volume, where per-event SaaS pricing becomes non-linear and a fixed-cost self-hosted collector wins.
• Internal dogfooding of Beacon itself if the organisation also builds/maintains the server — the client is the reference integration.

Scope decision to make deliberately: adopt as error/exception reporting only. This package speaks the Beacon Envelope protocol; it does not advertise distributed tracing, profiling, session replay, or product analytics. If the roadmap needs those, this is one lane of the observability stack, not the whole stack — plan an OpenTelemetry-shaped complement rather than expecting this bundle to grow into it.

Portfolio caveat for a Laravel-heavy estate: despite the framing, this is a Symfony bundle, not a Laravel package. If the majority of services are Laravel, adopting it means either maintaining a parallel Laravel client against the same Envelope protocol or standardising on Symfony for telemetry-enabled services. That is a real architectural cost and belongs in the decision record.

When to Consider This Package

Adopt when all of these hold:

• You already run (or have firmly committed to run) a self-hosted Beacon server, and its Envelope endpoint is reachable from your runtime — this client has nothing to talk to otherwise.
• Data residency, air-gap, or per-event cost is a stated requirement, not a nice-to-have.
• Your services are on Symfony 7.x/8.x and PHP 8.2–8.5, matching the bundle's declared support matrix; you are not asking it to bridge an older LTS.
• You want configuration-only onboarding: a DSN string per environment, no custom transport code, no per-service wrapper class.
• You are comfortable owning the operational surface of the server (uptime, storage growth, retention, access to the secret keys embedded in DSNs).

Treat it as a pilot, not a standard, until these signals improve:

• Adoption evidence is essentially zero — 0 stars, 0 dependents. There is no public evidence of production use, no third-party issue history to mine for failure modes, and no community to absorb maintenance if the author steps away. Bus factor is the dominant risk, and it is not mitigated by the MIT licence alone (MIT gives you the right to fork, not the capacity).
• The release date (2026-10-26) is ahead of the current date, which is a metadata smell. Verify the actual tag, changelog, and whether the published version is installable before it appears in a roadmap.
• No published compatibility or deprecation policy beyond the CI minors — you cannot yet predict whether a Symfony 8.1 minor will break it.
• DSNs embed a secret. Confirm how that secret is handled at rest in your config management and whether it is scoped per project; a leaked DSN with an ingestion secret is a write-access credential, and that needs a rotation story before rollout.

Look elsewhere when:

• You need a mature APM — tracing, spans, profiling, release health, alert routing, dashboards. Sentry/OpenTelemetry-shaped tools are years ahead and this bundle does not claim that surface.
• You need commercial support, an SLA, or a security-review package a procurement team will accept. There is no vendor here.
• Your estate is predominantly Laravel or non-Symfony PHP — the integration work, not the protocol, is the cost.
• You want zero operational load — self-hosting a collector means you now own an ingestion service with its own availability expectations, and an error tracker that is down during an incident is worse than none if the team has stopped watching logs.
• You need guaranteed forward compatibility across framework majors without carrying a fork.

How to Pitch It (Stakeholders)

One-liner for executives: A small, MIT-licensed Symfony client that lets our applications report errors to an error-tracking server we operate, so diagnostic data — including stack traces that can contain customer data — never leaves our infrastructure. Integration cost is a composer dependency plus one DSN per environment; the ongoing cost is operating the collector, not licensing the client.

For engineering leadership:

• Cheap to try, cheap to reverse. Configuration-only adoption; switching Beacon instances or backing out is a config/deploy change. Keep the existing logging path intact during the pilot so removal is a rollback, not a rewrite.
• Cost shape flips from variable to fixed. Self-hosted ingestion trades per-event SaaS spend for server, storage, and retention costs plus on-call. Model the crossover volume before committing, and be honest that at low volume the SaaS is probably cheaper.
• Maturity is the real risk, not the code. Zero stars and zero dependents means no external validation and a single-maintainer bus factor. Mitigations: pin an exact version, run it on one or two non-critical services first, keep the DSN and the reporting path behind our own thin interface so a swap to a mainstream SDK is contained, and budget a day to read the transport code before it touches production.
• A leaked DSN is a credential leak. The DSN carries a secret; it must live in secret management, not in committed config, and it needs a documented rotation procedure.

Recommendation to put in front of the decision-maker: Approve a time-boxed pilot on one low-risk Symfony service, scoped to exception reporting only, with explicit exit criteria — (a) events arrive reliably and are actionable, (b) the server's operational load is acceptable for one team, (c) the client survives one framework patch upgrade without a fork. Do not standardise it across the estate, and do not position it as an APM replacement, until those gates pass and someone is named as owner of both the client and the Beacon server. If the organisation cannot name that owner, this is a buy decision, not a build one.