Pinba Bundle Laravel Package

Technical Evaluation

Architecture fit. The first thing to flag: intaro/pinba-bundle is a Symfony bundle, not a Laravel package. It ships a Bundle class, DI compiler passes, and Doctrine/Twig/Memcache event subscribers — none of which have a direct analogue in Laravel's service provider / middleware / facade model. The underlying mechanism, however, is framework-agnostic: the pinba PECL extension exposes procedural functions (pinba_timer_start, pinba_timer_stop, pinba_script_name_set, pinba_flush) that any PHP runtime can call. So the bundle is best evaluated as a reference implementation for how to instrument a PHP framework, not as something we install into a Laravel app.

Integration feasibility. Moderate effort, low conceptual risk. A Laravel integration would be a thin package of our own:

• A service provider that sets pinba_script_name_set() and registers global middleware for request-level timers.
• Middleware/terminable middleware to flush on response.
• Eloquent analogue of the Doctrine subscriber (query timers via DB::listen).
• Blade analogue of the Twig timer (less valuable; Blade compiles once, so timing is mostly first-render).
• Optional memcached timing only if we actually use memcached (many Laravel stacks use Redis — the bundle has no Redis instrumentation).

The bundle's own source is small and readable, so we can crib the timer lifecycle and tag conventions rather than reinvent them.

Technical risk. This is the dominant concern, and it's mostly upstream of the bundle:

1. Pinba project health. Pinba is a MySQL storage engine + UDP collector. The original project is effectively dormant and has known friction with MySQL 8. The community fork (pinba2/pinba_server) is the realistic target. Either way, we'd be operating a niche, low-activity daemon.
2. PECL extension availability. pecl/pinba has lagged PHP major versions; PHP 8.x support depends on forks/patches. This is a hard blocker if our fleet is on PHP 8.2+ without a maintained build.
3. Package signal. 22 stars, 0 dependents, and a reported last release of 2026-06-09 — a future date that is almost certainly a metadata artifact. We must verify the actual composer.json and tag history before trusting the release cadence claim.
4. Single-maintainer bus factor.

Key questions.

• Is our PHP runtime version covered by a maintained build of the pinba extension?
• Are we willing to own a Pinba (or Pinba2) server plus its MySQL storage and retention?
• What is the actual driver for this — real-time per-request profiling, or aggregate latency dashboards? If the latter, OpenTelemetry/APM may dominate on effort.
• Does the "opportunity: 50.38 vs overall 13.89" gap reflect genuine latent demand for Pinba-style real-time timers, or just sparse sampling?
• Which of our caches are memcached vs Redis, and does the missing Redis path undermine the value proposition?

Integration Approach

Stack fit. Poor as a drop-in, acceptable as a pattern. Laravel's request lifecycle, container, and event model differ enough that a Symfony bundle cannot be consumed. The realistic shape is a small first-party Laravel package (~300–500 LOC) that uses the pinba extension directly and borrows this bundle's timer naming and tagging conventions. That keeps us on supported Laravel idioms while preserving the operational semantics the bundle encodes.

Migration path. There is nothing to migrate from in a Laravel context, so this is greenfield:

1. Validate extension + server availability in a sandbox before writing any code.
2. If green, build the Laravel shim (provider, request middleware, DB::listen hook, flush-on-terminate).
3. If the extension cannot be built against our PHP version, stop and evaluate alternatives — do not attempt to vendor-patch a PECL extension as a product bet.
4. Keep the shim behind a config flag so it can be disabled per-environment; Pinba should never be a hard dependency of application boot.

Compatibility. Two axes:

• Framework: none — Symfony bundle vs Laravel. Explicitly out of scope as a dependency.
• Runtime: tied to the extension's PHP version matrix and to the Pinba server's MySQL compatibility. Both need a written compatibility statement before sign-off. The bundle's own composer.json constraints (symfony/* versions) are irrelevant to us.

Sequencing.

1. Spike (1–2 weeks): stand up Pinba2 server in a non-prod environment; compile/test the extension against our exact PHP build; measure overhead.
2. Shim (1–2 weeks): minimal Laravel package, request + DB timers only. Skip Twig/Blade and memcache initially.
3. Pilot (2–4 weeks): one service, one team, compare Pinba latency data against existing APM/structured logs for fidelity.
4. Decide: expand, or retire in favor of OpenTelemetry. Treat this as a time-boxed evaluation, not an adoption.

Operational Impact

Maintenance. We would own: the Laravel shim (small, ours), the PECL extension build (moderate — must rebuild per PHP upgrade, and PHP upgrades now carry an extra gate), and the Pinba/Pinba2 server + MySQL storage (real infra). The upstream bundle is not something we maintain, but it is also not something we can lean on for fixes. Budget roughly a one-time 3–4 week investment plus recurring cost at every PHP major upgrade.

Support. No SLA, no vendor, 22 stars, zero dependents — effectively no community to escalate to. Internal ownership is mandatory from day one. Document the timer tag schema and the shim's internals so knowledge doesn't concentrate in one engineer.

Scaling. Architectural limits to state plainly: Pinba ingests over UDP, so samples are lossy under load by design (acceptable for aggregate latency stats, unacceptable for auditing). Storage is MySQL-backed with bounded retention; it is a recent-window real-time view, not a long-term metrics store. It also has no meaningful cardinality control — tag explosion (e.g., per-user IDs, per-query text) will degrade the collector. Enforce a tag allowlist in the shim.

Failure modes.

• Extension missing/misconfigured: calls become fatal errors or no-ops depending on build — must be guarded with function_exists() and a config gate so application boot never hard-fails.
• Pinba server down: UDP is fire-and-forget, so the app keeps running — this is actually a favorable failure mode, but it means silent blind spots. Alert on collector-side ingest rate.
• Timer leaks: unclosed timers accumulate in request scope; the shim must register a terminate hook that stops any dangling timers and flushes.
• Overhead: per-timer cost is small but non-zero; DB query timers on a chatty endpoint can add measurable overhead. Gate DB instrumentation separately from request instrumentation.
• Data trust: lossy UDP + no cardinality control means dashboards can mislead. Cross-check against a second source during the pilot.

Ramp-up. Low for engineers (the API is a handful of functions), moderate for the platform team (extension builds, collector ops, retention tuning). Two to three days of onboarding should cover the shim; the collector and extension toolchain is the real learning curve.

Recommendation. Do not adopt intaro/pinba-bundle as a dependency — the Symfony/Laravel mismatch alone disqualifies it. Use it as a design reference for a time-boxed Laravel-native Pinba shim, and only proceed if the extension builds cleanly against our PHP version and we accept ownership of a Pinba2 collector. If the underlying need is aggregate latency visibility rather than sub-second per-request timers, OpenTelemetry is the lower-risk path and should be evaluated in parallel during the spike.