Insightful stories that revolve around technology, culture, and design

Drupal’s default caching is robust, but if you’re building a site that needs to scale, think global e-commerce or high-traffic news, you’ll need to go beyond the basics. Imagine a global online retailer handling millions of visits per day. By layering caches, using targeted invalidation, and preventing cache stampedes, they can see a server load drop by 85% and response times can improve by 92%.

Ready to learn how? Let’s break down these advanced techniques and see how you can apply them to your own Drupal projects.

Chained Cache backends

Layered Caching for speed and resilience

Think of caching like a library: the most popular books are on the front shelf (memory), less popular ones are in the stacks (APCu), and the rarest are in the basement (database). Chained cache backends mimic these data flows through multiple layers, so you get speed and resilience.

Note: Drupal core doesn’t provide a built-in chained cache backend. The following is a conceptual example of how you could implement this pattern as a custom service. For more on cache backends, see the Cache Backend API docs.
‍

use Drupal\Core\Cache\CacheBackendInterface;

class ChainedCacheBackend implements CacheBackendInterface {
  protected $backends = [];

  public function __construct(array $backends) {
    $this->backends = $backends;
  }

  public function get($cid, $allow_invalid = FALSE) {
    foreach ($this->backends as $i => $backend) {
      $cached = $backend->get($cid, $allow_invalid);
      if ($cached) {
        // Populate only the faster layers above this one.
        for ($j = 0; $j < $i; $j++) {
          $this->backends[$j]->set($cid, $cached->data, $cached->expire, $cached->tags ?? []);
        }
        return $cached;
      }
    }
    return FALSE;
  }

  // Implement other required methods: set(), delete(), invalidate(), etc.
}

‍

Real-world use case: E-commerce product catalogue

A store with 100,000 products can use this approach:

• Memory Cache: For top-selling products.
• APCu: For mid-tier products.
• Database: For rarely accessed items.

When a user requests a product:

1. Check memory cache.
2. If not found, check APCu.
3. If still not found, check the database and populate the faster caches for next time.

This keeps frequent visitors happy with lightning-fast responses, while new queries are handled efficiently.

Isolated Cache bins

Preventing Cache interference

Imagine two chefs sharing a pantry: one cooks Thai, the other Italian. If they don’t separate their ingredients, chaos ensues! The same goes for caches-unrelated data should live in separate bins to prevent accidental overwrites.

In Drupal, you usually isolate cache bins by configuring them in settings.php or via service overrides-not by prefixing cache IDS in code.

Configuration example in settings.php
‍

$settings['cache']['bins']['product_search'] = 'cache.backend.redis';
$settings['cache']['bins']['user_profile'] = 'cache.backend.memory';

‍

Why it matters

A news site might use cache.bin.product_search for search results and cache.bin.user_profile for user data. This way, a search cache clear won’t accidentally wipe out user sessions.

Intelligent Cache invalidation

Beyond Simple tag clearing

Invalidation isn’t just about clearing old data-it’s about knowing what to clear and when. For example, if a content editor updates a product, you want to invalidate not just that product’s cache, but also related categories and recommendations.

Learn more: Cache Tags

Example: smart invalidation with Cache tags
‍

class SmartCacheInvalidator {
  public function invalidateRelatedContent($entity) {
    $tags = [
      'entity:' . $entity->getEntityTypeId(),
      'entity_bundle:' . $entity->bundle(),
      'entity_list',
    ];

    \Drupal::cache()->invalidateTags($tags);
    $this->triggerCustomInvalidation($entity);
  }

  protected function triggerCustomInvalidation($entity) {
    if ($entity->hasField('related_content')) {
      $related_items = $entity->get('related_content')->referencedEntities();
      foreach ($related_items as $related_item) {
        \Drupal::cache()->invalidateTags([
          'entity:' . $related_item->getEntityTypeId() . ':' . $related_item->id(),
        ]);
      }
    }
  }
}

‍

Real-world use case: news aggregation

When an article is updated:

1. The article’s cache clears (node:123).
2. Its category listing refreshes (content_type:article).
3. Related articles are invalidated (node:related_456).

This ensures updates propagate instantly-without over-clearing other content.

Cache stampede prevention

Avoiding the rush

A cache stampede is like hundreds of people rushing to rebuild a lost sandcastle at once-total chaos! In Drupal, the Lock API helps by letting only one request rebuild the cache, while others wait.

Example: Using the Lock API
‍

use Drupal\Core\Cache\CacheBackendInterface;

class CacheStampedePreventor {
  public function getCachedData($cache_id, callable $callback, array $options = []) {
    $lock_id = "cache_rebuild:{$cache_id}";

    $cached = \Drupal::cache()->get($cache_id);
    if ($cached) {
      return $cached->data;
    }

    $lock = \Drupal::lock();
    if ($lock->acquire($lock_id)) {
      try {
        $data = $callback();
        \Drupal::cache()->set(
          $cache_id,
          $data,
          CacheBackendInterface::CACHE_PERMANENT,
          $options['tags'] ?? []
        );
        $lock->release($lock_id);
        return $data;
      } catch (\Exception $e) {
        $lock->release($lock_id);
        throw $e;
      }
    } else {
      // Wait for the other process to finish rebuilding.
      if (method_exists($lock, 'wait')) {
        $lock->wait($lock_id);
      } else {
        // Fallback: sleep briefly before retrying.
        sleep(1);
      }
      $cached = \Drupal::cache()->get($cache_id);
      return $cached ? $cached->data : null;
    }
  }
}

‍

Note: The wait() method is available in most lock backends in Drupal 9/10, but always check your environment.

Real-world use case: flash sale page

During a flash sale, thousands hit the same product page. The first request rebuilds the cache; everyone else waits for their turn, no server meltdown!

Dynamic Cache contexts

Adapting to complex scenarios

Cache contexts tell Drupal when to vary the cache (e.g., by user role or language). But what if you need to vary by device type, or a combination of factors? That’s where custom cache contexts shine.

Learn more: Cache Contexts

Example: custom Cache context
‍

use Drupal\Core\Cache\CacheContextInterface;

class DynamicCacheContext implements CacheContextInterface {
  public function getContext() {
    $current_user = \Drupal::currentUser();
    return md5(serialize([
      'user_roles' => $current_user->getRoles(),
      'device_type' => $this->getDeviceType(),
    ]));
  }

  protected function getDeviceType() {
    $user_agent = \Drupal::request()->headers->get('User-Agent');
    return preg_match('/mobile/i', $user_agent) ? 'mobile' : 'desktop';
  }

  public static function getLabel() {
    return t('User roles and device type');
  }
}

‍

Real-world use case: responsive web app

A news app serves different layouts to mobile and desktop users. With a dynamic context:

• Mobile users get a lightweight version.
• Desktop users see a full-featured layout.
• Both caches stay independent and efficient.

Performance monitoring

Tracking what matters

Monitoring isn’t just about pretty graphs-it’s about actionable insights. You want to know:

• Which caches are hit most often?
• Which takes the longest to regenerate?
• Where are the bottlenecks?

Learn more: Logger API

Example: Tracking Cache performance
‍

class CachePerformanceTracker {
  public function trackCachePerformance(callable $callback) {
    $start_time = microtime(true);
    $memory_before = memory_get_usage();

    $result = $callback();

    $execution_time = microtime(true) - $start_time;
    \Drupal::logger('cache_performance')->info(
      'Execution Time: @time ms, Memory Used: @memory KB',
      [
        '@time' => round($execution_time * 1000, 2),
        '@memory' => round((memory_get_usage() - $memory_before) / 1024, 2),
      ]
    );

    return $result;
  }
}

‍

Real-world use case: analytics dashboard

A dashboard tracks:

• Cache hit rate by bin
• Average regeneration time
• Invalidations per hour

This helps engineers quickly spot and fix bottlenecks-like a slow block dragging down the homepage.

Implementation strategies

Putting it all together

1. Layered Caching architecture
Use chained backends for critical paths (e.g., product pages), and isolated bins for unrelated systems (e.g., user sessions vs. search results).

2. Contextual Caching
Be specific: avoid broad contexts like url; use url.path or custom contexts for business logic.

3. Granular Invalidation
Target specific entities (node:123) instead of broad tags (content_type:article).

4. Stampede Protection
Apply cache locks to high-traffic pages with frequent updates (e.g., stock tickers, live scores).

5. Continuous Monitoring
Log cache performance and set up alerts for anomalies (like a sudden drop in hit rate).

Series navigation

This article is part of our comprehensive 10-part series on Drupal caching:

1. Introduction to Drupal Caching
2. Understanding Drupal’s Cache API
3. Choosing the Right Cache Backend for Your Drupal Site
4. Mastering Page and Block Caching in Drupal
5. Optimising Drupal Views and Forms with Caching
6. Entity and Render Caching for Drupal Performance
7. Building Custom Caching Services in Drupal
8. Implementing Custom Cache Bins for Specialised Needs
9. Advanced Drupal Cache Techniques (You are here)‍
10. Drupal Caching Best Practices and Performance Monitoring (Coming soon)

What’s next?

Advanced caching techniques help Drupal sites stay responsive under pressure and efficient at scale. By layering cache backends, isolating bins, using precise invalidation, and adapting to context, you create a caching system that mirrors how real users interact with your site.

These methods work best when applied as part of a clear strategy. Each layer supports faster access. Each boundary between cache bins keeps systems focused. Context-aware caching and stampede prevention protect performance without adding complexity. And monitoring ensures every choice is informed by real data.

Together, they form a foundation for stability and long-term maintainability.

In our final blog, we’ll tie everything together with Drupal caching best practices. You’ll learn how to:

• Design caching strategies for long-term maintainability
• Monitor and optimise caching in production
• Troubleshoot common caching pitfalls

Stay tuned for the final chapter in our caching journey!

‍

‍

‍

Drupal’s default cache bins-such as cache. render and cache. Entities are designed for generalised use cases. 

However, complex applications often require specialised caching strategies that transcend these built-in systems. 

Imagine a scientific research platform that processes large datasets for computational models. 

Default caching might reduce database queries, but it fails to address the computational overhead of recalculating results. In such cases, custom cache bins become essential to balance performance with precision.

Limitations of default Cache bins

Default cache bins are optimised for simplicity, but they struggle with niche requirements:

1. Shared storage: All cached data shares the same backend, risking interference (e.g., a heavy computation overwriting frequently accessed data).
2. One-size-fits-all expiration: Default bins use universal rules for cache invalidation, which may not align with domain-specific needs (e.g., invalidating a weather API cache every hour vs. a financial report cache every day).
3. Backend constraints: Default bins often rely on the database (cache.backend.database), which may not suit high-throughput scenarios (e.g., real-time analytics requiring Redis).

When custom Cache bins add value

Custom bins shine in scenarios where default bins fall short:

• High-volume, low-change data: Scientific computations or machine learning predictions that take seconds to generate but change infrequently.
• Specialised backends: Applications requiring Redis for speed or file-based storage for large binary objects.
• Granular invalidation: Systems needing precise cache clearing (e.g., refreshing only weather forecasts for a specific region).

Tip: Avoid custom bins for rapidly changing data (like live chat messages) or sensitive information (such as user-specific financial records), where default mechanisms or no caching may be safer.

Understanding Cache bins

What are Cache bins?

Think of cache bins as labelled storage boxes in a warehouse. Each box holds a different type of item, and you can choose where to store each box for maximum efficiency. In Drupal, cache bins:

• Separate Cached content: Prevent interference between unrelated data (e.g., page content vs. API responses).
• Allow custom backends: Use different storage systems (e.g., Redis for fast access, database for persistence).
• Support unique policies: Define rules like expiration times, invalidation strategies, and access controls.

Default Drupal Cache bins

Drupal ships with predefined bins for common use cases:

• cache.default: Generic storage for arbitrary data.
• cache.render: Stores rendered HTML fragments.
• cache.entity: Caches raw entity data.
• cache.bootstrap: Critical data needed during early bootstrapping.

While these bins handle most scenarios, they lack flexibility for specialised needs.

Why create custom Cache bins?

Advantages of specialised storage

1. Isolation: Prevent cache interference between unrelated systems (e.g., a weather API cache won’t evict a machine learning model cache).
2. Tailored backends: Use Redis for low-latency access or file storage for large binary objects.
3. Fine-grained control: Define custom expiration rules (e.g., “cache weather data for 15 minutes”) and invalidation logic.

Real-world scenarios

• Scientific computation results: A research platform caches complex simulations for 24 hours, invalidating them only when input parameters change.
• Machine learning predictions: Store model outputs in a Redis-backed bin to reduce redundant calculations.
• Geospatial data: Cache map tiles in a file-based bin to offload database pressure.

Cache bin architecture

Core components

A custom cache bin relies on four foundational elements:

1. Cache backend: Defines where data is stored (e.g., database, Redis, file system).
2. Cache tags: Determine what triggers cache invalidation (e.g., scientific_computation, ml_model:42).
3. Metadata management: Includes rules like max-age and dependencies (tags, contexts).
4. Isolation mechanism: Enforced through unique service definitions and backend configurations.

Dependency injection: why it matters

Drupal’s service container allows cache logic to be decoupled from business logic. By injecting dependencies like CacheBackendInterface, services become:

• Testable: Easily mocked in unit tests.
• Flexible: Replace backends (e.g., switching from database to Redis) without rewriting logic.

Example:
‍

use Drupal\Core\Cache\CacheBackendInterface;

class SpecializedCacheBin implements CacheBackendInterface {
  protected $cacheBin;

  public function __construct(CacheBackendInterface $cache_bin) {
    $this->cacheBin = $cache_bin;
  }

  public function get($cid, $allow_invalid = FALSE) {
    return $this->cacheBin->get($cid, $allow_invalid);
  }

  // Implement all other required CacheBackendInterface methods...
}

‍

Official Documentation: Service Container

Step-by-step: creating a custom Cache bin

1. Register the service

Define the bin in your module’s mymodule.services.yml:
‍

services:
  cache.specialized_bin:
    class: Drupal\mymodule\Cache\SpecializedCacheBin
    arguments: ['@cache_factory']
    tags:
      - { name: cache.bin }

‍

Note: The cache backend (e.g., Redis, database) is configured in settings.php, not in the service definition.

2. Configure the backend in settings.php
‍

$settings['cache']['bins']['specialized_bin'] = 'cache.backend.redis'; // or 'cache.backend.database'

‍

3. Implement the Cache bin class

Here’s an example for a scientific computation cache:
‍

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Cache\CacheFactoryInterface;

class ScientificComputationCache implements CacheBackendInterface {
  protected $cacheBin;

  public function __construct(CacheFactoryInterface $cache_factory) {
    $this->cacheBin = $cache_factory->get('scientific_computation');
  }

  public function get($cid, $allow_invalid = FALSE) {
    $cached = $this->cacheBin->get($cid, $allow_invalid);
    if ($cached && $this->validateScientificData($cached->data)) {
      return $cached;
    }
    return FALSE;
  }

  public function set($cid, $data, $expire = CacheBackendInterface::CACHE_PERMANENT, array $tags = []) {
    $processed_data = $this->preprocessData($data);
    $this->cacheBin->set(
      $cid,
      $processed_data,
      $expire,
      array_merge($tags, ['scientific_computation'])
    );
  }

  protected function validateScientificData($data) {
    return is_array($data) && isset($data['result']) && isset($data['timestamp']);
  }

  protected function preprocessData($data) {
    return [
      'result' => $data,
      'timestamp' => time(),
      'source_hash' => md5(serialize($data)),
    ];
  }

  // Implement all other required CacheBackendInterface methods...
}

‍

Practical implementation examples

Machine learning model Cache

Scenario: A recommendation engine generates predictions that take 5 seconds to compute.

Solution: Cache predictions with Redis for fast retrieval.
‍

use Drupal\Core\Cache\CacheBackendInterface;

class MachineLearningModelCache {
  protected $cache;

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

  public function cacheModelPrediction($model_id, $input, $prediction) {
    $cache_id = 'ml_prediction:' . md5($model_id . serialize($input));
    $this->cache->set(
      $cache_id,
      [
        'model' => $model_id,
        'input' => $input,
        'prediction' => $prediction,
        'timestamp' => time(),
      ],
      CacheBackendInterface::CACHE_PERMANENT,
      ['machine_learning_predictions']
    );
  }
}

‍

Impact:

• Latency Reduction: Cuts prediction time from 5s to milliseconds.
• Scalability: Redis handles concurrent requests without database bottlenecks.

Geospatial data Caching

Scenario: A mapping application serves pre-rendered tiles that take 2 seconds to generate.

Solution: Use a file-based bin to offload the database.
‍

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\File\FileSystemInterface;

class MapTileCache implements CacheBackendInterface {
  protected $cacheBin;
  protected $fileSystem;

  public function __construct(CacheBackendInterface $cache_bin, FileSystemInterface $file_system) {
    $this->cacheBin = $cache_bin;
    $this->fileSystem = $file_system;
  }

  public function set($cid, $data, $expire, array $tags) {
    $uri = "public://cache/tiles/$cid.png";
    $this->fileSystem->saveData($data, $uri, FileSystemInterface::EXISTS_REPLACE);
    $this->cacheBin->set($cid, ['uri' => $uri], $expire, $tags);
  }

  public function get($cid, $allow_invalid = FALSE) {
    $cache = $this->cacheBin->get($cid, $allow_invalid);
    if ($cache && isset($cache->data['uri']) && file_exists($cache->data['uri'])) {
      return file_get_contents($cache->data['uri']);
    }
    return FALSE;
  }

  // Implement all other required CacheBackendInterface methods...
}

‍

Impact:

• Resource Efficiency: Reduces database load by storing large binary objects on disk.
• Resilience: Falls back to metadata for invalidation during file system failures.

Performance optimisation techniques

Best practices

1. Backend selection: Use Redis for low-latency access, file storage for large binaries.
2. Granular tags: Use specific tags like ml_model:42 instead of broad tags.
3. Dynamic expiration: Set max-age based on data volatility (e.g., weather data every 15 minutes).
4. Monitor: Track hit rates and generation times for proactive tuning.

Common pitfalls

• Overly Broad Tags: Using ml_model:all clears unrelated predictions.
• Inappropriate Backends: Storing large files in the database instead of the filesystem.

Debugging and monitoring

Logging Cache operations

Track cache activity for auditing and debugging:
‍

class CacheBinDebugger {
  public static function logCacheOperation($bin, $operation, $cid) {
    \Drupal::logger('cache_debug')->info(
      'Cache Operation: @operation in @bin for @cid',
      [
        '@operation' => $operation,
        '@bin' => $bin,
        '@cid' => $cid,
      ]
    );
  }
}

‍

Why it works:

• Operational Visibility: Identifies slow or frequently invalidated entries.
• Troubleshooting: Diagnoses missing dependencies during invalidation.

Performance monitoring

Use backend-specific tools to measure effectiveness:
‍

function mymodule_monitor_cache_bin_performance($bin_name) {
  $cache = \Drupal::cache($bin_name);

  // Example: Redis-specific stats (if using Redis)
  if (method_exists($cache, 'getConnection')) {
    $stats = $cache->getConnection()->info();
    \Drupal::logger('cache_performance')->info(
      'Redis Stats for @bin: @stats',
      [
        '@bin' => $bin_name,
        '@stats' => print_r($stats, TRUE),
      ]
    );
  }
}

‍

Metrics to monitor:

• Hit rate: High hit rates indicate effective caching.
• Generation time: Identify slow-to-generate content for optimisation.

Series navigation

This article is part of a comprehensive 10-part series on Drupal caching:

1. Introduction to Drupal Caching
2. Understanding Drupal’s Cache API
3. Choosing the Right Cache Backend for Your Drupal Site
4. Mastering Page and Block Caching in Drupal
5. Optimising Drupal Views and Forms with Caching
6. Entity and Render Caching for Drupal Performance
7. Building Custom Caching Services in Drupal
8. Implementing Custom Cache Bins for Specialised Needs (You are here)
9. Advanced Drupal Cache Techniques (Coming soon)‍
10. Drupal Caching Best Practices and Performance Monitoring (Coming soon)

‍

Wrapping up and what’s ahead?

As we wrap up, remember that implementing custom cache bins in Drupal is surprisingly straightforward once you understand the core concepts. Define your service in your module's services.yml file, create your cache bin class extending the appropriate backend, and register everything properly. These three steps will get you most of the way there. The real power comes when you fine tune your bin's configuration to match your specific caching needs and invalidation patterns. Don't hesitate to experiment with different backends and expiration strategies. Sometimes the best implementation reveals itself through trial and optimization. Your site's performance metrics will tell the story of your success.

Next, we’ll look at how advanced caching techniques build on this foundation. We’ll walk through cache hierarchies (memory → Redis → database), event-driven invalidation, and integrating with CDNs or edge networks to extend performance beyond the application layer.

‍

‍

The need for custom solutions

Drupal’s default caching mechanisms include cache.render and cache.page are designed for general use cases. They work well for standard content delivery, reducing load times and database queries across a broad range of applications. However, complex applications often require specialised caching logic that transcends these built-in systems.

Take, for instance, a financial reporting platform that processes thousands of data points per request. Default caching might reduce some backend calls, but it doesn’t address the computational overhead of transforming raw financial data into user-specific reports with real-time accuracy. Similarly, consider a personalised learning platform that dynamically assembles course content based on a learner’s history, progress, and preferences. In both cases, caching needs to go beyond what Drupal offers out of the box.

Default strategies fall short when performance demands collide with precision and dynamic output. In such scenarios, a custom caching service becomes essential, engineered to recognise context-specific data dependencies, invalidate intelligently, and serve pre-processed results without compromising on accuracy or personalisation.

Limitations of default Caching

Default caching systems are optimised for simplicity, but they struggle with niche requirements:

• Static vs. dynamic content: While static content (like product descriptions) benefits from broad caching, dynamic data (such as stock prices) requires fine-grained invalidation rules.
• Complex data structures: Nested JSON responses or hierarchical datasets may need specialised serialisation formats or invalidation triggers.
• Contextual variations: Default contexts like user. roles or url. path cannot accommodate business-specific variations (for example, caching based on user subscription tiers).
• Third-party integrations: External APIS or microservices often demand unique caching strategies to reduce latency and avoid rate limits.

When custom Caching adds value

Custom services shine in scenarios where default caching falls short:

• High-traffic, low-change content: E-commerce product listings that update infrequently but receive frequent visits.
• External API reliance: Applications that pull data from third-party services and need to mitigate network latency.
• Granular invalidation: Systems requiring precise cache clearing (such as refreshing only reports tied to a specific user).

Avoid custom caching for rapidly changing data (like live chat messages) or sensitive information (such as user-specific financial records), where default mechanisms or no caching at all may be safer.

Designing a custom Caching service

Core components explained

A custom caching service in Drupal relies on four foundational elements:

1. Cache backend
This defines where data is stored. Common backends include:

• Database: Default storage (cache.default), suitable for small-scale applications.
• Memory stores: APCu or Redis for faster access in single-server setups.
• Distributed Caches: Redis clusters or Memcached for multi-server environments.

2. Cache tags
Tags determine what triggers cache invalidation. For example:

• node:123 clears caches tied to a specific node.
• financial_report:2023 targets caches related to annual financial data.

Avoid broad tags like content_type: article, which can inadvertently clear unrelated caches.

Read more about cache tags.
‍

3. Cache contexts
Contexts define when to vary the cache. For instance:

• user.roles creates separate caches for admins vs. guests.
• Language ensures multilingual sites serve content in the correct language.

Use narrow contexts (like url. path instead of url) to prevent cache bloat. Note: For custom cache bins, you must include context values in your cache ID, as cache contexts are not natively supported outside render caching.

More on cache contexts.
‍

4. Cache metadata
Metadata includes rules like max-age (how long to store data) and dependencies (e.g., tags, contexts). This metadata ensures cached data remains fresh and relevant.

Dependency injection: why it matters

Drupal’s service container allows caching logic to be decoupled from business logic. By injecting dependencies like CacheBackendInterface and CacheContextsManager, services become:

• Testable: Easily mocked in unit tests.
• Flexible: Replace backends (for example, switching from database to Redis) without rewriting logic.

use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Cache\Context\CacheContextsManager;

class CustomCacheService {
  protected $cacheBackend;
  protected $cacheContextsManager;

  public function __construct(
    CacheBackendInterface $cache_backend,
    CacheContextsManager $cache_contexts_manager
  ) {
    $this->cacheBackend = $cache_backend;
    $this->cacheContextsManager = $cache_contexts_manager;
  }
}

‍

Learn about dependency injection in Drupal.

Step-by-step implementation

1. Register the service

Define the service in mymodule.services.yml:
‍

services:
  mymodule.custom_cache:
    class: Drupal\mymodule\Cache\CustomCacheService
    arguments:
      - '@cache.default'
      - '@cache.contexts_manager'

‍

This binds the service to Drupal’s dependency injection system, enabling reusability and testability.

2. Implement Caching logic

Create a method to fetch and cache data. Note: For custom cache bins, you must handle cache contexts by including them in the cache ID if needed.
‍

public function getCachedData($cache_id, $callback, $options = []) {
  $options += [
    'expire' => \Drupal\Core\Cache\CacheBackendInterface::CACHE_PERMANENT,
    'tags' => ['my_custom_cache'],
  ];
  if ($cached = $this->cacheBackend->get($cache_id)) {
    return $cached->data;
  }

  $data = $callback();
  $this->cacheBackend->set(
    $cache_id,
    $data,
    $options['expire'],
    $options['tags']
  );

  return $data;
}

‍

How It works:

• Check: First, the service checks if the cache exists.
• Generate: If not, the expensive operation (such as an API call) runs.
• Store: Results are saved with metadata for future reuse.

See the official Cache API usage guide.

Multi-level Caching: solving complex bottlenecks

Layered Caching Strategy

Multi-level caching balances speed and resilience by combining storage tiers:

• Memory Cache: Fastest but volatile (e.g., APCu).
• Local persistent Cache: Survives server restarts (e.g., Redis on a single server).
• Distributed Cache: Scales across servers (e.g., Redis clusters).
  ‍

class MultiLevelCacheService {
  protected $memoryCache = [];
  protected $localCache;
  protected $distributedCache;

  public function __construct($localCache, $distributedCache) {
    $this->localCache = $localCache;
    $this->distributedCache = $distributedCache;
  }

  public function getData($key, $fetchCallback) {
    if (isset($this->memoryCache[$key])) {
      return $this->memoryCache[$key];
    }

    if ($local_cached = $this->localCache->get($key)) {
      $this->memoryCache[$key] = $local_cached->data;
      return $local_cached->data;
    }

    if ($distributed_cached = $this->distributedCache->get($key)) {
      $this->localCache->set($key, $distributed_cached->data, \Drupal\Core\Cache\CacheBackendInterface::CACHE_PERMANENT);
      $this->memoryCache[$key] = $distributed_cached->data;
      return $distributed_cached->data;
    }

    $data = $fetchCallback();

    $this->memoryCache[$key] = $data;
    $this->localCache->set($key, $data, \Drupal\Core\Cache\CacheBackendInterface::CACHE_PERMANENT);
    $this->distributedCache->set($key, $data, \Drupal\Core\Cache\CacheBackendInterface::CACHE_PERMANENT);

    return $data;
  }
}

‍

Use case:
A news site with high traffic on its home page. The memory cache handles immediate requests, while the distributed layer ensures consistency across a server cluster.

Real-world example: Caching external API data

Scenario

An e-commerce platform pulls product pricing from a third-party API. Without caching, each request takes 2 seconds due to network latency.

Solution

Add a caching layer to reduce latency:
‍

class ApiCacheService extends CustomCacheService {
  protected $apiClient;

  public function __construct($cache_backend, $cache_contexts_manager, $apiClient) {
    parent::__construct($cache_backend, $cache_contexts_manager);
    $this->apiClient = $apiClient;
  }

  public function fetchWithCaching($endpoint, $params = []) {
    $cache_id = 'api_cache:' . md5($endpoint . serialize($params));

    return $this->getCachedData($cache_id, function() use ($endpoint, $params) {
      try {
        $response = $this->apiClient->request($endpoint, $params);
        return $this->processApiResponse($response);
      } catch (\Exception $e) {
        \Drupal::logger('api_cache')->error('API fetch failed: @message', ['@message' => $e->getMessage()]);
        return null;
      }
    }, [
      'expire' => REQUEST_TIME + 1800,
      'tags' => ['external_api_data'],
    ]);
  }

  protected function processApiResponse($response) {
    // Transform or sanitise as needed.
    return $response;
  }
}

‍

Impact:

• Latency reduction: Cuts API call time from 2s to near-instant.
• Graceful degradation: Falls back to cached data during API outages.

Error handling and fallbacks

Resilience through fallback layers

When a cache backend fails (e.g., Redis crashes), a fallback mechanism prevents downtime.
‍

public function getFallbackData($primary_key, $fallback_callback) {
  try {
    return $this->getCachedData($primary_key, $fallback_callback);
  } catch (\Exception $e) {
    \Drupal::logger('cache_service')->warning('Primary cache failed, using fallback');
    return $fallback_callback();
  }
}

‍

Why it works:

• User experience: Keeps the site functional during backend failures.
• Operational continuity: Ensures critical features remain accessible.

Performance monitoring

Tracking what matters

Create a tracker to measure cache effectiveness:
‍

class CachePerformanceTracker {
  protected $stats = ['hits' => 0, 'misses' => 0, 'generation_time' => []];

  public function trackCachePerformance($cache_id, $callback) {
    $start = microtime(true);
    $result = $callback();
    $this->stats['generation_time'][$cache_id] = microtime(true) - $start;
    return $result;
  }

‍

Metrics to monitor:

• Hit rate: High hit rates indicate effective caching.
• Generation time: Identify slow-to-generate content for optimisation.

Best practices and common pitfalls

Best practices

• Granular tags: Use financial_report:2023 instead of broad tags.
• Minimise contexts: Prefer url. path over url to reduce variants.
• Avoid sensitive data: Never cache CSRF tokens or PII.
• Monitor: Track hit rates and generation times for proactive optimisation.

Common pitfalls

• Overly broad contexts: Using url instead of url.path creates redundant cache entries.
• No fallbacks: A cache failure should not break the site.

Series navigation

This article is part of our comprehensive 10-part series on Drupal caching:

1. Introduction to Drupal Caching
2. Understanding Drupal’s Cache API
3. Choosing the Right Cache Backend for Your Drupal Site
4. Mastering Page and Block Caching in Drupal
5. Optimising Drupal Views and Forms with Caching
6. Entity and Render Caching for Drupal Performance
7. Building Custom Caching Services in Drupal (You are here)
8. Implementing Custom Cache Bins for Specialised Needs (Coming soon)
9. Advanced Drupal Cache Techniques (Coming soon)‍
10. Drupal Caching Best Practices and Performance Monitoring (Coming soon)

‍

‍

What’s next?

While Drupal’s default caching covers the basics, scaling performance for advanced applications often means thinking beyond the core. Custom caching services allow developers to fine-tune how data is stored, served, and invalidated, especially when dealing with highly dynamic or resource-intensive workloads.

In the next blog, we’ll explore how to go one step further with custom cache bins. You’ll learn how to create isolated cache storage for niche scenarios like session-based data, configure these bins in settings.php, and fine-tune caching strategies for performance-critical use cases.

To dive deeper into Drupal’s caching capabilities in the meantime, check out the Cache API documentation, along with resources on Cache Tags, Cache Contexts, and Cacheable Metadata.

‍

‍

Drupal’s entity system is powerful, but without proper caching, it can become a performance bottleneck. Understanding entity and render caching is crucial for building high-performance Drupal websites that can handle complex content structures efficiently.

In this blog, we’ll uncover the strategies that made this transformation possible.

Entity Caching fundamentals

In-depth explanation

Drupal’s entity caching system is a multi-layered mechanism that optimises performance by reducing redundant database queries and PHP processing. To understand its depth, let’s break down each layer and explore how it works under the hood.

1. Entity load Caching

What it does
When an entity (e.g., a node, user, or taxonomy term) is requested, Drupal typically queries the database to load its raw data. Entity Load Caching stores this raw data in the cache_entity bin (by default) to avoid repeated database calls for the same entity. The cache key is typically in the format entity:{entity_type}:{id}:{langcode} (e.g., entity:node:123:en).

Technical mechanics

• Entity storage system: Entities are loaded via the EntityStorageInterface (e.g., SqlContentEntityStorage). When an entity is first requested, it is fetched from the database and stored in the cache bin.
• Cache keys: The cache key is derived from the entity type, ID, and language (e.g., node:123:en).
• Invalidation: When an entity is updated or deleted, its cache entry is cleared using cache tags (e.g., node:123).

Why It matters

• Reduces database load: Eliminates redundant queries for frequently accessed entities.
• Speeds up entity access: Directly retrieves data from memory instead of parsing SQL results.

2. Render Caching

What it does
After an entity is loaded, Drupal generates a render array (a structured PHP array defining how the entity should be displayed). Render Caching stores these arrays to avoid rebuilding them on every request.

Technical mechanics

• Render arrays: Arrays like ['#markup' => 'Hello', '#cache' => [...]] are generated during entity rendering.
• Cache bin: Render arrays are stored in cache_render with keys based on entity type, ID, view mode, and cache contexts (e.g., user.roles).
• Cache contexts: Determine when to vary the cache (e.g., different render arrays for admins vs. anonymous users).

Why it matters

• Avoids rebuilding: Skips expensive operations like field rendering, template preprocessing, and access checks.
• Granular control: Uses cache tags (e.g., node:123) and contexts (e.g., url.path) to ensure freshness.

Example:
‍

// Add cache metadata to a render array.
$build['my_element'] = [
  '#markup' => 'Cached Content',
  '#cache' => [
    'contexts' => ['user.roles'],
    'tags' => ['node:123'],
    'max-age' => 3600,
  ],
];

3. View mode Caching

What it does
Entities are often displayed in different formats (e.g., “teaser” for listings and “full” for detail pages). View Mode Caching stores separate render arrays for each view mode to avoid redundant processing.

Technical mechanics

• View modes: View Modes: Defined in hook_entity_type_build() or via the UI (e.g., teaser, full, custom_mode).
• Cache key structure: Combines entity type, ID, view mode, and language (e.g., node:123:teaser:en).
• Customisation: Developers can alter view mode rendering via hook_entity_view() or hook_ENTITY_TYPE_view().

Why it matters

• Efficient Multi-Format Rendering: Prevents rebuilding the same entity for different contexts.
• Consistency: Ensures view modes like “teaser” remain fast even if the “full” view is complex.

Example hook:
‍

function mymodule_node_view(array &$build, \Drupal\Core\Entity\EntityInterface $entity, \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display, $view_mode) {
  if ($view_mode === 'teaser') {
    $build['#cache']['max-age'] = 7200;
  }
}

4. Field-level Caching

What it does
Fields (e.g., a “body” text field or an “image” field) can be cached individually to avoid reprocessing static content.

Technical mechanics

• Field formatters: Each field’s display is handled by a formatter (e.g., text_default, image).
• Cache granularity: Developers can specify caching for individual fields using hook_field_formatter_view_alter(). Note: In practice, field formatter plugins should set cache metadata directly on render arrays. The hook is for last-resort alterations.
• Dependencies: Field caching relies on render arrays and cache metadata bubbled up from the field level.

Why it matters

• Optimises static fields: Caches rarely changing fields (e.g., author bio) while dynamic fields (e.g., stock status) remain uncached.
• Reduces overhead: Avoids reprocessing fields with expensive calculations (e.g., computed fields).

Example hook:
‍

function mymodule_field_formatter_view_alter(array &$element, array $context) {
  if ($context['field_name'] === 'field_price') {
    $element['#cache'] = [
      'contexts' => ['user.roles'],
      'tags' => ['field:price'],
      'max-age' => 1800,
    ];
  }
}

Use Case 1: Hybrid Caching for a product catalogue

Scenario

An e-commerce site needs fast delivery of product pages for anonymous users but must update instantly when inventory changes.

Goal

Combine entity load caching with tag-based invalidation to reduce database queries while keeping content fresh.

Sample implementation
‍

/**
 * Implements hook_node_view().
 *
 * Adds cache metadata for product nodes with tag-based invalidation.
 */
function mymodule_node_view(array &$build, \Drupal\Core\Entity\EntityInterface $entity, \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display, $view_mode) {
  if ($entity->bundle() === 'product' && $view_mode === 'full') {
    $build['#cache']['tags'][] = 'product_list';
    $build['#cache']['max-age'] = 3600;
  }
}

‍

Explanation:
This caches product entities for 1 hour (max-age) but clears the cache when the entity is edited (node:$nid) or when the product list changes (product_list).

Render pipeline overview

In-depth explanation

The render pipeline is the sequence of steps Drupal uses to transform entities into HTML. Let’s dissect each stage and explore its role in caching.

1. Entity loading

What happens

• Database query: Drupal queries the database for entity data (e.g., node title, body).
• Field data: Retrieves field values from field_data_* tables.
• Access checks: Verifies user permissions to view the entity.

Caching interaction

• Entity load Caching: If the entity is already in the cache_entity bin, it bypasses the database.
• Performance impact: Avoids 1–5 SQL queries per entity.

2. Field value loading

What happens

• Field definitions: Loads field definitions from core.entity_field_manager.
• Field values: Gathers values for all fields (e.g., field_image, field_tags).
• Field formatters: Determines how each field should be rendered (e.g., image style, link format).

Caching interaction

• Field-level Caching: If a field’s formatter is cached, its render array is pulled from cache_render.
• Performance impact: Reduces time spent processing field data for static fields.

3. Render array generation

What happens

• Structured array: Builds a render array with elements like #type, #markup, and #theme.
• Preprocessing: Invokes hook_preprocess_HOOK() functions to add variables for templates.
• Cache metadata: Aggregates cache contexts (e.g., user.roles) and tags (e.g., node:123).

Caching interaction

• Render Caching: The final render array is stored in cache_render for reuse.
• Performance impact: Avoids rebuilding complex arrays for subsequent requests.

4. Cache Metadata collection

What happens

• Contexts: Determine when to vary the cache (e.g., language, user.roles).
• Tags: Track dependencies (e.g., node:123, user:456).
• Max-age: Sets the cache lifetime (e.g., 3600 seconds).

Technical details

• Bubbling: Child elements (e.g., blocks, fields) bubble their metadata to parent containers.
• Merge logic: Parent elements inherit the most restrictive max-age and combine contexts/tags.

Example:
‍

// Bubbling metadata from a child element to a parent.
$parent['child_element'] = [
  '#markup' => 'Cached Child',
  '#cache' => [
    'contexts' => ['user.roles'],
    'tags' => ['node:123'],
    'max-age' => 3600,
  ],
];
$parent['#cache'] = [
  'contexts' => ['url.path'],
  'tags' => ['page:home'],
  'max-age' => 7200,
];
// After bubbling, the parent's metadata includes:
// contexts = ['url.path', 'user.roles']
// tags = ['page:home', 'node:123']
// max-age = 3600 (the lower of 7200 and 3600).

5. Final rendering

What happens

• Theme resolution: Maps render arrays to Twig templates or PHP callbacks.
• HTML generation: Converts the render array into HTML (e.g., <div>Cached Content</div>).
• Output: Sent to the browser or stored in the page cache (cache_page).

Caching interaction

• Dynamic Page Cache: For authenticated users, fragments are cached in cache_dynamic_page_cache.
• Internal Page Cache: For anonymous users, the full HTML is stored in cache_page.

Performance impact

• Anonymous Users: Serves HTML directly from cache_page without bootstrapping Drupal.
• Authenticated Users: Reuses cached fragments from cache_dynamic_page_cache.

Use Case 2: Debugging slow page loads

Scenario

A news site’s article pages take 2+ seconds to load. Profiling shows repeated field processing.

Goal

Add cache metadata to preprocess functions to reduce redundant processing.

Sample implementation
‍

 * Implements hook_preprocess_node().
 *
 * Adds cache metadata to node templates.
 */
function mymodule_preprocess_node(array &$variables) {
  $node = $variables['node'];
  $variables['#cache'] = [
    'contexts' => ['user.roles', 'language'],
    'tags' => ['node:' . $node->id(), 'content_type:article'],
    'max-age' => 1800,
  ];
}

‍

Explanation:
This caches the rendered HTML for 30 minutes, varying by user role and language. Tags ensure the cache clears when the article is updated.

Cache contexts and tags

In-depth explanation

Drupal’s caching system relies on cache contexts and cache tags to balance performance with precision. These mechanisms ensure cached content is both fast and correct, avoiding stale data while minimizing redundant computation. Let’s dissect their mechanics, interactions, and real-world implications.

1. Cache contexts: when to vary the Cache

What they do
Cache contexts define when cached content should differ. They act as variation keys—if any context value changes, Drupal generates a new cache entry.

Technical mechanics

• Variation logic: Contexts like user.roles, language, or url.path are resolved at runtime. Their values (e.g., ["anonymous"], "en", "/blog") become part of the cache key.
• Context stack: Drupal uses a prioritised list of available contexts (defined via \Drupal\Core\Cache\Context\CacheContextInterface). Common ones include:
  
  • user.roles: Different content for admins vs. editors.
  • language: Language-specific versions for multilingual sites.
  • url.path: Unique caching for each page (e.g., /home vs. /about).
  • theme: Separate caching for mobile vs. desktop themes.
• Context Conflicts: Avoid overly broad contexts like url (includes query parameters) unless necessary. Use url.path instead to reduce cache bloat.

Why it matters

• Precision: Prevents serving admin menus to anonymous users or mixing language outputs.
• Efficiency: Reduces redundant cache entries by choosing the minimal set of contexts required.

Example:
‍

// Cache a block differently for editors vs. anonymous users.
$build['my_block'] = [
  '#markup' => 'Welcome, ' . \Drupal::currentUser()->getAccountName(),
  '#cache' => [
    'contexts' => ['user.roles'],
    'tags' => ['user:' . \Drupal::currentUser()->id()],
    'max-age' => 900,
  ],
];

2. Cache tags: how to invalidate the Cache

What they do
Cache tags define what triggers cache invalidation. They tie cached data to entities or external dependencies (e.g., node:123, config:system.site). When a tag is invalidated, all cache entries referencing it are cleared.

Technical mechanics

• Tag resolution: Tags are resolved via the CacheableMetadata class. Entities automatically bubble their tags (e.g., a node’s node:123), but developers can add custom tags manually.
• Tag inheritance: Parent elements inherit tags from children through cache bubbling. For example, a node with a field_image will inherit the image field’s tags.
• Granularity: Tags can be entity-specific (node:123), bundle-level (content_type:article), or even custom (e.g., weather_api:city=paris).

Why it matters

• Freshness: Ensures updates to an entity invalidate only relevant caches, not the entire site.
• Scalability: Avoids full-cache clears during bulk operations (e.g., updating 100 nodes only invalidates 100 tags).

Example:
‍

// Invalidate a cached view when any article is updated.
$build['my_view'] = [
  '#markup' => $rendered_view,
  '#cache' => [
    'tags' => ['content_type:article'],
    'max-age' => 3600,
  ],
];

3. Interplay between contexts and tags

How they work together

• Contexts ≠ Tags: Contexts vary the cache (e.g., “show different content”), while tags control invalidation (e.g., “clear when something changes”).
• Performance impact: A render array with contexts: ['user.roles'] and tags: ['node:123'] creates a unique cache entry per role but invalidates all role-specific versions when the node updates.

Example:
‍

  '#type' => 'form',
  '#form' => '\Drupal\comment\Form\CommentForm',
  '#cache' => [
    'contexts' => ['user', 'session'], // Varies for logged-in users.
    'tags' => ['node:123'], // Invalidates when the node changes.
    'max-age' => 0, // Never cached for anonymous users.
  ],
];

Use case 3: multilingual Caching pitfalls

Scenario

A multilingual site serves French and English articles. Without proper caching, users occasionally see mixed-language content.

Goal

Cache article pages by language to prevent mixed outputs.

Sample implementation
‍

/**
 * Implements hook_entity_view_alter().
 *
 * Ensures multilingual content is cached per language.
 */
function mymodule_entity_view_alter(array &$build, \Drupal\Core\Entity\EntityInterface $entity, $view_mode) {
  // Initialize cache metadata if not set.
  if (!isset($build['#cache'])) {
    $build['#cache'] = [];
  }

  // Merge cache contexts.
  $build['#cache']['contexts'] = isset($build['#cache']['contexts'])
    ? CacheableMetadata::mergeContexts($build['#cache']['contexts'], ['languages:language_interface'])
    : ['languages:language_interface'];

  // Merge cache tags.
  $node_tag = 'node:' . $entity->id();
  $language_tag = 'language:' . $entity->language()->getId();
  $build['#cache']['tags'] = isset($build['#cache']['tags'])
    ? CacheableMetadata::mergeTags($build['#cache']['tags'], [$node_tag, $language_tag])
    : [$node_tag, $language_tag];

  // Optionally set max-age (default permanent).
  if (!isset($build['#cache']['max-age'])) {
    $build['#cache']['max-age'] = CacheableMetadata::CACHE_PERMANENT;
  }
}

‍

Explanation:
This ensures the cache varies by language, preventing French users from seeing English content and vice versa.

Field-level Caching

In-depth explanation

Field-level caching optimises performance by storing the rendered output of individual fields (e.g., text, images, computed values) independently. This allows static fields to be cached for extended periods while dynamic fields remain fresh. Unlike entity-level caching, field-level caching operates at a granularity that avoids reprocessing expensive formatters (e.g., geolocation maps, computed prices) unnecessarily.

1. Technical mechanics of field Caching

A. field formatters and render arrays
Fields are rendered via formatters, which are plugins implementing FieldFormatterInterface. Each formatter generates a render array with attached cache metadata.

Example formatter flow:

1. Field definition: Retrieved via EntityFieldManagerInterface.
2. Formatter plugin: Resolved from configuration (e.g., text_default, image).
3. Render array: Generated by the viewElements() method, including #cache metadata.
   ‍

// Example of a field formatter's viewElements() method.
public function viewElements(FieldItemListInterface $items, $langcode) {
  $elements = [];
  foreach ($items as $delta => $item) {
    $elements[$delta] = [
      '#markup' => $this->sanitizeValue($item->value),
      '#cache' => [
        'contexts' => ['user.roles'],
        'tags' => ['field:custom_text'],
        'max-age' => 3600,
      ],
    ];
  }
  return $elements;
}

‍

B. Cache metadata bubbling
Field-level cache metadata (contexts, tags, max-age) is bubbled up to parent containers (e.g., entities, pages) during render pipeline processing. This ensures invalidation cascades correctly.

Example:
A node’s field_image with #cache['tags'] = ['node:123'] ensures the entire node’s cache clears when the image updates.

Use case 4: conditional Caching for user-specific fields

Scenario

A price field must show discounted prices to logged-in users but static pricing for guests.

Goal

Cache the field for 30 minutes, but vary by user role.

Sample implementation
‍

/**
 * Implements hook_field_formatter_view_alter().
 */
function mymodule_field_formatter_view_alter(&$element, $context) {
  $element['#cache'] = [
    'contexts' => ['user.roles'],
    'tags' => ['field:price', 'user:' . \Drupal::currentUser()->id()],
    'max-age' => 1800,
  ];
}

‍

Explanation:
This creates separate cache entries for different user roles while invalidating the cache when the price field changes.

Cache bubbling

In-depth explanation

Cache bubbling is the process by which cache metadata (contexts, tags, and max-age) from deeply nested render elements (e.g., fields, blocks, forms) propagates upward to parent containers (e.g., entities, pages). This mechanism ensures that the caching behaviour of a composite element reflects all its dependencies, preventing stale content and maintaining cache coherence across the entire render tree.

Without cache bubbling, a parent container might cache independently of its children, leading to situations where an updated field or block remains invisible until the parent’s cache expires. Bubbling guarantees that invalidation cascades correctly and that cache variations (e.g., role-specific content) are preserved at every level.

1. Technical mechanics of Cache bubbling

A. How metadata propagates
Cache metadata flows upward through the render array hierarchy:

1. Child elements: Fields, blocks, or subcomponents define their own #cache properties.
2. Parent aggregation: The renderer merges child metadata into the parent’s #cache array during processing.
3. Conflict resolution:

• Contexts: Combined into a union (e.g., ['user.roles', 'url.path']).
• Tags: Merged into a single list (e.g., ['node:123', 'block:sidebar']).
• Max-age: The lowest value wins (e.g., 3600 and 1800 → 1800).

Example:
‍

// A render array with a cached child element.
$parent = [
  '#type' => 'container',
  '#cache' => [
    'contexts' => ['url.path'],
    'tags' => ['page:home'],
    'max-age' => 7200,
  ],
  'child' => [
    '#markup' => 'Cached Content',
    '#cache' => [
      'contexts' => ['user.roles'],
      'tags' => ['node:123'],
      'max-age' => 3600,
    ],
  ],
];

// After bubbling, the parent's metadata becomes:
$parent['#cache'] = [
  'contexts' => ['url.path', 'user.roles'], // Union of contexts.
  'tags' => ['page:home', 'node:123'],      // Combined tags.
  'max-age' => 3600,                        // Lowest max-age.
];

‍

B. Bubbleable metadata interface
Drupal core uses the BubbleableMetadata class to manage metadata propagation. Developers can manually manipulate it:

use Drupal\Core\Render\BubbleableMetadata;
‍

// Create a BubbleableMetadata object.
$metadata = BubbleableMetadata::createFromRenderArray($element);

// Merge metadata from a child element.
$metadata->merge(BubbleableMetadata::createFromRenderArray($child_element));

// Apply merged metadata back to the parent.
$metadata->applyTo($parent_element);

2. Why Cache bubbling matters

• Correctness: Ensures updates to a field or block invalidate all cached parents referencing it.
• Efficiency: Avoids full-site cache clears during partial updates (e.g., editing a single block).
• Granularity: Allows dynamic components (e.g., CSRF tokens) to disable caching for their parents.

Example:
A node with a field_comments block will inherit the block’s comment:* tags. Updating a comment invalidates the node’s cache.

Use Case 5: Debugging Cache bubbling

Scenario

A custom block inside an article page isn’t invalidated when the article is updated.

Goal

Log cache metadata to identify missing dependencies.

Sample implementation
‍

function mymodule_debug_cache_bubbling($element) {
  $cache_contexts = $element['#cache']['contexts'] ?? [];
  $cache_tags = $element['#cache']['tags'] ?? [];

  \Drupal::logger('cache_debug')->info(
    'Cache Contexts: @contexts, Tags: @tags',
    [
      '@contexts' => implode(', ', $cache_contexts),
      '@tags' => implode(', ', $cache_tags)
    ]
  );
}

‍

Explanation:
This logs cache metadata to help identify if the block is missing a critical tag like node:123.

Performance optimisation techniques

In-depth explanation

Optimising caching in Drupal requires balancing speed and correctness. By applying targeted strategies, developers can reduce server load while ensuring users see up-to-date content. Below are battle-tested techniques, complete with code examples and real-world applications.

1. Use granular Cache tags

Why it matters
Broad tags like content_type:article invalidate caches unnecessarily. Granular tags (e.g., node:123, field: price) ensure only relevant content updates.

Technical implementation

• Entity-specific tags: Attach entity:$type:$id tags to components referencing a single entity.
• Bundle-level tags: Use content_type:$bundle for bulk invalidations (e.g., updating a shared field formatter).

Example:
‍

/**
 * Implements hook_block_view_alter().
 *
 * Cache a product block with entity-specific tags.
 * Example assumes 'field:product_promo' is a custom tag for the promo field.
 */
function mymodule_block_view_alter(array &$build, \Drupal\Core\Block\BlockPluginInterface $block) {
  if ($block->getPluginId() === 'product_promo_block') {
    $product_id = \Drupal::routeMatch()->getParameter('product');
    $build['#cache'] = [
      'tags' => ['node:' . $product_id, 'field:product_promo'],
      'max-age' => 3600,
    ];
  }
}

2. Minimise Cache contexts

Why it matters
Each context multiplies the number of cache variants. For example, URL context creates separate caches for /page vs. /page?foo=bar, even if the content doesn’t vary by query parameters.

Technical implementation

• Replace broad contexts: Use url.path instead of url unless query parameters affect output.
• Avoid redundant contexts: Skip user if role-based variations suffice (e.g., user.roles).

Example:
‍

/**
 * Implements hook_preprocess_block().
 *
 * Cache a block by path, not full URL.
 */
function mymodule_preprocess_block(&$variables) {
  $variables['#cache'] = [
    'contexts' => ['url.path', 'language'],
    'tags' => ['block:promo_banner'],
    'max-age' => 7200,
  ];
}

3. Leverage Render Cache Selectively

Why it matters
Not all content benefits from caching. Static fields (e.g., author bios) gain speed, while dynamic content (e.g., form validation errors) must bypass caching.

Technical implementation

• Static content: Set a long max-age for rarely changing fields.
• Dynamic content: Use max-age: 0 or #cache['contexts'][] = 'session' for per-user data.

Example:
‍

/**
 * Implements hook_form_alter().
 *
 * Prevent CSRF token caching in forms.
 */
function mymodule_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
  if ($form_id === 'contact_form') {
    $form['#cache'] = [
      'contexts' => ['user'],
      'max-age' => 0,
    ];
  }
}

4. Avoid Caching sensitive data

Why it matters
Caching session-specific or PII (Personally Identifiable Information) risks exposing private data. Always vary by user or disable caching entirely.

Technical implementation

• User-specific content: Add user context to ensure per-user cache variants.
• Session data: Use session context for temporary state (e.g., shopping cart items).

Example:
‍

/**
 * Implements hook_preprocess_node().
 *
 * Prevent caching of user-specific content.
 */
function mymodule_preprocess_node(&$variables) {
  $node = $variables['node'];
  if ($node->getType() === 'private_document') {
    $variables['#cache'] = [
      'contexts' => ['user'],
      'tags' => ['node:'. $node->id()],
    ];
  }
}

5. Monitor and benchmark Cache effectiveness

Why it matters
Caching optimisations are only valuable if they reduce database load and improve page speed. Use metrics to validate changes.

Technical implementation

• SQL query counting: Use the Devel module to track queries per page.
• Cache headers: Check X-Drupal-Cache and X-Drupal-Cache-Tags in HTTP responses.
• Performance tools: Integrate New Relic or Blackfire.io for granular profiling.

Example:
‍

// Log cache hit/miss statistics via a custom service.
class CacheStatsLogger {
  public function logCacheStatus($cid, $cache_hit) {
    $logger = \Drupal::logger('cache_stats');
    if ($cache_hit) {
      $logger->info('Cache hit for @cid', ['@cid' => $cid]);
    } else {
      $logger->warning('Cache miss for @cid', ['@cid' => $cid]);
    }
  }
}

Common pitfalls and how to avoid them
‍

// Use Drush to analyse cache tags and contexts.
drush cache: rebuild
drush request /node/123 --extra-headers='Accept: text/html' | grep 'X-Drupal-Cache-Tags'

/**
 * Implements hook_entity_view_mode_alter().
 */
function mymodule_entity_view_mode_alter(&$view_mode, $context) {
  $entity = $context['entity'];
  $context['build']['#cache'] = [
    'contexts' => ['user.roles', 'user.permissions'],
    'tags' => ['entity:' . $entity->id(), 'entity_list:' . $entity->getEntityTypeId()],
    'max-age' => 7200,
  ];
}