Using Drupal's cache API for expensive computations
Dynamic Drupal builds often repeat expensive work: a shipping quote calls several carrier APIs, a reporting endpoint aggregates thousands of records, and a dashboard recalculates the same recommendation for every visitor. These operations are good candidates for a persistent cache, provided the stored value has a clear expiry and a dependable invalidation path.
The Drupal cache API stores serialisable values between requests through named cache bins. It sits below page and render caching: those layers can reuse an assembled response, while the API retains the result of one domain calculation. That distinction matters when a calculation must remain editable, be tagged against the records that shaped it, and serve anonymous and authenticated requests without rebuilding the final page.
A sound implementation treats cached data as temporary derived state, not as the source of truth. In Australia, that means designing for Sydney, Melbourne, Brisbane and Perth across several time zones, retaining prices in Australian dollars, and separating rules for tax and delivery. The same disciplined approach prevents a cached freight calculation from becoming a permanent pricing or customer-data problem.
| Caching layer | Suitable workload | Lifetime and invalidation | Main limitation |
|---|---|---|---|
| Drupal Cache API | Custom domain results and expensive calculations | Cross-request storage with TTL and cache tags | Requires careful key and dependency design |
| Render cache | Drupal render arrays and assembled fragments | Invalidated through Drupal’s render and entity metadata | Does not suit arbitrary business calculations |
| Entity and query caches | Repeated entity or query loading | Entity-aware tags and Drupal-managed invalidation | Optimises a different part of the request |
| Request-local memoisation | The same lookup repeated within one request | Lasts only for the current request | Provides no reuse by later visitors |
Selecting the right caching layer
Use the Cache API when the expensive unit is a domain result: a carrier response, a computed quote, a search result set, or an analytics summary. Page caching is better when the complete output can be reused as-is, while render caching is designed for render arrays. Saving the smaller result gives other Drupal code a reusable value and makes expiry and invalidation easier to reason about.
Most sites inject the cache.default service, whose database-backed storage persists across requests. Modules can use other bins for data with a distinct lifecycle or move a high-traffic deployment to a shared backend such as Redis with appropriate configuration. Whichever backend is selected, entries are serialised, so objects should implement serialisation cleanly and values should not contain resources, closures or live service references.
Request-local variables are still useful inside a calculation that repeats the same lookup several times, but they disappear when the request ends. A useful service can combine both levels: keep one result in memory for the current request and use the persistent cache for later visitors. This cache-aside approach reduces database work and repeated calls to an external service without making the cache the authoritative record.
Designing reliable keys and dependencies
Every cache entry needs an identifier derived from every input that can change its value. A freight quote might depend on origin postcode, destination postcode, parcel weight, service level, warehouse, tax context, locale and the customer’s effective price permissions. Hashing a canonical representation keeps the key within Drupal’s length limits and prevents punctuation or ordering differences from creating duplicate entries. Include a version string so a deployment can invalidate old logic without deleting unrelated entries.
Cache tags describe dependencies, while a time-to-live controls freshness when no event tells the site that data has changed. Tag a quote with its warehouse, carrier, route group and relevant product identifiers, then invalidate those tags after a rate, stock record or configuration change. A TTL is still required for upstream data that Drupal cannot observe. It also provides a useful ceiling for experimental or temporary calculations that should never live indefinitely.
External sources can change independently of a Drupal save event. A campaign importing headlines such as the launch coverage for Chicken Road 2 AU can become obsolete quickly, so give that feed a short TTL and a source-specific tag. Local delivery conditions add further variables: road closures between Melbourne and regional hubs, courier cut-offs and click-and-collect inventory at a Sydney warehouse can all alter a quote. Those dependencies belong in the invalidation design.
Caching calculations in a Drupal service
Put caching behind a dedicated Drupal service instead of scattering calls through controllers. Dependency injection makes the backend replaceable in tests and keeps business rules separate from HTTP responses. A small service can accept already-normalised inputs, create a key, fetch an entry and return cached data when suitable.
<?php
namespace Drupal\my_module\Cache;
use Drupal\Core\Cache\CacheBackendInterface;
final class ShippingQuoteCache {
public function __construct(private CacheBackendInterface $cache) {}
public function get(string $cache_id): ?array {
$item = $this->cache->get($cache_id);
return $item === FALSE ? NULL : $item->data;
}
public function set(
string $cache_id,
array $quote,
int $ttl,
array $tags
): void {
$this->cache->set($cache_id, $quote, time() + $ttl, $tags);
}
}
The service definition wires the cache backend into the class:
services:
my_module.shipping_quote_cache:
class: Drupal\my_module\Cache\ShippingQuoteCache
arguments:
- '@cache.default'
In production code, calculate the key from a canonical request, call get() and treat false as a miss. A SHA-256 hash of a versioned representation provides a practical key without exposing personal details. Only the owning service should decide when to calculate and store a replacement, which prevents several parts of a module from writing inconsistent values under the same identifier.
Use getMultiple() and setMultiple() for batches when the entries share sensible expiry and tag rules. Use individual set() calls when each record needs a different TTL or dependency set. Cached values should contain plain data such as identifiers, monetary amounts in integer cents, timestamps and display-ready labels. Rebuilding those values from authoritative records keeps the cache portable between database, Redis and Memcached backends.
Invalidating data without disrupting traffic
Invalidate explicitly when the site knows a dependency changed. After saving new carrier rates, for example, call invalidateTags(['shipping_quote', 'carrier_fedex']); after updating stock for a warehouse, invalidate its inventory tag. Drupal also invalidates caches associated with changed entities, but a custom calculation benefits only when its identifiers are represented in the tags it stores. Keep broad and narrow tags separate so one product update does not flush every quote on the site.
Expiry alone does not prevent a cache stampede. When a popular entry expires, concurrent requests can all notice the miss and start the same costly calculation. Use Drupal’s Lock API to let one request refresh the value while others wait briefly or receive the previous result. Acquire a namespaced lock with a short timeout, check the cache again after acquiring it, and release the lock in a finally block. A lock protects work; it does not replace an expiry or dependency tag.
High-traffic pages need a deliberate stale-value policy. One pattern stores fresh and fallback keys, serves the fallback while a background or queued refresh runs, and labels the result as estimated when the source is delayed. Weather disruptions, a Melbourne Cup delivery surge or an upstream carrier incident can make a fresh answer unavailable. Keeping a bounded fallback avoids both an empty widget and an indefinite promise that an old price remains valid.
Preparing an Australian Drupal site for production
Australian consumer law makes accurate shipping charges, delivery windows and refund terms business-critical. For covered organisations, the Privacy Act 1988 and Australian Privacy Principles constrain how personal information is collected, used, stored and secured. A freight cache should avoid names, full addresses, phone numbers and account credentials. If a personalised quote is necessary, restrict its key and lifetime, and confirm that cache storage is covered by the organisation’s privacy and retention practices.
- Measure the calculation before caching it, recording execution time, call volume, hit rate and the cost of misses.
- Build keys from canonical inputs, include schema versions and partition results by market, locale, tax setting and permissions.
- Attach dependency tags to every entry and combine them with a realistic time-to-live.
- Guard refreshes with the Lock API so expiry does not trigger a stampede of expensive work.
- Store the minimum required data, excluding credentials and unnecessary customer information.
- Test Australian edge cases, including AUD amounts, standard GST, postcode zones and daylight-saving transitions.
- Plan deployments with a cache-version change, monitor hit rates and give operators a safe purge procedure.
After deployment, watch slow query logs, external API latency, cache misses and the age of returned values together. A high hit rate with stale data is not a healthy result, while a low hit rate can indicate keys that vary for trivial reasons. Record cache decisions in the pull request that introduced them, especially when results affect freight, tax, stock or customer access. Clear ownership makes the optimisation maintainable when rates, carriers and Drupal releases change.