Opcache Bundle Laravel Package

Product Decisions This Supports

• Deploy pipeline design (the real decision). This package surfaces a genuine operational question: does our release process deterministically invalidate stale bytecode? If production runs opcache.validate_timestamps=0 for performance — a common and defensible choice — then a deploy without an invalidation step means the old code keeps serving traffic. That is the "fix is deployed but not live" incident class. The package is a reminder to make this an explicit, auditable pipeline step rather than an implicit hope.
• Build vs. buy on operational glue. The honest framing is not "adopt a dependency" but "write ~20–30 lines in a deploy hook, use a framework-native command, or pull in a third-party bundle." This is a make-vs-buy call on a very small feature, and the answer should be driven by maintenance policy and correctness of mechanism, not feature comparison.
• Framework fit — a catalogue error to correct. Despite being listed as a Laravel/PHP package, it is a Symfony bundle: DI extension, services.xml, Symfony Console command registration. No service provider, no facade, no extra.laravel block. For a Laravel target, the bundle wiring is dead weight; only the small command class is even portable. If the shortlist was generated by keyword matching, fix the catalogue — this will otherwise keep resurfacing in Laravel evaluations.
• Incident response / runbook content. A console-invokable reset is a useful MTTR lever for "stale code" incidents provided it actually reaches the process serving traffic. Whether it does depends on SAPI scoping (CLI vs. FPM) — so this belongs in the runbook as a verified step, not in the architecture as an assumption.
• Multi-app platform standardisation. If the org runs several PHP apps, a shared, documented cache-invalidation convention reduces per-app snowflakes. But framework-native paths (Laravel's optimize:clear, Symfony's cache commands, or an FPM reload) usually win this axis because they are already maintained and already in the deploy recipe.
• Dependency hygiene policy. Archived repo, 30 stars, zero dependents, no CVE path. Its appearance on an evaluation shortlist is a useful forcing function to state a policy on accepting unmaintained dependencies for operational tooling — even when the code itself is trivial and MIT-licensed.

When to Consider This Package

Consider it only when all of the following hold:

• The application is Symfony. Not Laravel. There is no Artisan or service-container integration; adopting it for Laravel means bypassing the bundle and extracting the single command class — at which point you are not adopting the package at all.
• OPcache is configured to go stale, i.e. validate_timestamps=0 or a long revalidate frequency, so bytecode genuinely survives a file change.
• No existing reset mechanism exists, and the command would execute in the same SAPI / shared memory segment as the web workers. This is the decisive caveat: a CLI process normally has its own OPcache (or opcache.enable_cli=0 and none at all), so a CLI-invoked reset frequently clears nothing that matters and exits 0 — a green deploy step with false assurance. Where that mismatch exists, use a tool that talks to the FPM socket (cachetool) or a plain FPM/worker reload.
• The team formally accepts an unmaintained dependency for an operational-only concern (MIT, tiny surface, no network calls — low supply-chain risk, but zero upstream fixes and stale Composer constraints likely blocking modern PHP/Symfony versions).

Look elsewhere when:

• The app is Laravel — the framework's optimize:clear / clear-compiled path already covers compiled-file and OPcache invalidation; adding this is pure duplication.
• Deploys already reload PHP-FPM or gracefully restart workers — the problem is moot.
• The platform is containerised with immutable images and rolling replacement — new containers boot with fresh OPcache; the command is redundant.
• opcache.restrict_api or disable_functions is set in hardened images — the reset can be suppressed without a surfaced error.
• You run Laravel Octane — workers hold code in memory independently of OPcache; a reset without octane:reload leaves stale code running.
• The org forbids archived dependencies — correct action is to document the reset in the runbook and not add a dependency.

In every "look elsewhere" case, capture the underlying requirement ("deploy must invalidate OPcache deterministically, and we must be able to prove it did") as a pipeline task with a verification step.

How to Pitch It (Stakeholders)

Bottom line: do not adopt as a dependency; solve the underlying need directly. Adopt the pattern, not the package.

For executives. This is a 30-star, archived, single-command utility with no licensing cost and no strategic value. Adopting it would add an unmaintained entry to the supply chain in exchange for roughly twenty lines of code we would own anyway. There is no commercial or roadmap impact either way. The only question that matters — does our deploy reliably invalidate stale bytecode? — is a one-line addition to the pipeline plus a verification check. Recommend: reject the dependency, fund the pipeline step, close the item.

For engineering. The package addresses a real problem — stale OPcache after deploy when timestamp validation is disabled — but the problem is better solved one level down. On Laravel, the framework already handles it. On Symfony, either a deploy hook calling opcache_reset() in the correct context, or a cachetool invocation against the FPM socket, covers it. Three ranked options: (A) vendor the ~30-line command as a native command with no external dependency — acceptable; (B) replace with cachetool, maintained and FastCGI-based — recommended if cache invalidation is genuinely required; (C) install the bundle and bridge Symfony wiring into Laravel — reject, no benefit over A and inherits archived-repo risk and stale constraints.

The trap to communicate explicitly. A reset executed from a separate CLI process usually does not touch the web workers' shared memory. A green deploy step therefore does not guarantee fresh bytecode. Validate the premise on staging first: run the reset, mutate a known file, confirm the served app picks up the change. If it does not, re-scope to the FPM-socket approach.

Operational notes worth carrying regardless of decision.

• Cold-cache stampede — a reset invalidates bytecode for the whole pool; the next wave recompiles, spiking latency and CPU. Batch it into the deploy, never run it on a timer or at peak.
• Mid-flight swap — sequence as symlink swap → reset → warm, to avoid "cannot redeclare" / stale-include errors.
• Fleet fan-out — the command is node-local with no cluster awareness; on N hosts the deploy tool (Envoy, Deployer, Ansible) must invoke it N times, and partial failures go unreported.
• Silent failure — opcache_reset() returns false on failure; throw rather than log-and-continue, and verify with a smoke assertion (e.g. a version-constant endpoint) so the step fails loudly instead of no-op'ing.

Recommendation. Reject as a composer require; treat archived status as disqualifying for a dependency and merely inconvenient for a copy-paste. Vendored code becomes ours to own — defensible at roughly an hour of ownership per year, but record it as a deliberate fork. The real deliverable is organisational: make the team aware that a CLI OPcache reset does not touch FPM, add the reset to the deploy pipeline as an explicit step, and add the post-deploy verification ("prove the reset reached the serving process") to the runbook so we are not encoding a false sense of safety.