Architecture

A quick reference of what’s inside the plugin, useful for theme developers, plugin authors and anyone diagnosing unexpected behaviour.

Top-level packages

P2Lab\Cache\
├── Api/              REST controllers (admin endpoints)
├── Command/          Symfony console commands
├── Decorator/        Decorators around Shopware core services
├── DependencyInjection/
├── Entity/           DAL definitions for the plugin's own tables
├── Enum/             Mode / strategy constants
├── Factory/          Cache-adapter factory
├── Framework/        Cache store implementation
├── Helper/
├── Message/          Async messages dispatched by the plugin
├── MessageHandler/   Handlers for those messages
├── Migration/        Database migrations
├── P2LabCache.php    Plugin entry point (lifecycle)
├── Resources/
├── ScheduledTask/    Three nightly cleanup tasks (+ handlers)
├── Service/          Domain services (the bulk of the logic)
├── Storefront/
├── Subscriber/       Event subscribers that wire into Shopware
└── ValueObject/

Key services

Service	What it does
`CacheEntryService`	Reads / writes the `p2lab_cache_entry` metadata table
`CacheInvalidationService`	Top-level invalidation API — `clearAll()`, `clearAllProducts()`, etc.
`CacheWarmupService`	Discovers cacheable URLs, creates progress entries, batches them
`CacheSizeService`	Reports total cache size (disk for Filesystem; database for Redis / APCu)
`SmartInvalidationAnalyzer`	Field-to-tag mapping for Smart invalidation mode
`CacheInvalidationLogService`	Persists rows in `p2lab_cache_invalidation_log`
`ReverseProxyLogService`	Persists rows in `p2lab_cache_reverse_proxy_log`, plus analytics queries
`CacheTagService`	Builds the tag set for a given response
`TagParserService`	Parses tag names back into entity references for the log views
`RequestService`	Inspects requests to decide cacheability and compute the cache key
`SettingsService`	Reads `system_config` values with per-sales-channel fallback

Decorators

Decorates	Purpose
`SalesChannelContextFactory`	Cached sales-channel context for warmup workers
`ReverseProxyGateway`	Adds xkey strategy + blocklist + splitting / shortening before sending purges to Varnish

Subscribers

Subscriber	Listens to	What it does
`CacheEntryFlushSubscriber`	`KernelEvents::TERMINATE`	Persists newly-written entries’ metadata after the response is sent
`CacheInvalidationSubscriber`	Entity-written events	Triggers the invalidation pipeline (Manual / Basic / Extended / Precise / Smart)
`CacheResponseSubscriber`	`KernelEvents::RESPONSE`	Stores the response in the backend if cacheable; sets `Cache-Control` headers
`NotificationMessageSubscriber`	Custom plugin events	Pushes admin notifications (warmup completion etc.)
`TagCollectionSubscriber`	Entity-loaded events	Collects the tag set that a response should carry
`XkeySubscriber`	Pre-purge event	Applies blocklist, splitting and shortening to outgoing xkey headers

Async messages

Message	Handler	Purpose
`CacheWarmupStartMessage`	`CacheWarmupStartHandler`	Kicks off a warmup run; spawns batch messages
`CacheWarmupBatchMessage`	`CacheWarmupBatchHandler`	Processes one batch of URLs

Scheduled tasks

Task	Default interval	What it does
`p2lab_cache.cleanup_cache_entries`	24 h	Drops orphaned `p2lab_cache_entry` rows
`p2lab_cache.cleanup_invalidation_log`	24 h	Drops invalidation-log rows older than 30 days
`p2lab_cache.cleanup_reverse_proxy_log`	24 h	Drops reverse-proxy-log rows older than 30 days

See Scheduled tasks.

Database tables

Table	Purpose
`p2lab_cache_entry`	Metadata for every cache entry (size, type, generation / hit time)
`p2lab_cache_invalidation_log`	Every invalidation event
`p2lab_cache_reverse_proxy_log`	Every xkey purge sent to Varnish
`p2lab_cache_warmup_progress`	One row per warmup run; tracks offset and counters
`p2lab_cache_warmup_failed_url`	URLs that failed during a warmup

Tag naming conventions

Cache tags created by the plugin all start with p2c-. The conventions:

p2c-product-<id> — full product tag (any field change purges)
p2c-product-<id>.<field> — Smart-mode field-level tag (e.g. .price, .stock)
p2c-product-stock_<id> — stock-only tag, exposed separately so the product_stock blocklist category can isolate it
p2c-category-<id> — full category tag
p2c-listing-<categoryId> — listing tag (purged when a member product’s listing-affecting field changes)
p2c-cms-page-<id> — CMS page tag
p2c-buybox-<productId> — async buybox tag

These tags are sent to Varnish via xkey and also drive the local invalidation lookup.

Extending the plugin

Add a new cache type: subscribe to KernelEvents::RESPONSE, set the type via the response object, and add a tag prefix. Update getCacheStatsByType() to know about it.
Add a field to Smart’s mapping: decorate SmartInvalidationAnalyzer and override analyzeProductChange() or analyzeCategoryChange().
Add an xkey blocklist category: extend the xkeyTagBlocklist config + add the matching pattern in XkeySubscriber.