Layout Cache Laravel Package

Getting Started

This is not a Laravel package — it is a Symfony bundle (OroLayoutCacheBundle) that ships as part of the OroCommerce platform. There is no service provider, no config/layout_cache.php, and no facade. If you are coming from Laravel, treat it as "a package whose service provider is registered via Symfony's kernel" and read the rest with that mental model.

Minimal steps:

1. Confirm you actually need to install it. In an existing OroCommerce application, check whether the bundle is already vendored:

   composer why oro/layout-cache
   ls vendor/oro | grep -i cache
   

   In most Oro 4.x+ applications this functionality was folded into oro/commerce / oro/platform. The standalone repo has had no release since 2020-09-11, so installing it fresh into a modern Oro app is likely to conflict rather than help.
2. If you do install it, register the bundle the Symfony way:

   // config/bundles.php
   Oro\Bundle\LayoutCacheBundle\OroLayoutCacheBundle::class => ['all' => true],
   

   (Older Oro installs used app/AppKernel.php and registerBundles().)
3. Read these files first, in this order:
   • DependencyInjection/Configuration.php and OroLayoutCacheExtension.php — tells you the real config tree (anything below is the shape, not the exact keys).
   • Resources/config/oro/*.yml — cache pools, listeners, and any layout option extensions.
   • Cache/ or Layout/ — the actual cache-writer/reader decorators around LayoutManager.
4. First use case: enable render caching on a heavy storefront block (product listing, category menu, mini-cart) so repeated layout renders for the same context are served from cache instead of re-executing block types and DB queries.

Implementation Patterns

Declarative (layout YAML) caching. The idiomatic way to use this is not from PHP. You annotate a block or layout in layout.yml / layout_updates.yml with cache options and the bundle's listeners/decorators pick it up during rendering:

# Resources/views/layouts/<theme>/layout.yml (illustrative — verify key names
# against the bundle's Configuration.php, they changed across Oro versions)
layout:
    actions:
        - '@setBlockTheme':
            themes: 'product_listing.html.twig'
        - '@add':
            id: featured_products
            parentId: page_content
            blockType: product_listing
            options:
                cache:
                    enabled: true
                    lifetime: 3600

Programmatic caching of a rendered layout. When you need to bypass the declarative layer (e.g. a custom controller or a console command that renders layouts), resolve the decorated layout manager from the container and include context in whatever key you build:

$layout = $this->container->get('oro_layout.layout_manager')
    ->getLayout($context->get('theme'), $context->get('route_name'));

The bundle wraps this so that identical LayoutContext values hit the cache — which makes context completeness the single most important design decision (see Gotchas).

Cache pools and backing store. Route the layout cache to a dedicated Symfony cache pool rather than the default filesystem pool. In Oro's config.yml:

framework:
    cache:
        pools:
            oro_layout.cache:
                adapter: cache.adapter.redis
                default_lifetime: 3600
                tags: true   # layout invalidation relies on tag-based clearing

Redis (or another tag-capable adapter) is effectively required — tag invalidation silently degrades to full clears on cache.adapter.filesystem.

Invalidation via tags. The bundle tags entries per layout/theme/site. Anything that mutates a layout — a layout.yml edit, a theme activation, a content block update — fires an Oro cache listener that clears the matching tags. Your job is to keep writes going through Oro's APIs (layout manager, theme manager) so those listeners fire. Direct UPDATE statements on oro_layout tables will not invalidate the cache.

Warmup and CLI. Treat layout cache like any other Oro cache pool:

bin/console cache:clear --env=prod
bin/console oro:cache:warmup --env=prod
bin/console cache:pool:clear oro_layout.cache

Wire oro:cache:warmup into your deploy script — a cold layout cache on a large B2B catalog is painful on the first request.

Testing. In config_test.yml, point the pool at cache.adapter.array (or null) so assertions don't run against stale rendering. Functional tests should also call the layout cache clearer in setUp() if they touch layout fixtures.

Gotchas and Tips

• Laravel→Symfony conceptual mapping. Service provider → bundle class + DI extension; config/*.php → DependencyInjection/Configuration.php (a TreeBuilder); Cache::tags() → Symfony cache contracts with the TagAwareAdapterInterface; Artisan → bin/console commands. None of Laravel's helpers (cache(), config(), facades) exist here.
• Context completeness is the #1 source of production bugs. A layout rendered for one customer group, website, localization, or currency will be wrong for another if the cache key doesn't include it. When extending the bundle, always fold the full LayoutContext (or its relevant subset) into the key — never just theme + route.
• It may already be inside the platform. With zero dependents and a 2020 final release, this repo reads as archived/absorbed. Before writing any integration code, grep the Oro core vendor/oro/commerce for LayoutCache — you may be reimplementing what's already there.
• Debugging stale renders starts with three moves: (1) set the pool to array and see if the problem disappears; (2) bin/console cache:pool:clear oro_layout.cache; (3) debug:container | grep layout to confirm which decorator is actually wrapping oro_layout.layout_manager. If a third-party bundle decorates the same service, decoration priority can silently defeat the cache.
• NOASSERTION license. The repo does not declare a recognized SPDX identifier. Read LICENSE (Oro's standard is OSL-3.0, which is copyleft-flavored and not MIT). Do not assume permissive before shipping to a client.
• PHP/Symfony version drift. A 2020-era bundle targets PHP 7.x and Symfony 4.x. On Symfony 5.4+/PHP 8.1 you will likely hit ReturnTypeWillChange and signature deprecations in the DI extension; expect to patch or (better) upgrade the Oro platform instead.
• Caching bloats Redis fast on large catalogs. Use a bounded default_lifetime rather than infinite, and size the Redis instance / eviction policy accordingly — an evicted layout cache behaves like a cold cache, so LRU eviction under memory pressure can cause periodic latency cliffs.
• Extension points to reach for: decorate oro_layout.layout_manager, add a layout option via Oro\Bundle\LayoutBundle\DependencyInjection\Compiler\LayoutBlockTypePass-style compiler passes, or implement a cache-warming CacheWarmerInterface. Prefer these over touching vendor code — Oro upgrades regularly break patched vendors.