Twig Cache Purger Bundle Laravel Package

Getting Started

This is a Symfony bundle, so the first thing a Laravel developer needs to do is translate the concept rather than expect drop-in reuse. The package solves one narrow problem: Twig compiles every template into a hashed PHP class in its cache directory, and normally the only way to invalidate that cache is to wipe the whole directory. This bundle exposes a service (and typically a console command) that lets you purge the compiled cache for one named template without touching the rest.

Where to look first:

• src/ for the TwigCachePurger (or similarly named) service — that is the actual API surface you will call.
• The bundle's DependencyInjection/Configuration.php for the config tree (cache directory / pool wiring).
• Any registered console command, usually something like setono:twig-cache-purger:purge <template>.

Minimal Symfony steps:

1. composer require setono/twig-cache-purger-bundle
2. Register Setono\TwigCachePurgerBundle\TwigCachePurgerBundle in config/bundles.php.
3. Ensure Twig is configured with a filesystem cache (twig.cache pointing at a real directory); the purger cannot do anything useful against cache: false.

Laravel reality check: Laravel uses Blade, which compiles to storage/framework/views/*.php, and Laravel only ships php artisan view:clear (all-or-nothing). So the day-to-day value here is conceptual: if you use Twig in Laravel (e.g. via rcrowe/twigbridge), you can adopt the bundle's pattern directly by purging the matching compiled file. If you are on Blade, treat this as a blueprint for a "purge one view" helper you would build yourself.

First use case to aim for: after an admin edits a single CMS template, purge just that template's compiled artifact instead of flushing the entire view cache (which, on a busy app, causes a cold-start recompile storm).

Implementation Patterns

1. Inject the purger and call it from the save path. The cleanest pattern is to autowire the purge service into the controller/service that persists a template edit and call purge($templateName) right after the write. Keep the template name as an explicit, resolvable string (e.g. pages/about.html.twig), not a Symfony logical path (@App/about.html.twig) unless the purger resolves namespaces.

2. Event-driven purge. In Symfony this is an event subscriber on your entity's postUpdate/postPersist; mirror it in Laravel as an Eloquent observer or model event that calls a ViewCachePurger::purge($view) service. This decouples "content changed" from "cache invalidated" and is the pattern most CMS integrations end up with.

3. Deploy-pipeline purge. Wire the bundle's console command into your release script for the handful of templates that change independently of code (email templates, marketing pages, translated stubs). This is safer than cache:clear because it does not evict unrelated Twig/DI caches and avoids a fleet-wide recompile.

4. HTTP/admin hook. Expose a small authenticated endpoint or artisan command (php artisan view:purge {name}) that wraps the same service, so ops or a headless CMS can invalidate a single template without shell access.

5. Multi-tenant isolation. If tenants have their own template directories, prefix template names per tenant (tenant_42/home.twig) and purge by exact name. Do not attempt directory-level purging through this API — it is a single-template tool.

6. Laravel port sketch. Build a ViewPurger that computes the compiled Blade filename (sha1($path).php via the compiler's getCompiledPath) and deletes it. For Twig-in-Laravel, use Twig's Environment::getCache() + the template's class name to locate the file. Wrap it behind a service and an artisan command so call sites match the Symfony bundle's ergonomics.

Gotchas and Tips

• Template name resolution is the #1 failure mode. Twig compiles by the resolved template name; namespaced (@Bundle/...) or dynamically chosen templates may not map cleanly. Log what you pass and verify against the actual filename in the cache directory.
• A shared/remote cache pool breaks assumptions. If Twig's cache is a Redis/memcached pool rather than a filesystem, the purger must talk to the pool, not unlink() files. Confirm which cache adapter your twig.cache uses before trusting the bundle.
• auto_reload/debug masks the problem. In dev, Twig recompiles changed templates automatically, so a broken purge looks fine locally and fails silently in production. Test with APP_DEBUG=0 and a warm cache.
• Load-balanced fleets. Purging one node's filesystem cache does not invalidate siblings. Either use a shared cache backend or fan out the purge via your deploy mechanism. This is the same trap as view:clear on multi-server Laravel setups.
• Warm the cache after purging. Purging one template means the next request pays the compile cost for it; a request-time purge can spike latency. Purge on write/deploy, not on read, and consider a follow-up twig:cache:warmup (or Blade precompile) for high-traffic templates.
• Permissions. The PHP process needs write access to the Twig cache dir; containerized read-only filesystems will make purge appear to succeed while the stale file remains.
• Extension points are thin. This is a single-purpose bundle — expect a service plus a command and little else. If you need conditional or batch logic, wrap it in your own service rather than expecting hooks.
• Maintenance risk. Zero stars and zero dependents on a 2026 release means you are effectively the canary. Pin the version, read the source (it is small), and be ready to inline the ~50 lines it implements if it goes unmaintained. For a Laravel team, the safer long-term bet is usually to build the small purge helper yourself against your own cache abstraction.
• Don't reach for this to solve general cache staleness. It purges compiled templates only — it will not touch application cache, HTTP cache, or view:cache artifacts. Keep it scoped to the "one template changed" workflow.