Caché: Transients API y Object Cache

Base arquitectónica#

El sistema de almacenamiento en caché en WordPress es una arquitectura multinivel dividida en la memoria en tiempo de ejecución del proceso (runtime), una capa de abstracción para datos temporales (Transients API) y un almacén de objetos persistente (Persistent Object Cache).

Runtime Object Cache (WP_Object_Cache): Por defecto, el motor integrado en el núcleo almacena objetos en la memoria RAM del proceso PHP (static array). El ciclo de vida de esta caché está limitado a una única petición HTTP. Evita consultas SQL duplicadas dentro del mismo script (por ejemplo, llamadas repetidas a get_post(42) no consultan el RDBMS), pero se destruye completamente al finalizar la petición.

Drop-in de caché persistente (object-cache.php): Colocar un archivo en wp-content/object-cache.php anula la clase estándar WP_Object_Cache. En las infraestructuras corporativas de 2026, se emplean motores RDBMS en memoria distribuidos como Redis 7.4+ o Valkey. El object cache persistente retiene estructuras de datos serializadas entre peticiones HTTP independientes, reduciendo las consultas a MySQL de cientos a unas pocas por página.

Transients API: La interfaz histórica del núcleo para almacenar datos temporales con un tiempo de vida (TTL) configurado:

• set_transient($key, $value, $expiration)
• get_transient($key)
• delete_transient($key)

Bifurcación arquitectónica de la Transients API:

1. Con Persistent Object Cache activo: Las funciones *_transient() se enrutan de forma transparente hacia wp_cache_*(), utilizando el grupo transient. Los datos residen en Redis con mecanismos de expiración nativos (EXPIRE).
2. Sin Persistent Object Cache: Los transients se escriben en la tabla relacional wp_options como dos filas independientes: _transient_{key} y _transient_timeout_{key}. Si no se especifica expiración ($expiration = 0), el transient se marca con autoload = 'yes'. Esto causa un crecimiento catastrófico (bloat) en wp_options, degradación de la caché alloptions y agotamiento de la memoria del servidor en cada arranque del núcleo.

Un desafío crítico en arquitecturas de alta concurrencia es el Cache Stampede (efecto Dogpile / Thundering Herd): el momento en que una clave caliente con un millón de peticiones por minuto expira, provocando que miles de procesos PHP paralelos experimenten simultáneamente un fallo de caché («cache miss») y saturen MySQL con cálculos pesados idénticos. Para mitigar esto, se utilizan mutex distribuidos (wp_cache_add) y el algoritmo de recálculo probabilístico preventivo (XFetch).

Modelo mental#

Comparación del comportamiento del sistema cuando una clave caliente expira: colapso clásico (Thundering Herd) frente a compuerta de mutex distribuido (Distributed Mutex Gate):

DESASTRE: THUNDERING HERD (Sin Mutex)
=================================================================================
¡Clave expirada en Redis!
Petición 1  (Miss) ----+
Petición 2  (Miss) ----|---> ¡10.000 consultas SQL pesadas concurrentes a MySQL!
Petición 3  (Miss) ----|    [Resultado: 100% CPU, agotamiento de conexiones, 504 Gateway Timeout]
Petición N  (Miss) ----+

ARQUITECTURA ENTERPRISE: ATOMIC MUTEX + STALE SERVE
=================================================================================
¡Clave expirada en Redis!
Petición 1  (Miss) ---> Intenta adquirir mutex (wp_cache_add / SETNX) -> ¡ÉXITO!
                         |---> Ejecuta la consulta SQL pesada (1 hilo)
                         v
                       Actualiza Redis y libera el mutex
                       
Petición 2  (Miss) ---> Intenta adquirir mutex -> ¡OCUPADO!
                         |---> Devuelve datos obsoletos (Stale Cache) o espera 50 ms
Petición 3  (Miss) ---> Intenta adquirir mutex -> ¡OCUPADO! -> Devuelve Stale Cache

Aplicación práctica#

1. Página principal de un marketplace de alto tráfico: Caché del árbol de categorías agregado y filtros de marcas en Redis con invalidación agrupada al publicar nuevos productos.
2. Integración con pasarelas de pago y logística externa: Almacenamiento de matrices de tarifas y tipos de cambio en caché persistente con protección contra Thundering Herd durante picos de compras.
3. Contadores de visitas y analítica: Uso de incrementos atómicos wp_cache_incr() en Redis en lugar de ejecutar pesados UPDATE wp_postmeta SET meta_value = meta_value + 1 en cada visita.
4. Aislamiento en entornos multi-tenant (Multi-Site / Multi-Environment): Uso del prefijo de sales WP_CACHE_KEY_SALT en wp-config.php para evitar colisiones de claves entre staging y producción en una misma instancia de Redis.

Cómo funciona#

Al diseñar una estrategia de caché, es esencial diferenciar el trabajo con base de datos del trabajo en memoria:

Por qué wp_cache_flush() en producción es una catástrofe#

Invocar wp_cache_flush() purga absolutamente toda la base de datos en Redis. Al milisegundo siguiente, cientos de peticiones HTTP entrantes se encuentran con una caché completamente vacía. La carga sobre MySQL se multiplica por 50–100 al instante: el servidor entra en swapping severo, agota el pool de max_connections y colapsa con el error «Error establishing a database connection».

Los estándares de 2026 prohíben el vaciado global de caché. En su lugar, se implementa Key Versioning (versionado de claves por grupo):

// Invalidación de grupo sin vaciar Redis: simplemente incrementamos la versión del grupo
$version = wp_cache_incr('group_version', 1, 'catalog_meta');
// Todas las claves subsiguientes se construyen como "catalog_items:v{$version}"

Artefacto de producción: Enterprise Resilient Cache Manager#

A continuación se muestra un gestor de caché resiliente en PHP 8.4+ que implementa protección contra Cache Stampede mediante mutex distribuidos, versionado de grupos de claves y deduplicación segura.

<?php
declare(strict_types=1);

namespace AgenticLab\Performance;

use Closure;

/**
* Enterprise Resilient Cache Manager.
* 
* Gestor de caché tolerante a fallos con protección contra Thundering Herd / Dogpile.
*
* Author: Artur Yusupov (Fullstack Agentic Lab)
*/
final class AgenticResilientCache {
  private const string LOCK_GROUP = 'agentic_cache_locks';
  private const int DEFAULT_LOCK_TTL = 15; // Segundos de bloqueo durante el cálculo

  /**
   * Ejecuta una operación costosa garantizando protección contra Cache Stampede.
   *
   * @template T
   * @param string $key Clave de caché
   * @param string $group Grupo de caché
   * @param int $ttl Tiempo de vida en segundos
   * @param Closure(): T $compute Función de cálculo ejecutada ante un miss
   * @return T
   */
  public static function remember(
      string $key,
      string $group,
      int $ttl,
      Closure $compute
  ): mixed {
      $versioned_key = self::build_versioned_key($key, $group);
      $found = false;
      
      /** @var mixed $cached */
      $cached = wp_cache_get($versioned_key, $group, false, $found);

      if ($found && $cached !== false) {
          /** @var T */
          return $cached;
      }

      // Sin caché. Intentar adquirir el mutex distribuido atómico
      $lock_key = "lock:{$versioned_key}";
      $is_locked = !wp_cache_add($lock_key, 1, self::LOCK_GROUP, self::DEFAULT_LOCK_TTL);

      if ($is_locked) {
          // Otro proceso de trabajo ya está calculando el dato.
          // Intentar servir datos obsoletos (Stale-While-Revalidate)
          $stale_key = "stale:{$versioned_key}";
          $stale_found = false;
          $stale_data = wp_cache_get($stale_key, $group, false, $stale_found);

          if ($stale_found && $stale_data !== false) {
              /** @var T */
              return $stale_data;
          }

          // Si no hay datos obsoletos, esperar 50 ms y volver a intentar la lectura
          usleep(50000);
          $retry_cached = wp_cache_get($versioned_key, $group, false, $found);
          if ($found && $retry_cached !== false) {
              /** @var T */
              return $retry_cached;
          }
      }

      // Hemos adquirido el mutex o finalizó la espera: ejecutar el cálculo
      try {
          /** @var T $result */
          $result = $compute();

          // Guardar los datos frescos
          wp_cache_set($versioned_key, $result, $group, $ttl);

          // Guardar copia de respaldo stale con doble TTL
          wp_cache_set("stale:{$versioned_key}", $result, $group, $ttl * 2);

          return $result;
      } finally {
          // Liberar obligatoriamente el mutex de bloqueo
          wp_cache_delete($lock_key, self::LOCK_GROUP);
      }
  }

  /**
   * Invalidación instantánea de todo un grupo de caché sin llamar al peligroso wp_cache_flush().
   */
  public static function invalidate_group(string $group): void {
      $version_key = "version:{$group}";
      $current_version = (int)wp_cache_get($version_key, 'group_versions');

      if ($current_version === 0) {
          wp_cache_set($version_key, 2, 'group_versions', 0);
      } else {
          wp_cache_incr($version_key, 1, 'group_versions');
      }
  }

  /**
   * Construye la clave teniendo en cuenta la versión actual del grupo.
   */
  private static function build_versioned_key(string $key, string $group): string {
      $version_key = "version:{$group}";
      $version = wp_cache_get($version_key, 'group_versions');

      if ($version === false) {
          $version = 1;
          wp_cache_set($version_key, 1, 'group_versions', 0);
      }

      return "v{$version}:{$key}";
  }
}

Errores comunes#

Resumen del arquitecto#

Una estrategia de caché de alto rendimiento en soluciones empresariales sobre WordPress se fundamenta en tres pilares:

• Erradicación de transients en MySQL: Integración innegociable de Redis / Valkey mediante object-cache.php con política de memoria allkeys-lru.
• Blindaje contra el efecto Dogpile: Uso de mutex atómicos distribuidos (wp_cache_add) y algoritmos de recálculo probabilístico para claves críticas.
• Invalidación segura: Prohibición de llamadas globales a wp_cache_flush() a favor del versionado granular de grupos (Key Versioning).