Metrics Laravel Package

Getting Started

prismamedia/metrics is a framework-agnostic PHP metrics abstraction: you call a small interface (counters, gauges, timings) and swap the backend adapter underneath without touching call sites. v2.1.0 is an infrastructure release — it adds Symfony 7 compatibility and expands the PHP test matrix. That matters directly for Laravel developers: Laravel 11 ships on Symfony 7 components, so v2.1.0 is the first release you can install cleanly in a modern Laravel app without constraint conflicts.

Minimal steps:

1. composer require prismamedia/metrics:^2.1 — pin the minor, since ^2.0 will not guarantee the relaxed Symfony constraint.
2. If you were previously blocked on Laravel 11 with a symfony/* conflict, re-run composer update prismamedia/metrics --with-dependencies and confirm with composer why-not prismamedia/metrics 2.1.0.
3. Read the source in this order: the metrics client/interface (the methods you'll actually call), the adapter implementations (StatsD/InfluxDB/Null or whichever backends you use), then any Symfony bundle/DI extension — the extension is the best documentation of what configuration keys the package expects.
4. Bind it once in AppServiceProvider::register() as a singleton and inject the interface, not the concrete client.

First use case: instrument a single controller and a single queued job. Add a counter for requests by status code and a timing around the handler, then look at the numbers in your backend before instrumenting anything else. Metrics you don't read are just latency.

Implementation Patterns

Service container wiring. The package predates Laravel and has no Laravel service provider, so you own the binding. Build the client from config('metrics.*') in a dedicated MetricsServiceProvider, bind it as a singleton, and bind the interface to it so tests can swap the implementation. Register it late enough that config is available, but early enough that middleware and jobs resolve it.

Environment-driven adapter selection. Use the Null adapter (or an in-memory fake) for local and testing, and the real backend only in staging/production. This keeps dev machines from emitting garbage into shared dashboards and keeps your test suite from opening sockets.

Middleware for request-level metrics. A single terminable middleware covers most of your needs: start a timer in handle(), and in terminate() emit the duration plus a counter tagged by HTTP status. Use terminate() rather than the end of handle() so the measurement includes response delivery and doesn't sit on the critical path.

Queue instrumentation via events. Rather than editing every job, listen to JobProcessing/JobProcessed/JobFailed and derive counters and timings from the event payload. Key by job class name, never by job ID or payload hash — that's how you blow up cardinality in one deploy.

Timer discipline. Wrap external calls (HTTP, Redis, third-party APIs) in try/finally so failures still record a duration, and tag failures with an explicit outcome dimension rather than letting them look like slow successes. If the package's timer returns a duration, normalise units at the call site — mixing milliseconds and seconds across a codebase is the most common source of "the graph is wrong" bug reports.

Decorator for testability. Wrap the package client in a thin App\Metrics\Metrics class exposing only the methods you use. That gives you one place to enforce naming conventions, add default tags, swallow adapter exceptions, and swap to an in-memory recorder in tests without the package's own fakes.

Gotchas and Tips

• The Symfony 7 bump is additive, not breaking. v2.1.0 is a constraint relaxation plus CI coverage; no API removals are signalled. Upgrading from 2.0.x should be a no-op at the call-site level. The only realistic friction is Composer resolution if you have transitive pins holding symfony/* at 6.x.
• PHP version support is only as real as the test matrix. The release "runs tests on new PHP versions" — check the CI config for the matrix before assuming a specific PHP minor is supported in your environment. PHP 8.4 deprecation noise can appear from dependencies even when the package itself is clean.
• Metrics must never break a request. Network-backed adapters (StatsD over UDP, HTTP-based backends) can throw or block. Wrap emissions in your decorator with a catch-all and log at debug level; a failed metric is not a failed checkout.
• Watch flushing behaviour. UDP-based adapters are fire-and-forget; HTTP or buffered adapters may need an explicit flush. If you see metrics disappearing on short-lived processes (queue workers, artisan commands), that's a missing flush at shutdown, not a lost packet.
• Cardinality is your problem, not the package's. The library will happily accept a raw URL or user ID as a tag. Normalise to route patterns and bounded enums before the call site.
• No Laravel facade. Don't reach for Metrics::increment() in Blade or quick scripts; resolve the interface out of the container so the decorator and test swaps keep working.
• Config caching. If you publish a config file, remember php artisan config:cache bakes it in — changing METRICS_* env values requires a re-cache in deployed environments.
• Extension points. If the shipped adapters don't fit your backend, implement the package's metrics interface yourself rather than forking; that's the stable contract and survives minor releases.