Cache Backends

The Image Proxy ships with three cache backends. The active backend is selected on the Settings → Cache backend card. This page explains when to pick which.

At a Glance

Backend	Best for	Caveats
Filesystem	Default; single-server installs	Slowest under cold cache; needs a writable directory.
Redis	Multi-server installs and high traffic	Requires the phpredis PHP extension on every web node.
Memcached	Hosts that already operate Memcached	Cannot enumerate keys → Purge flushes the whole server and statistics show zero.

Filesystem

Cached images are stored as files on disk. This is the default and works on any host without extra extensions or services.

• Storage location: Defaults to the system temp directory. You can point it at a directory under wp-content instead — anything outside those two roots is rejected for safety.
• Cold cache: Filesystem is slower than Redis or Memcached on a cold cache because each request touches disk. Once cached, modern OS-level page caches keep popular images hot, so the practical difference shrinks.
• Persistence: Cache entries survive PHP / web server restarts.
• Capacity: Limited only by free disk space.

Redis

An in-memory cache served by a Redis instance. Best when the proxy serves many concurrent requests or runs behind a load balancer with multiple PHP nodes.

• Requirement: The phpredis PHP extension must be loaded — the Redis option is hidden from the Settings card if it's not. Enabling Redis without the extension shows a yellow warning in the UI and causes the pipeline to fall back to a NullCache.
• Multi-server: All PHP nodes can share one Redis instance, so a request served by node A populates the cache for node B.
• Persistence: Survives PHP restarts. Whether it survives a Redis restart depends on your Redis persistence configuration (RDB/AOF).
• Authentication: Password is optional. The plugin never returns the stored password through its REST API.

Memcached

An alternative in-memory backend for hosts that already run Memcached.

• Requirement: The ext-memcached PHP extension must be loaded — the option is hidden otherwise.
• Persistence: Memcached does not persist data across server restarts. After a Memcached restart the cache is empty and the first batch of requests will be misses.
• Key enumeration limitation: Memcached has no protocol-level way to list its keys. Two consequences:
  • Purge cache flushes the entire Memcached server, including any data unrelated to the Image Proxy. If other applications share the same Memcached instance, prefer Redis or Filesystem.
  • The Dashboard cache panel shows zero for entry count, used bytes, and oldest entry. Hit / miss / error counters are still accurate because they come from an independent event store.

Fallback Behaviour

When the configured backend is unavailable — Redis or Memcached extension missing, or the filesystem directory is not writable — the pipeline transparently switches to a NullCache:

• Every request looks like a cache miss.
• Origin fetches happen on every page load.
• The Dashboard backend chip turns yellow and a warning appears below: "The configured backend is not available — the proxy is using a fallback."

This is intentional: the proxy keeps serving images correctly even when the cache is broken, so visitor IPs continue to be protected. Once the underlying backend is fixed (extension installed, directory writable), caching resumes automatically without further intervention.