Inicialización y ciclo de vida del plugin

Este documento describe cómo se carga el plugin ADP Car Market Hub, qué ocurre durante la activación, desactivación y desinstalación, y qué migraciones ejecuta el plugin a medida que se inicia.

Cuándo utilizar este documento

Lea este documento si necesita:

• Rastrear el orden en el que se ejecuta el código del plugin durante una solicitud de WordPress.
• Comprender qué acciones se ejecutan al activar y desactivar (capacidades, páginas por defecto, tablas personalizadas, eventos programados).
• Planificar una actualización o solucionar problemas de una migración que no se aplicó.
• Decidir dónde enganchar (hook) código personalizado para que se ejecute después de que los servicios del plugin estén disponibles.

Descripción general

El plugin se inicia desde el archivo principal adp-car-market-hub.php. Ese archivo es corto por diseño y solo realiza tareas que deben ocurrir en el momento de la carga del archivo. Todo el código de las características se carga a través de un cargador automático de estilo PSR-4 y se conecta mediante el singleton AS24CI\Plugin en la acción plugins_loaded.

Constantes definidas en el momento de la carga

adp-car-market-hub.php define las siguientes constantes antes de que se ejecute cualquier hook:

• AS24CI_VERSION — Versión actual del plugin (mantenida en sincronía con la cabecera del plugin y readme.txt).
• AS24CI_PLUGIN_FILE — Ruta absoluta al archivo principal del plugin.
• AS24CI_PLUGIN_DIR — Directorio del plugin (con barra diagonal final).
• AS24CI_PLUGIN_URL — URL al directorio del plugin, útil para la cola de recursos (assets).

El archivo también llama a require_once AS24CI_PLUGIN_DIR . 'src/Core/Helpers.php' para cargar ayudantes procedimentales compartidos y define condicionalmente los ayudantes globales as24ci_format() y as24ci_get_available_ai_models() si no se ha declarado antes ninguna función con el mismo nombre.

Cargador automático (Autoloader)

Inmediatamente después de las constantes, el archivo registra un pequeño cargador automático compatible con PSR-4 para el espacio de nombres AS24CI\. Los nombres de las clases se asignan a nombres de archivo con el formato class-as24ci-<lower-dashed-name>.php. El cargador automático busca primero en includes/ y recurre a includes/admin/ para las clases exclusivas de administración.

Registro de hooks en el momento de la carga

El archivo principal registra los siguientes hooks antes de que se ejecute cualquier código de características:

El archivo principal también inicia el módulo Content Studio en el momento de la carga, independientemente del enrutador de AS24CI\Plugin:

• register_activation_hook → AS24CI\Content_Studio_Repository::maybe_create_tables (crea las tablas de Content Studio al activar).
• admin_menu (prioridad 30) → AS24CI\Admin_Tab_Content_Studio::register_menu.
• plugins_loaded (prioridad 20) → AS24CI\Content_Studio_Admin_Worker::register_hooks.

El intervalo personalizado de WP-Cron se registra incondicionalmente para que WordPress siempre lo conozca, incluso cuando los interruptores de características individuales que lo utilizan estén desactivados.

Secuencia de inicio (solicitud normal)

Cuando WordPress carga el plugin durante una solicitud normal, se producen los siguientes pasos en orden:

1. Se incluye el archivo principal; se registran las constantes, el cargador automático y los hooks enumerados anteriormente.
2. WordPress dispara plugins_loaded en la prioridad 1: as24ci_load_textdomain() ejecuta load_plugin_textdomain() para que las traducciones estén disponibles antes de que se renderice cualquier cadena traducible.
3. WordPress dispara plugins_loaded en la prioridad por defecto: AS24CI\Plugin::init() construye el singleton.
4. El constructor de AS24CI\Plugin: - Instancia los servicios compartidos: Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler. - Llama a Vehicle_Field_Resolver::set_repository() para que el resolvedor central de campos pueda leer de la tabla de vehículos. - Llama a Vehicle_Deleter::set_repository() y Vehicle_Deleter::register_hooks() para que cada ruta de eliminación permanente (WordPress nativo, sincronización completa del importador, acción en lote) pase por una única limpieza idempotente. - Llama a register_hooks() para conectar todas las características para la solicitud actual.
5. register_hooks() conecta dos callbacks de admin_init (se conectan durante plugins_loaded pero solo se disparan en un admin_init posterior en wp-admin): - AS24CI\Plugin::maybe_upgrade_caps() — garantiza que existan los roles y las capacidades para la versión actual del plugin. - AS24CI\Plugin::maybe_upgrade() — ejecuta las migraciones de opciones/datos.
6. register_hooks() registra entonces los hooks propios de cada subsistema: - Siempre activos: CPT, Taxonomies, Leads_CPT, Contact_Form, Templates, Assets, Ajax, Archive_Filters, Cron_Endpoint, License_Manager, License_Refresh_Signal, Webhooks, Analytics, Ai_Assistant, Data_Quality_Scanner, Pricing_Engine (con programación diaria), Financing_Calculator, Rest_Api, Locations, Seller_Profile_Fields, además del programador. El Updater privado también se conecta aquí, restringido a los contextos de administración / WP-Cron / WP-CLI. - Restringidos por opciones de características en AS24CI\Options: Schema (más Seo_Compatibility), Sitemap, Social_Share, Pdf_Datasheet, Favorites, Compare, Export, Bulk_Actions, Search_Agent. - Solo administración (is_admin() verdadero): el controlador AS24CI\Admin, Admin_Team (CMH Team), Update_Visibility y Admin_Setup_Wizard, y — cuando Options::FEATURE_DASHBOARD_WIDGET está habilitado — el widget del dashboard.
7. WordPress continúa con el resto del ciclo de vida de la solicitud. La mayoría de las clases de características registran hooks adicionales en acciones posteriores como init (tipos de contenido personalizados, taxonomías, creación de tablas para los Agentes de Búsqueda), rest_api_init (rutas REST), wp_footer (píxel de seguimiento de analytics) o admin_init (actualizaciones de tablas exclusivas de administración).

Activación

AS24CI\Plugin::activate() está registrado con register_activation_hook y se ejecuta una vez cuando un administrador activa el plugin. Realiza el siguiente trabajo, en orden:

1. Llama a seed_safe_defaults(), que utiliza add_option() para instalar valores por defecto conservadores para la primera configuración. Los valores existentes nunca se sobrescriben. Valores por defecto destacados: - as24ci_default_currency = EUR. - as24ci_default_post_status = draft para que los administradores puedan revisar los mapeos antes de publicar. - as24ci_max_images = 30 (un límite finito en lugar de ilimitado). - as24ci_full_sync = 0 (la eliminación permanente sigue siendo opcional). - Las características orientadas al frontend (sitemap, schema, favoritos, comparador, financiación, widget del dashboard, exportación, carga diferida, gestor de diseño) se activan por defecto; las características de seguimiento, externas, por lotes y de riesgo (analytics, REST API, AI Assistant, compartir en redes sociales, PDF datasheet, prueba de conducción) se desactivan por defecto.
2. Llama a add_option( Options::SETUP_FIRST_ACTIVATION_AT, gmdate('c') ) para registrar la marca de tiempo de la primera activación utilizada por el aviso de administración del Asistente de configuración. Debido a que add_option() no realiza ninguna acción cuando el valor ya existe, las reactivaciones conservan la fecha original.
3. Llama a ensure_roles_and_caps() que: - Crea el rol as24ci_editor si no existe. - Otorga el conjunto de capacidades as24ci_car / as24ci_cars tanto a as24ci_editor como a administrator. - Añade la capacidad manage_as24_imports (la constante Plugin::CAP_MANAGE) únicamente a los administradores. Esta capacidad restringe la interfaz de usuario del importador, los ajustes, las herramientas y los logs.
4. Establece as24ci_caps_version en 1 para que la migración de capacidades no se ejecute de nuevo en solicitudes posteriores.
5. Establece as24ci_db_version en 5 para que las migraciones de datos definidas en maybe_upgrade() se omitan en una instalación nueva.
6. Llama a maybe_create_default_pages() para crear opcionalmente las páginas Cars, Compare Cars y Favorites y almacenar sus IDs de publicación en as24ci_page_archive_id, as24ci_page_compare_id y as24ci_page_favorites_id. El comportamiento está restringido por la opción as24ci_create_default_pages y los filtros as24ci_default_pages_enabled y as24ci_default_pages.
7. Llama a Analytics::maybe_create_table() para crear la tabla de analytics.
8. Llama a Vehicle_Repository::maybe_create_table() para crear la tabla dedicada de vehículos.
9. Programa la limpieza diaria de retención de analytics (as24ci_daily_cleanup) si no está ya programada.
10. Llama a License_Manager::ensure_cron_scheduled() para programar el evento diario de revalidación de licencia (as24ci_license_refresh).
11. Llama a CPT::register_post_type() y luego a flush_rewrite_rules() para que el archivo /cars funcione inmediatamente después de la activación.
12. Registra Plugin activated (v<version>). a través de AS24CI\Logger.

Las tablas de Content Studio se crean mediante un hook de activación independiente (Content_Studio_Repository::maybe_create_tables) registrado en el archivo principal del plugin, no por Plugin::activate().

activate() no introduce deliberadamente URLs de API por defecto. La falta de configuración se muestra a través de la interfaz de usuario de estado del sistema / salud y a través de errores del cliente cuando se ejecuta el importador.

Migraciones de capacidades y datos

Se conectan dos métodos estáticos en admin_init (no en plugins_loaded) para mantener las instalaciones existentes sincronizadas con la versión actual del plugin. Conectarse a admin_init evita obligar a que la pila de autenticación conectable se cargue temprano en cada solicitud:

• maybe_upgrade_caps() — Conectado en admin_init. Protege contra solicitudes AJAX, cron y REST (retornando temprano en esos contextos) y utiliza una protección estática por solicitud para que el cuerpo de la migración se ejecute como máximo una vez. No está restringido por manage_options. Compara as24ci_caps_version con el valor de destino (1 en el momento de escribir este documento) y vuelve a ejecutar ensure_roles_and_caps() si es necesario.
• maybe_upgrade() — Conectado en admin_init; retorna temprano a menos que is_admin(). Compara as24ci_db_version con el valor de destino (5) y aplica cualquier paso de migración pendiente. Cada paso es idempotente:
• Migración 1: solo marcador, sin cambios de datos.
• Migración 2: fuerza la opción de consentimiento de analytics (Options::ANALYTICS_REQUIRE_CONSENT) a 0. Los administradores pueden volver a habilitarla desde la interfaz de ajustes.
• Migración 3: migra la opción heredada FINANCING_PLACEMENT a las nuevas zonas del Gestor de diseño. La migración solo escribe en una zona del Gestor de diseño si esa zona aún no se ha guardado, por lo que se conservan los diseños existentes.
• Migración 4: vuelve a aplicar seed_safe_defaults() para que las instalaciones existentes reciban los nuevos valores por defecto seguros sin sobrescribir los valores que el administrador ya haya establecido.
• Migración 5: protege los secretos en texto plano en reposo. Los secretos reversibles (Options::CLIENT_SECRET, Options::HUB_API_KEY, Options::WEBHOOK_SECRET) se envuelven a través de Secrets::encrypt(), y el token de cron (Options::CRON_TOKEN) se reemplaza con su hash HMAC con clave a través de Secrets::hash_token(). El proceso de migración es idempotente (se omiten las filas que ya están protegidas) y el token de acceso OAuth almacenado en caché se borra para que se vuelva a almacenar a través de la ruta cifrada. Después de todos los pasos aplicables, la opción se actualiza a la versión de destino actual.

---

---

Desactivación

AS24CI\Plugin::deactivate() se ejecuta una vez cuando un administrador desactiva el plugin. Los datos existentes se conservan. El método:

1. Llama a wp_clear_scheduled_hook( Scheduler::CRON_HOOK ) para eliminar los eventos as24ci_scheduled_import pendientes.
2. Llama a wp_clear_scheduled_hook( Analytics::ANALYTICS_CLEANUP_CRON_HOOK ) para eliminar el evento de retención de analíticas diario.
3. Llama a Ai_Assistant::clear_ai_queue_schedule() para eliminar el evento de cron de la cola de IA en segundo plano.
4. Llama a Pricing_Engine::clear_schedule() para eliminar el evento de cron diario del motor de precios.
5. Llama a License_Manager::clear_cron() para eliminar el evento diario de revalidación de licencia (as24ci_license_refresh).
6. Llama a wp_clear_scheduled_hook( 'as24ci_competitor_watcher_cron' ) únicamente como limpieza heredada (legacy) — la característica Competitor Watcher (y su clase) ha sido eliminada; el nombre del hook está codificado de forma fija aquí para que cualquier evento programado remanente en instalaciones actualizadas desde versiones anteriores siga limpiándose.
7. Elimina el transient Scheduler::LOCK_TRANSIENT (as24ci_cron_import_running) en caso de que el plugin se desactive mientras una importación está en curso.
8. Llama a flush_rewrite_rules() y registra Plugin deactivated.

Debido a que la desactivación no altera las tablas de la base de datos, los custom post types o las opciones, al reactivar el plugin se restaura el estado anterior.

Desinstalación

Cuando el plugin se elimina desde el administrador de WordPress (no solo se desactiva), WordPress ejecuta uninstall.php. El script:

1. Carga AS24CI\Options (si el archivo existe) para que la lista autoritativa de claves de opciones se pueda derivar de Options::get_all_keys(), más un pequeño conjunto de claves adicionales (as24ci_models_cache_keys, as24ci_page_archive_id, as24ci_page_compare_id y la heredada as24ci_api_total_cache). Se utiliza una lista de respaldo codificada de forma fija si la clase no se puede cargar.
2. Elimina los transients del plugin (as24ci_access_token, as24ci_cron_import_running, as24ci_image_queue_running).
3. Cancela la programación de los eventos pendientes para as24ci_scheduled_import y as24ci_daily_cleanup.
4. Lee la opción as24ci_delete_data_on_uninstall. Cuando el valor es 1, el script elimina: - Todos los posts as24ci_car (forzado). - Todos los IDs de adjuntos almacenados en el postmeta _as24ci_image_ids de cada vehículo. Los adjuntos de galería manuales (_as24ci_manual_image_ids) no se eliminan intencionadamente. - El adjunto de imagen destacada de cada vehículo (limpieza defensiva). - Todos los posts as24ci_lead. - Las páginas de Vehículos, Comparar y Favoritos creadas durante la activación.
5. Siempre elimina (drop) las tablas personalizadas (independientemente de la casilla de verificación de exclusión voluntaria): - {$wpdb->prefix}as24ci_analytics - {$wpdb->prefix}as24_vehicles - {$wpdb->prefix}as24ci_search_agents - {$wpdb->prefix}as24ci_content_studio_assets - {$wpdb->prefix}as24ci_content_studio_jobs Las opciones de versión de esquema correspondientes (as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version) también se eliminan.
6. Elimina todas las claves de opciones recopiladas para el sitio.
7. En instalaciones multisitio, la misma rutina se ejecuta una vez por sitio a través de switch_to_blog().

Referencia de configuración

El comportamiento de bootstrap y ciclo de vida está influenciado por las siguientes opciones (todas definidas como constantes en AS24CI\Options). El catálogo completo está documentado en el documento Almacenamiento de Opciones y Ajustes; aquí solo se enumeran las entradas relevantes para el ciclo de vida.

Notas operativas

• register_activation_hook se activa solo cuando un administrador activa el plugin desde la pantalla de Plugins. Actualizar los archivos del plugin no activa la activación; es por eso que existe maybe_upgrade().
• Debido a que maybe_upgrade() y maybe_upgrade_caps() están enganchados en admin_init y solo se ejecutan durante cargas de páginas de administración reales (no AJAX, REST o cron), las solicitudes exclusivas del frontend no asumen el coste de las comprobaciones de migración. La primera carga de una página de administración después de una actualización aplica cualquier migración pendiente.
• Los TTL de bloqueo de WP-Cron del plugin son conservadores: el bloqueo de importación (Scheduler::LOCK_TTL) es de aproximadamente 40 minutos. Si un proceso se interrumpe a mitad de la ejecución, el bloqueo se libera automáticamente cuando el transient expira. La recuperación manual se describe en la documentación del programador.
• La desinstalación siempre elimina las tablas de analíticas, vehículos y agentes de búsqueda porque pueden contener datos personales o de visitantes. Los posts y las opciones solo se eliminan cuando el administrador ha optado por ello a través del ajuste as24ci_delete_data_on_uninstall.

Resolución de problemas

• La activación no crea la página de Vehículos. Confirme que as24ci_create_default_pages está establecido en 1 y que ningún tema u otro plugin está filtrando as24ci_default_pages_enabled a false. La página tampoco se vuelve a crear si ya existe una página con el mismo título; en ese caso, se reutiliza su ID.
• Faltan capacidades personalizadas para un administrador. Visite cualquier página de administración para que maybe_upgrade_caps() pueda ejecutarse en admin_init, o elimine temporalmente as24ci_caps_version de wp_options para forzar que la migración se vuelva a ejecutar. La migración se omite en solicitudes AJAX, REST y cron, por lo que debe ejecutarse durante una carga de página de administración real.
• No se aplicó un paso de migración. Compruebe el valor de as24ci_db_version. Si ya es igual al objetivo, la migración ya se ha ejecutado. Reduzca el valor manualmente solo si comprende las consecuencias para su instalación.
• El archivo /cars devuelve un error 404 inmediatamente después de la activación. La activación ya llama a flush_rewrite_rules(). Si el archivo sigue sin ser accesible, visite Ajustes → Enlaces permanentes y guarde una vez para forzar a WordPress a reconstruir su caché de reescritura.

Documentos relacionados

• Descripción general de la arquitectura
• Modelo de datos
• Esquema de la base de datos
• Descripción general de la sección