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()'

tags 

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

Cache tags provide a way to track which cache items depend on certain data. Tags are used for the cache invalidation.

For example tag the cache item with a product id:

layout:
  actions:
    - '@setOption':
        id: <block-id>
        optionName: cache
        optionValue:
          tags:
            - '="product_" ~data["product"].getId()' # For product with id = 14 it's evaluated to `product_14`

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:

  1. 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()'
    
  2. 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()]);
            }
        }
    }
    
  3. 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.