Twig Cache Purger Bundle Laravel Package

Technical Evaluation

What it is. A Symfony bundle that invalidates the compiled cache entry for a single Twig template, instead of nuking the whole Twig cache with cache:clear / cache:pool:clear. Small, single-purpose, MIT.

Architecture fit — the headline finding: this is not a Laravel package. The request frames it as a Laravel/PHP package; it is a Symfony bundle. It ships a DI extension, service definitions, and kernel-time registration. A Laravel application has no bundle/kernel concept to hang that on, and Twig is not even the default engine (Blade). Fit is therefore conditional:

• Fits only where we genuinely run Symfony with Twig on a filesystem-backed Twig cache, and where full-cache clears are expensive — large template sets, multi-tenant/white-label themes, or CMS-editable Twig that changes at runtime.
• Does not fit the Laravel estate at all, including via Twig bridges (rcrowe/twigbridge), because the bundle's registrations still have nowhere to load.

Integration feasibility. Install cost is trivially low: composer require, Flex auto-registers, no schema, no data migration, reversal is composer remove + cache clear. That near-zero cost of reversal is the strongest argument for a short, time-boxed spike rather than a formal evaluation cycle.

Technical risk.

Key questions to answer before commitment.

1. Do we run Symfony/Twig anywhere in the estate, or is this purely a pattern to borrow?
2. What is the supported Symfony × Twig × PHP matrix, and is there CI proving it?
3. Does it use Twig's CacheInterface / LoaderInterface, or hard-coded path assumptions?
4. Does it recompile eagerly, or lazily on next request?
5. What is the programmatic entry point — single-template service, console command, or both?
6. Does it dispatch events we can hook for logging and metrics?
7. How many LOC is it? If small enough to vendor at near-zero cost, abandonment risk is largely neutralized.

Integration Approach

Stack fit. Primary stack is Laravel/Blade. Treat the package as non-installable there. Two legitimate paths:

• Path A — borrow the pattern, not the dependency (recommended). A ~100–150 LOC in-house service that resolves a compiled template path and unlinks it. Blade's compiled-view naming is hash-derived and stable enough to rely on; Twig's is class-name derived. Owning it removes the Symfony coupling, the bus-factor exposure, and the version-matrix dependency in one move.
• Path B — adopt, only if a real Symfony runtime enters the estate (legacy service, acquisition, or a Twig-based theming system).

Migration path (Path B). Single service → composer require → bundle registration → verify against the staging environment with the highest template count. No DB, no schema, no backfill. Rollback is a composer removal plus a cache clear.

Compatibility gates. Symfony LTS, PHP version, Twig major, and the cache adapter question above. The adapter question is make-or-break: if Twig is not filesystem-cached, the entire value proposition is a no-op and the evaluation ends there.

Sequencing.

1. Spike (1–2 days): read the source; confirm invalidation mechanism, version matrix, cache-adapter assumptions.
2. Prove in staging only, in the one environment with meaningful template volume, asserting that the template actually recompiles and renders correctly afterwards.
3. Decide: if a Symfony runtime is real, adopt there. If the value came from the concept — which is the likely outcome — implement the Laravel/Blade equivalent in-house and close the ticket. Do not fork a Symfony bundle for a Laravel app.
4. Never sequence this ahead of roadmap items. It is a DX/ops nicety, not a delivery blocker, and nothing in the estate depends on it.

Operational Impact

Maintenance. MIT, tiny surface area, one vendor. Expect to own it regardless of stars. Budget is near-zero while untouched and unbounded if Twig internals shift. Mitigation: pin versions and keep a one-line CI smoke test that purges a template and asserts recompilation and correct rendering.

Support. No community to lean on — 0 stars, 0 dependents means no downstream bug reports, no ecosystem pressure on compatibility, and effectively "best effort from a small agency" upstream. Assume we are the support tier. Assign a named backend owner; do not let this accrete silently to a platform team that never chose it.

Scaling.

• Purge itself is O(1) and cheap. The cost sits in the recompile that follows: on a hot template, N workers may recompile concurrently on next request. Verify the write is atomic on our filesystem, and consider a post-purge warm-up or staggered purge.
• Multi-node is the operational gotcha. The purge deletes a file on the local filesystem only. In a pod/container fleet, one node is fresh and the rest serve stale templates — the worst class of bug to diagnose. It works in production only with a shared cache directory or an explicit fan-out. Without that, this is honestly a local-development tool wearing a production label.
• It complements, and does not replace, deployment-time cache clearing.

Failure modes to instrument.

• Silent no-op — wrong template name, namespaced/bundle notation (@App/foo.html.twig), or non-filesystem cache. Presents as a rendering bug. Assert post-purge and alert.
• Over-purge — recompile storms and latency spikes. Rate-limit and log.
• Partial purge across nodes — inconsistent output between pods. Add a purge audit log and a "compiled-at" check.
• Container filesystem ownership/permission failures after base-image changes.

Ramp-up. Reading the source is under an hour; the concept is immediately graspable by any PHP engineer. The real ramp-up cost is domain knowledge — how Twig lays out and warms its cache — which the package does not document. Write it down internally once, or the next engineer re-learns it from scratch.

TPM recommendation. Do not adopt as a dependency for the Laravel estate. Log it as a reference implementation for a ~1-day in-house selective template cache purge utility, gated on three prerequisites: filesystem-backed template cache, a shared cache directory (or fan-out) across nodes, and purge observability. Revisit only if a Symfony runtime enters the estate. The 9.64 score is a code-quality signal on a very small artifact; the 47.36 opportunity score and 0 dependents are the decision-relevant numbers.