Opcache Bundle Laravel Package

Product Decisions This Supports

• Roadmap fork: OPcache tuning vs. application-level optimization. The single highest-value output is a hit rate, memory used/free, wasted-script count, and restart-pending flag. That data decides whether the next sprint goes into php.ini tuning (memory_consumption, max_accelerated_files, revalidate_freq, validate_timestamps) or into query caching and app-level work — a decision otherwise made on instinct. Treat the package as the metric specification for that decision, not as the thing you install to get it.
• Build vs. buy for a thin internal diagnostic. For a Laravel product the honest framing is "build": roughly 200 lines wrapping opcache_get_status(false) and opcache_get_configuration(), exposed behind a local-only route or as a Laravel Debugbar collector. This package is the reference implementation and scope guard — it tells you which fields are worth surfacing and which are noise, so the build stays at a day instead of drifting into a week.
• Observability tiering (dev-time inspection vs. APM). It draws a clean line between "eyeball the cache on staging" and "we need history, trends, and alerts." That line is the input to the real budget question: is a Tideways/Blackfire/New Relic contract justified this quarter? Deciding "dev-only inspection is enough" is a legitimate, defensible outcome — and a cheaper one.
• Release and deploy hygiene. Confirming that OPcache is actually reset on deploy — and that the cache-clear step in the pipeline does what the team believes — is a recurring source of "why is staging running old code?" incidents. Surfacing restart_pending / restart_in_progress turns a 20-minute SSH investigation into a glance.
• Capacity planning inputs for pre-production. Memory wastage and cached-script counts on a staging box inform container memory limits and PHP-FPM pool sizing before they become production incidents.
• Supply-chain policy precedent. This is a useful worked example when defining what counts as an adoptable dependency: MIT, ~22 stars, 0 dependents, single maintainer, no security disclosure channel. Getting the team aligned on "this tier of package is reference material, never a Composer requirement" pays off beyond this one decision.
• Use cases it genuinely serves: diagnosing a hit-rate regression after a dependency bump, validating a php.ini change before it ships, onboarding engineers to how the opcode cache behaves, and answering "is the cache even on?" during non-production triage.

Caveat for the decision record: despite being catalogued as a Laravel/PHP package, this is a Symfony bundle with a Web Profiler toolbar panel. There is no service provider, no Debugbar integration, and no registration path in a Laravel app. Do not put "adopt this package" on the roadmap — put "build the equivalent" there.

When to Consider This Package

Consider it — as reference material only — when all of these hold:

• The need is specifically OPcache visibility in dev/staging, not broad application performance monitoring.
• The team is willing to vendor ~200 lines of collector logic into an internal class or Laravel Debugbar collector rather than adding a dependency (MIT permits this; retain attribution).
• You want a checklist of metrics worth tracking — hit rate, memory used/free/wasted, cached and wasted script counts, restart flags — validated by someone else's implementation before you write your own.
• An APM decision is pending and you need a cheap stopgap that ships nothing to production.
• Someone owns the resulting internal tool and its PHP-version upkeep.

Look elsewhere when:

• The stack is Laravel. Non-viable as a composer require in every practical sense: the symfony/* constraints target the Symfony 2.x/3.x era, Laravel 9+ needs Symfony 6.x/7.x, and resolution will fail or force an untenable downgrade of core components. Do not attempt to satisfy it. Build the internal equivalent instead.
• You need production telemetry, history, trends, or alerting. This is per-process, per-node, no retention, no thresholds. Route that requirement to an OPcache metrics exporter into Prometheus/Grafana, or to an APM vendor with a support contract.
• The fleet is multi-node, behind a load balancer, or on Octane. The panel samples one PHP instance on one host. Preloading and Swoole/RoadRunner worker semantics make the picture partial or unfamiliar.
• Supply-chain policy is strict. Zero dependents and negligible adoption mean zero ecosystem validation and an indefinite fork obligation. That fails most dependency gates.
• The need is a shared or permissioned surface. A profiler toolbar is a developer tool; exposing it in shared environments is a security review item (it leaks absolute filesystem paths and OPcache configuration), not a feature.
• You are the Symfony shop exception. If the target really is Symfony with WebProfilerBundle already in the dev workflow, this drops in with near-zero integration work — pin the version, enable in dev only, and accept that it may go unmaintained.

How to Pitch It (Stakeholders)

To executives (30 seconds): This is a free, MIT-licensed developer tool that shows whether PHP's opcode cache is working — hit rate, memory use, wasted scripts. It is a Symfony component, so it does not plug into our Laravel apps; what we take from it is the short list of metrics worth showing and a proven ~200-line implementation we can reproduce behind a developer-only route in about a day. It ships nothing to production, costs no license, and answers a question that today burns engineer-hours during performance work and after confusing deploys. It is not a platform investment and does not replace an APM — it helps us decide whether we need one. Recommendation: fund a one-day internal build, adopt nothing.

To engineering: Do not add this as a dependency — it is a Symfony bundle and its symfony/* constraints will conflict with modern Laravel. Instead, vendor the collector logic (MIT, keep attribution) into an internal/opcache-inspector class: opcache_get_status(false) plus opcache_get_configuration(), a singleton repository bound in a ServiceProvider, and either a local-only route behind auth + environment middleware or a Laravel Debugbar collector. Budget ~1 day, plus 0.5 day/year for PHP-version upkeep.

Four things will bite you, and they should be in the ticket up front: (1) opcache_get_status() returns false when OPcache is disabled or blocked by opcache.restrict_api — degrade gracefully, never throw; (2) CLI and FPM report different OPcache instances, so php artisan opcache:status shows an empty cache unless opcache.enable_cli=1 — this is the number-one "the tool is broken" ticket, document it; (3) the scripts array can hold tens of thousands of entries, so always pass false and aggregate server-side; (4) the original collector predates PHP 7.4 preloading and PHP 8 JIT, so validate the memory and hit-rate math against fixture payloads per PHP minor rather than trusting its assumptions.

Sequence it as a timeboxed spike (≤2 days) answering one question: does OPcache hit-rate and memory data change any decision we make? If the answer is "we want to eyeball it occasionally," ship the guarded route and stop. If it is "we want alerting on cache churn across the fleet," skip this entirely and go to an APM vendor — that path has support, aggregation, and no fork obligation. The package's real value here is as a reference implementation and a checklist, not as software to run.