Important

You are browsing documentation for version 5.1 of OroCommerce, supported until March 2026. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

OroCommerce Render Caching

One of the ways to significantly improve website performance is to enable caching. With a few layout-block options, you can enable cache for specific layout blocks permanently or for a particular time and invalidate it with the cache tags from a regular Symfony service when needed. Provided mechanism also supports complex caching strategies using the custom cache metadata provider PHP class.

Cache Layout Blocks

To cache a block in the layout tree, you have to provide cache metadata with the cache block option.

Note

Layout block cache does not support blocks that were rendered using iteration over data, because it relies on a block id that is reused multiple times when iteration over data is used.

Enable the Cache

To enable the layout block cache, provide the cache block option.

cache: true means the block is cached forever

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue: true

Disable the Cache

By default, the cache is disabled for all the blocks. You can also disable the cache enabled by another layout update.

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue: null

Configuration Reference

maxAge

type: `integer` optional, default: null

Indicates how long the block can be cached. To make the block always return the fresh content, you can set maxAge to 0 (it is used for post-cache substitution).

For example, store the cache item for 10 minutes:

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue:
          maxAge: 600

varyBy

type: `array of scalar items` optional, default: []

Defines the items that the block cache varies by (e.g., product id, whether the user is logged in or not).

For example, vary the cache item by a product id:

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue:
          varyBy:
            product: '=data["product"].getId()'

if

type: `boolean` optional, default: true

Indicates when the cache must be enabled.

For example, enable the cache only for not logged in users:

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue:
          if: '=!context["is_logged_in"]'

Note

All the options can apply layout expressions and must be evaluated to scalar values. Also, layout expressions for the cache option must not depend on other block options.

Layout Update Example

Cache the layout block with the product_view_container id for anonymous users for 10 minutes. The cache varies for different products and is tagged with the product_ID tag:

src/Acme/Bundle/DemoBundle/Resources/views/layouts/default/oro_product_frontend_product_view/cache_product_view.yml

layout:
  actions:
    - '@setOption':
        id: product_view_container
        optionName: cache
        optionValue:
          maxAge: 600                                  # Cache the block for 600 seconds (10 minutes)
          if: '=!context["is_logged_in"]'               # Enable cache only when user is not logged in
          varyBy:
            product: '=data["product"].getId()'        # Cache varies per product
          tags:
            - '="product_" ~data["product"].getId()'   # Tag is used to invalidate the cache
                                                       # when required, by calling the `invalidateTags()` method
                                                       # on the `@cache.oro_layout.render` service

Note

You can use layout update conditions to set cache options depending on the context. For example:

layout:
  actions:
    # ...
  conditions: 'context["is_logged_in"]'

Post-Cache Substitution

Post-cache substitution allows you to cache a block but substitute sub-block content dynamically, or cache a sub-block with different settings.

For example:

Cache the whole product_view_container block forever, but render the product_price_container block dynamically:

src/Acme/Bundle/DemoBundle/Resources/views/layouts/default/oro_product_frontend_product_view/cache_product_view.yml

layout:
  actions:
    - '@setOption':
        id: product_view_container
        optionName: cache
        optionValue:
          varyBy:
            product: '=data["product"].getId()'
    - '@setOption':
        id: product_price_container
        optionName: cache
        optionValue:
            varyBy:
              product: '=data["product"].getId()'
            maxAge: 0 # force disable the cache for a child block

Cache the whole product_view_container block for 1 day, but the product_price_container block only for 15 minutes:

src/Acme/Bundle/DemoBundle/Resources/views/layouts/default/oro_product_frontend_product_view/cache_product_view.yml

layout:
  actions:
    - '@setOption':
        id: product_view_container
        optionName: cache
        optionValue:
          varyBy:
            product: '=data["product"].getId()'
            maxAge: 86400 # 1 day in seconds
    - '@setOption':
        id: product_price_container
        optionName: cache
        optionValue:
            varyBy:
              product: '=data["product"].getId()'
            maxAge: 900 # cache a child block only for 15 minutes

Cache Block Visibility

For security reasons, block visibility is not cached. If you do not want to calculate block visibility every time, override it to the static value with the layout update or cache a wrapping container instead.

layout:
  actions:
    - '@setOption':
        id: product_view_container
        optionName: visible
        optionValue: true
  conditions: 'context["is_logged_in"]'

Make Cache Items Always Vary By Some Data

Out of the box, all cache items vary by localization, theme, and website.

To add additional data to all varyBy cache items, create a service that implements the Oro\Bundle\LayoutCacheBundle\Cache\Extension\RenderCacheExtensionInterface interface and mark it with the layout_cache.extension DI tag.

For example, vary all the cache items by a day of the week:

src/Acme/Bundle/DemoBundle/Cache/Extension/DayOfWeekExtension.php

namespace Acme\Bundle\DemoBundle\Cache\Extension;

use Oro\Bundle\LayoutCacheBundle\Cache\Extension\RenderCacheExtensionInterface;

class DayOfWeekExtension implements RenderCacheExtensionInterface
{
    public function alwaysVaryBy(): array
    {
        return ['day_of_week' => date('l')];
    }
}

src/Acme/Bundle/DemoBundle/Resources/config/services.yml

services:
  Acme\Bundle\DemoBundle\Cache\Extension\DayOfWeekExtension:
    tags: [layout_cache.extension]

Cache Layout Blocks with PHP

Sometimes, layout updates are not flexible enough to cover all the cases with the block caching. In this case, you can create a custom metadata provider service that implements the Oro\Bundle\LayoutCacheBundle\Cache\Metadata\CacheMetadataProviderInterface interface and mark it with the layout_cache.metadata_provider DI tag.

For example, disable the cache for all the blocks if the user is logged in:

src/Acme/Bundle/DemoBundle/Cache/Metadata/DisableCacheForLoggedInUsersCacheMetadataProvider.php

namespace Acme\Bundle\DemoBundle\Cache\Cache\Metadata;

use Oro\Bundle\LayoutCacheBundle\Cache\Metadata\CacheMetadataProviderInterface;
use Oro\Bundle\LayoutCacheBundle\Cache\Metadata\LayoutCacheMetadata;
use Oro\Component\Layout\BlockView;
use Oro\Component\Layout\ContextInterface;

class DisableCacheForLoggedInUsersCacheMetadataProvider implements CacheMetadataProviderInterface
{
    public function getCacheMetadata(BlockView $blockView, ContextInterface $context): ?LayoutCacheMetadata
    {
        if (!$context->get('is_logged_in')) {
            # Do nothing if the user is not logged in
            return null;
        }

        # Return cache metadata with max age equal to 0, if the user is logged in
        return (new LayoutCacheMetadata())->setMaxAge(0);
    }
}

src/Acme/Bundle/DemoBundle/Resources/config/services.yml

services:
  Acme\Bundle\DemoBundle\Cache\Cache\Metadata\DisableCacheForLoggedInUsersCacheMetadataProvider:
    tags: [layout_cache.metadata_provider]

Invalidating Cache by Tags

To invalidate tagged cache items, you have to call the invalidateTags() method of the @cache.oro_layout.render service.

For example, let’s invalidate a cache for a block that depends on a specific product information when product has been updated:

Tag the block that renders product information

src/Acme/Bundle/DemoBundle/Resources/views/layouts/default/oro_product_frontend_product_view/cache_product_view.yml

layout:
  actions:
    - '@setOption':
        id: product_view_container
        optionName: cache
        optionValue:
          tags:
            - '="product_" ~data["product"].getId()'

Create an event listener that will call the invalidateTags() method on post update event:

src/Acme/Bundle/DemoBundle/EventListener/ProductUpdateListener.php

namespace Acme\Bundle\DemoBundle\EventListener;

use Doctrine\ORM\Event\LifecycleEventArgs;
use Oro\Bundle\ProductBundle\Entity\Product;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;
use Symfony\Contracts\Cache\TagAwareCacheInterface;

class ProductUpdateListener
{
    private TagAwareAdapterInterface $cache;

    public function __construct(TagAwareAdapterInterface $cache)
    {
        $this->cache = $cache;
    }

    public function postUpdate(LifecycleEventArgs $args)
    {
        $entity = $args->getEntity();
        if ($entity instanceof Product) {
            $this->cache->invalidateTags(['product_'.$entity->getId()]);
        }
    }
}

Register the listener in a service container:

src/Acme/Bundle/DemoBundle/Resources/config/services.yml

services:
  Oro\Bundle\LayoutCacheBundle\EventListener\ProductUpdateListener:
    arguments:
      - '@cache.oro_layout.render'
    tags:
      - { name: doctrine.event_listener, event: postUpdate }

Configure the Cache Storage

You can use filesystem or Redis as a cache storage. By default, render cache uses filesystem cache storage.

When using Redis, it is recommended to use a separate server for the render cache. To configure it, define the ORO_REDIS_LAYOUT_DSN environment variable

ORO_REDIS_LAYOUT_DSN=redis://localhost/5

Keep in mind that Redis configuration is not compatible with the filesystem cache storage. To enable filesystem storage back, remove the above mentioned configuration.

Clear the Render Cache

To clear the render cache, run the command below:

php bin/console cache:pool:clear cache.oro_layout.render

Note

It is recommended to clear the render cache after any cache-related changes.