Beem Php Laravel Package

Getting Started

• Install the published Composer package and confirm PHP/runtime requirements from the README.
• Read the README sections for DSN configuration, client initialization, transaction/span creation, exception capture, and transport flushing first.
• Add the DSN as an environment variable, for example BEEM_DSN, and expose it through a Laravel config file. Do not commit real DSNs.
• Register the SDK client as a singleton in a service provider, typically AppServiceProvider::register() or a dedicated BeemServiceProvider.
• For a first use case, capture unhandled exceptions and wrap one HTTP request in a transaction. In Laravel 11+, wire exception capture into bootstrap/app.php via withExceptions; on older versions, use App\Exceptions\Handler.
• Add request middleware that starts a transaction, names it from the HTTP method and route, and finishes/flushes it in terminate().
• Smoke-test against a staging/local receiver with a small sample rate before enabling in production.

Implementation Patterns

• Bind the SDK client as a singleton and inject it into middleware, exception handlers, job middleware, and console wrappers rather than constructing it ad hoc.
• HTTP middleware pattern: start a transaction per request, attach route/controller/user/tenant context after auth, finish the transaction in terminate(), and explicitly flush.
• Exception handling pattern: capture the exception, then rethrow or delegate to Laravel’s existing handler. Filter expected/validation exceptions so they do not pollute error reporting.
• Queue job pattern: use job middleware to start a transaction or span per job, capture failures, and flush after each job. Do not rely only on shutdown flush in long-lived workers.
• Console pattern: wrap command execution in a transaction/span and flush on command termination, especially for scheduled tasks and one-off commands.
• Outbound HTTP pattern: add Guzzle/Laravel HTTP client middleware to create spans for external calls and propagate trace headers if the SDK supports it.
• Transaction/span hygiene: use meaningful, low-cardinality names such as GET /orders/{id} rather than raw URLs with IDs; avoid creating spans inside tight loops; always finish spans in finally.
• Batching pattern: tune batch size and flush interval for traffic volume; flush at the end of requests/jobs and before critical exits. If the SDK exposes a sync transport or immediate flush, use it selectively for fatal/high-value errors.
• Configuration pattern: drive DSN, environment, release, and sample rate from env/config; make it easy to disable reporting in tests and local development.
• Testing pattern: disable the transport or point it at a fake/local receiver in automated tests; assert that your middleware and exception hooks call the SDK wrapper without making real network calls.

Gotchas and Tips

• This is a framework-agnostic core SDK, not a Laravel package. Expect no auto-discovery, facade, or Laravel-specific breadcrumbs; you own the integration layer.
• The shutdown flush is useful as a safety net but unreliable under Octane, queue workers, fatal errors, OOM kills, and explicit exit. Add explicit flush points in request/job/command termination.
• Long-running processes are the biggest risk: workers and Octane keep the client alive across requests/jobs. Reset request context, close spans, and flush per unit of work to avoid memory growth and cross-request contamination.
• Avoid duplicate exception reporting if Laravel’s log stack or another APM/Sentry integration already reports errors. Choose one primary reporter or add deduplication.
• Batching means events can arrive late or be lost if the process dies before flush. Decide which errors require immediate delivery and flush those paths explicitly.
• Treat the DSN as a secret. Use separate projects/DSNs per environment, keep it server-side only, and rotate it if exposed.
• Review captured payloads for PII. Sanitize request bodies, headers, user identifiers, and exception messages before capture where needed.
• Watch performance overhead: sample high-volume endpoints, cap span counts, and benchmark batch sizes. Capturing every handled exception or every outbound call can become noisy and expensive.
• v0.1.0 is an initial release, so pin the version and expect API changes. Wrap SDK calls behind a small internal adapter/service so upgrades are localized.
• For debugging, start with a local HTTP receiver and verify DSN parsing, transport timeouts, flush behavior, and timestamps. Log transport failures rather than silently dropping telemetry.
• Check the SDK for extension points such as custom transports or event processors; if available, use them for filtering, enrichment, and test fakes rather than patching vendor code.