From ff5ba25505133fd6ce2c23a45888d687412c2d27 Mon Sep 17 00:00:00 2001
From: FrankZamora <prime.leads.app@gmail.com>
Date: Sun, 7 Dec 2025 12:11:48 -0600
Subject: [PATCH] feat(php): implement cache-first architecture hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add CacheFirstHooksRegistrar that fires roi_theme_before_page_serve
hook on template_redirect priority 0 for singular pages.

- Only fires for anonymous users (cache doesn't apply to logged in)
- Only fires for singular pages (posts, pages, CPTs)
- Provides post_id to external plugins
- Does NOT define DONOTCACHEPAGE (allows page caching)

Plan 1000.01 implementation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../Hooks/CacheFirstHooksRegistrar.php        | 82 +++++++++++++++++++
 functions.php                                 |  6 ++
 2 files changed, 88 insertions(+)
 create mode 100644 Shared/Infrastructure/Hooks/CacheFirstHooksRegistrar.php

diff --git a/Shared/Infrastructure/Hooks/CacheFirstHooksRegistrar.php b/Shared/Infrastructure/Hooks/CacheFirstHooksRegistrar.php
new file mode 100644
index 00000000..08adade1
--- /dev/null
+++ b/Shared/Infrastructure/Hooks/CacheFirstHooksRegistrar.php
@@ -0,0 +1,82 @@
+<?php
+declare(strict_types=1);
+
+namespace ROITheme\Shared\Infrastructure\Hooks;
+
+/**
+ * Registra hooks para arquitectura cache-first.
+ *
+ * Permite que plugins externos evalúen condiciones ANTES de servir páginas,
+ * sin bloquear el cache de WordPress.
+ *
+ * @see openspec/specs/cache-first-architecture/spec.md
+ * @package ROITheme\Shared\Infrastructure\Hooks
+ */
+final class CacheFirstHooksRegistrar
+{
+    /**
+     * Registra los hooks de cache-first.
+     */
+    public function register(): void
+    {
+        add_action('template_redirect', [$this, 'fireBeforePageServe'], 0);
+    }
+
+    /**
+     * Dispara hook para que plugins externos evalúen acceso.
+     *
+     * Solo se dispara para:
+     * - Páginas singulares (posts, pages, CPTs)
+     * - Visitantes NO logueados (cache no aplica a usuarios logueados)
+     *
+     * Los plugins pueden llamar wp_safe_redirect() + exit para bloquear.
+     * Si no hacen nada, la página se sirve normalmente (con cache si disponible).
+     */
+    public function fireBeforePageServe(): void
+    {
+        // No para usuarios logueados (cache no aplica, no tiene sentido evaluar)
+        if (is_user_logged_in()) {
+            return;
+        }
+
+        // Solo páginas singulares
+        if (!is_singular()) {
+            return;
+        }
+
+        // No en admin/ajax/cron/REST
+        if (is_admin() || wp_doing_ajax() || wp_doing_cron()) {
+            return;
+        }
+
+        if (defined('REST_REQUEST') && REST_REQUEST) {
+            return;
+        }
+
+        $post_id = get_queried_object_id();
+
+        if ($post_id > 0) {
+            /**
+             * Hook: roi_theme_before_page_serve
+             *
+             * Permite que plugins externos evalúen condiciones antes de servir página.
+             *
+             * Uso típico:
+             * - Rate limiters (límite de vistas por IP)
+             * - Membership plugins (verificar acceso)
+             * - Geolocation restrictions
+             *
+             * Para bloquear acceso:
+             *   wp_safe_redirect('/pagina-destino/', 302);
+             *   exit;
+             *
+             * Para permitir acceso:
+             *   return; // La página se servirá (con cache si disponible)
+             *
+             * @since 1.0.0
+             * @param int $post_id ID del post/page que se va a servir
+             */
+            do_action('roi_theme_before_page_serve', $post_id);
+        }
+    }
+}
diff --git a/functions.php b/functions.php
index d946a389..25a9f61d 100644
--- a/functions.php
+++ b/functions.php
@@ -174,6 +174,12 @@ try {
     );
     $youtubeFacadeHooksRegistrar->register();
 
+    // === CACHE-FIRST ARCHITECTURE (Plan 1000.01) ===
+    // Hook para plugins externos que necesitan evaluar acceso antes de servir página
+    // @see openspec/specs/cache-first-architecture/spec.md
+    $cacheFirstHooksRegistrar = new \ROITheme\Shared\Infrastructure\Hooks\CacheFirstHooksRegistrar();
+    $cacheFirstHooksRegistrar->register();
+
     // Log en modo debug
     if (defined('WP_DEBUG') && WP_DEBUG) {
         error_log('ROI Theme: Admin Panel initialized successfully');