Redis (Full Page Caching)

Overview of Redis

Miva supports Full Page Caching using Redis, an in-memory data store that allows pages to be served quickly without being regenerated on every request.

When a page is cached, Miva stores the fully rendered HTML in Redis. Future requests for that page can be served directly from Redis instead of rebuilding the page through templates and database queries.

Because Redis operates in memory (RAM), cached pages can be delivered extremely quickly, often resulting in Time to First Byte (TTFB) under 200ms.

For more information about Redis visit: https://redis.io/topics/introduction

Benefits of Redis Full Page Caching

Using Redis caching improves both performance and scalability by reducing the need to regenerate pages for each request.

Key benefits include:

• Faster page load times

• Reduced server and database load

• Higher Google Page Speed / Lighthouse Scores

• Better search engine rankings SEO (site speed is a ranking factor)

How Redis Caching Works

When a visitor requests a page, Miva checks Redis for a cached version. If found (a cache hit), the page is returned immediately. If not (a cache miss), the page is generated, stored in the cache, and then returned for future use.

On This Page

• Overview

• Benefits of Redis Full Page Caching

• How Redis Caching Works

• ⚠️ Write_Basket Disables Caching

• Setup and Configuration
• Cache Key
• Cache Settings
• Wildcard Parameter Support
• Page Level Cache Settings
• Template Level Function
• Cache Detection for Component Modules
• X-Miva-Cache Response Header
• XML Provisioning
• Upgrading from the redis_page_cache_module
• Framework Support
• Template Branch Behavior
• Runtime JSON API Caching
• Combination Facets Support
• Integration Checklist

⚠️ Write_Basket Disables Caching

If a page executes a write_basket custom field, Miva will automatically prevent that page from being cached.

This is intentional behavior to avoid storing shopper-specific data in cache.

If write_basket is used globally (for example, in the global HTML profile), it can prevent all pages from being cached.

When this occurs, you will see the following response header:

X-Miva-Cache: off aborted-write-basket

Recommended Solution

If the data being stored is not required server-side, replace write_basket usage with browser-based session storage. This allows pages to be cached while still preserving client-side functionality.

Theme Consideration

Some older Miva themes (such as Shadows and Colossus) use a global write_basket call to store the referring URL. This will prevent Redis caching from working across the site.

To resolve this, update the implementation to use session storage instead:
https://github.com/mivaecommerce/readytheme-shadows/issues/64

Setup and Configuration

Before using Redis Full Page Caching, it must be enabled at the server level.

If you are unsure whether Redis is enabled for your site, c contact support@miva.com.

Note: Redis is only available to customers on dedicated servers (Professional plan and above). It is not available on shared hosting environments.

Connect Your Store to Redis

After Redis has been enabled, connect your store by navigating to:

1. Path: Store Settings → Store Details → Scroll to Cache Configuration

2. Select Redis from the Cache Type dropdown.

Cache Configuration

These settings define how your store connects to and uses Redis for caching.

Note: Selecting Redis as the Cache Type does not enable Redis. It must already be installed and available on your server.

Cache Type - the caching method used by your store. Select Redis to use Redis for full page caching when available.

Redis Index - the Redis database index used for caching. This allows multiple applications to share a Redis instance without overlapping data.

Redis Expiration - how long cached pages are stored before expiring (in seconds).
The default is 300 seconds (5 minutes).

Redis Connection Settings

These settings define how Miva connects to your Redis server.

1. Status - Displays the current connection status:

• Connected – Redis is properly configured and available

• N/A – Redis is not enabled or not configured on the server

If the status shows N/A after selecting Redis, contact Miva support to enable Redis for your server.

2. Redis Host - The hostname or IP address of the Redis server. In most cases: 127.0.0.1

3. Redis Port - The port Redis is running on. Default: 6379

4. Redis Timeout - The time (in milliseconds) Miva waits when attempting to connect before timing out.

5. Redis Password- Optional. Required only if your Redis server uses authentication.

Cache Management

Cache Hits - Number and percentage of requests served from cache.

Cache Misses - Number of requests that required page generation.

Flush Cache - Clears all cached pages from Redis.

This action applies globally and cannot be performed for individual pages.

Clear Cache from the User Interface branch action menu.

Cache Key

Each cached page is identified by a cache key, which is a unique identifier generated from the page request.

A cache key determines whether a cached version of a page can be reused or if a new version needs to be generated.

Miva generates the cache key based on:

• s.http_host (domain)

• s.request_uri (page URL, excluding query string)

• Any input GET or POST variables (such as URL parameters)

• Selected cookies or headers (depending on your Cache Settings)

Because the cache key is based on request data, different values in a request can create different cache keys. This can result in multiple cached versions of the same page.

Example Use Case

Consider an email campaign link where a parameter value changes for each visitor:

https://www.domain.com/shirt.html?mc_cid=7dhs683xh

Because the mc_cid value is unique per visitor, each request generates a different cache key. This prevents the page from being reused from cache, reducing the effectiveness of caching.

This is common with tracking parameters, where values frequently change but do not affect the actual page content.

Cache Settings can be used to ignore these parameters so they do not create unnecessary variations of cached pages. See the Cache Settings documentation for more details.

Cache Settings

Cache Settings allow you to control how request data—such as URL parameters, cookies, and headers, affects cache key generation and caching behavior.

Because cache keys are built from request data, differences in parameters or other values can create multiple cached versions of the same page. Cache Settings provide the ability to control which values should be included, ignored, or used to prevent caching entirely.

Cache Settings are configured under:

Settings → Store Settings → Cache Settings

For full details and configuration examples, see: Cache Settings Documentation

Wildcard Parameter Support

Cache Settings support wildcard matching for Parameter types using a trailing asterisk (*).

Example:

utm_*

This rule matches any parameter that begins with utm_, including:

• utm_source

• utm_campaign

• utm_medium

• utm_term

• utm_content

Tracking parameters like these often change frequently or expand over time. Without wildcard support, each new parameter would need to be added individually to avoid creating unnecessary cache variations.

Using a wildcard allows a single rule to apply to an entire group of related parameters. This helps ensure that new or unexpected parameters do not reduce cache efficiency or create excessive cache entries.

Page Level Cache Settings

In addition to the global cache settings, these settings also exist at the page level. Any value set at the page level will override that set at the global level.

There are also page specific settings which govern how a page is cached related baskets.

There are 5 Options:

• Never Cache This Page
• Cache Only if the Basket is Provisional
• Cache Only if the Basket is Empty and No Customer is logged In
• Always Cache if the Basket is Empty
• Always Cache

The Default of all pages is "Cache Only if the basket is empty and no customer is logged in". This makes it so that its impossible to cache customer specific basket data.

These settings can be change individually at a per page level, or from the batch list:

Template Level Function

There exists a function you can call from any page template TemplateManager_Page_Cache_Disable( reason ), which aborts caching of a page that would otherwise have been cached.

The Write_Basket custom field function automatically calls this new function to prevent any which writes a custom basket field from being cached.

<mvt:do file="g.Module_Feature_TUI_MGR" name="l.null" value="TemplateManager_Page_Cache_Disable( 'good-reason' )" />

Cache Detection for Component Modules

There also exists a new function, TemplateManager_Page_Cached(), which returns 1 when a page is being rendered for caching. This function can be used in component modules so they can alter their behavior, if necessary, when a page is being rendered for the cache.

X-Miva-Cache Response Header

When caching is enabled, a new header named X-Miva-Cache will be output for every page hit.

When a page is cached, the header will output the text "hit" or "miss" and the MD5 component of the cache key.

Example:

X-Miva-Cache: hit 581ffcd33dbcda8cd3dd48b066dc1325

When a page is not cached, the header will output the text "off" and a reason:

X-Miva-Cache: off global-param

X-Miva-Cache: off page-header

X-Miva-Cache: off write-basket

In the event of a page hit that would otherwise be cached being invalidated due to a call to TemplateManager_Page_Cache_Disable, the reason output should be the reason will get displayed in this new header.

This header gives you visibility into why a page was not cached, or if a page was served from the cache.

XML Provisioning

For bulk importing of Cache Settings, there are XML Provisioning tags both at the store level and the page level.

<Store_Update code="test">    <RedisEnabled>Yes</RedisEnabled>    <RedistHost>localhost</RedisHost>    <RedisPort>12345</RedisPort>    <RedisPassword>abracadabra</RedisPassword>    <RedisExpiration>12</RedisExpiration>        <CacheSettings>        <Header name="blah1" mode="key" />        <Header name="blah2" mode="disable" />        <Header name="blah3" mode="disable_substring">wombat</Header>        <Header name="blah4" mode="disable_equal">cache_disabled</Header>                <Parameter name="blah1" mode="key" />    </CacheSettings></Store_Update>

Upgrading from the redis_page_cache_module

Prior to Redis being built into 10.01.00, there was a stand alone module which enabled similar functionality.

As part of the 10.01.00 upgrade process any settings from the redis_page_cache_module, if installed, will get transferred into the new built in Redis Cache Settings, ensuring that the existing behavior is retained. The redis_page_cache_module will then be disabled. Both cannot be used at the same time.

All this happens automatically as part of the upgrade process.

Framework Support

The framework import/export process has also been updated to support saving and applying these new page specific cache settings. This allows developers to create their own frameworks with the Page level cache settings they prefer which will get automatically applied when the framework is applied.

Template Branch Behavior

There is logic built into the Redis Caching to prevent any template branch from ever getting Cached. This makes it so you can safely work in a template branch without having to worry about it accidentally being cached and being served to customers.

You do not need to manually add the template branch cookies to the Cache settings. This happens automatically behind the scenes.

Runtime JSON API Caching

The following Runtime functions leverage redis caching to improve response times:

• Runtime_CategoryList_Load_Query
• Runtime_ProductList_Load_Query
• Runtime_CategoryProductList_Load_Query
• Runtime_RelatedProductList_Load_Query

Since these functions are used by several flex components that are intended for placement on high traffic pages, their performance important. The intention of Redis support is to avoid as many database operations as possible, so cache lookups are performed based on input parameters prior to validation of any values, and even error responses should be cached.

Runtime JSON Cache Key Format

The Redis Key will look like: 
json_<function_name>:<cache_key> 
Where function_name is the lowercase name of the function in question.

Global store-level cache key inclusions are honored, and the following additional function-specific values are included in the cache key:

• Offset
• Count
• Sort
• Filter (reserialized)

For Runtime_CategoryProductList_Load_Query

Category_ID or Category_Code

For Runtime_RelatedProductList_Load_Query

Product_ID or Product_Code

For Runtime_CategoryList_Load_Query

Parent_ID

Hit/Miss Counters

Hits and misses for runtime functions are separately tracked and displayed under the key json_cache_status:<store_id>

Combination Facets Support

The combination facets uses cookies to store the value of the Year, Make Model selected. This makes it so that a single URL may display completely different products based on what was selected. This module has been updated to automatically register any cookies used in the Store Level Cache Settings. This allows pages which use combination facets to still get cached and deliver the correct content.

Integration Checklist

Below is a list of things to check when implementing Redis Caching. Server-sided logic that shows/hides content to users based on the any of the following criteria should be looked at prior to caching being enabled.

Write_Basket Custom Field
Ensure write_basket is not used on pages intended to be cached. Global usage (such as in the HTML profile) will prevent caching across the site.

See Write_Basket Disables Caching above for details and recommended solutions.

1. Client Dimensions - If your site uses Client Dimensions, the cookies should be added to the Cache Settings
2. Cookies - Common uses cases include: GDRP Cookie Agreement, Recently Viewed Products, Continue Shopping URLs
3. User Agent - Common uses cases include: Checking for mobile, tablet, or desktop devices and showing them different content, Showing/hiding things for Googlebot or other search engines.
4. IP Address - Common uses cases include: Showing/hiding features based on client IP Address, Testing development features based on IP address, s.remote_addr
5. Custom Headers - Common uses cases include: Template Code referencing system variables beginning with s.http_xxxx such as s.http_access_token, s.http_accept, s.http_host, miva_output_header
6. OAuth Module - If using the OAuth module to allow for login with facebook,google,amazon,twitter the following pages should be excluded from the cache: google-redirect,amazon-redirect,facebook-redirect,oauth
7. Including Session IDs in Links - You want to verify the template code is not using any session specific variables so sessions don't get cached in links. Examples include:
   • session_id
   • sessionurl
   • secure_sessionurl
   • sessionurl_nosep
   • secure_sessionurl_nosep
   • customer_session_id
   • checkout_session_id
8. Setting Cookies - Examples include:
   • request_cookies
   • SetCookie
   • OutputCookies