Initialisation et cycle de vie du plugin

Ce document décrit comment le plugin ADP Car Market Hub se charge, ce qui se passe lors de l'activation, de la désactivation et de la désinstallation, ainsi que les migrations exécutées par le plugin lors de son initialisation.

Quand utiliser ce document

Lisez ce document si vous devez :

• Suivre l'ordre dans lequel le code du plugin s'exécute lors d'une requête WordPress.
• Comprendre quelles actions s'exécutent lors de l'activation et de la désactivation (capacités, pages par défaut, tables personnalisées, événements planifiés).
• Planifier une mise à niveau ou résoudre un problème lié à une migration qui ne s'est pas appliquée.
• Décider où greffer du code personnalisé afin qu'il s'exécute après que les services du plugin sont disponibles.

Aperçu

Le plugin est initialisé à partir du fichier principal adp-car-market-hub.php. Ce fichier est court par conception et n'effectue que le travail qui doit impérativement avoir lieu au moment du chargement du fichier. Tout le code des fonctionnalités est chargé via un autoloader de style PSR-4 et connecté par le singleton AS24CI\Plugin sur l'action plugins_loaded.

Constantes définies au chargement

adp-car-market-hub.php définit les constantes suivantes avant l'exécution de tout hook :

• AS24CI_VERSION — Version actuelle du plugin (maintenue synchronisée avec l'en-tête du plugin et readme.txt).
• AS24CI_PLUGIN_FILE — Chemin absolu vers le fichier principal du plugin.
• AS24CI_PLUGIN_DIR — Répertoire du plugin (avec barre oblique finale).
• AS24CI_PLUGIN_URL — URL du répertoire du plugin, utile pour la mise en file d'attente des assets.

Le fichier appelle également require_once AS24CI_PLUGIN_DIR . 'src/Core/Helpers.php' pour charger les assistants procéduraux partagés et définit de manière conditionnelle les assistants globaux as24ci_format() et as24ci_get_available_ai_models() si aucune fonction du même nom n'a été déclarée auparavant.

Autoloader

Immédiatement après les constantes, le fichier enregistre un petit autoloader compatible PSR-4 pour l'espace de noms AS24CI\. Les noms de classes sont mappés à des noms de fichiers de la forme class-as24ci-<lower-dashed-name>.php. L'autoloader cherche d'abord dans includes/ et se rabat sur includes/admin/ pour les classes réservées à l'administration.

Enregistrement des hooks au chargement

Le fichier principal enregistre les hooks suivants avant l'exécution de tout code de fonctionnalité :

Le fichier principal initialise également le module Content Studio au moment du chargement, indépendamment du routeur AS24CI\Plugin :

• register_activation_hook → AS24CI\Content_Studio_Repository::maybe_create_tables (crée les tables Content Studio lors de l'activation).
• admin_menu (priorité 30) → AS24CI\Admin_Tab_Content_Studio::register_menu.
• plugins_loaded (priorité 20) → AS24CI\Content_Studio_Admin_Worker::register_hooks.

L'intervalle WP-Cron personnalisé est enregistré de manière inconditionnelle afin que WordPress en ait toujours connaissance, même lorsque les options de fonctionnalités individuelles qui l'utilisent sont désactivées.

Séquence d'initialisation (requête normale)

Lorsque WordPress charge le plugin lors d'une requête normale, les étapes suivantes se déroulent dans l'ordre :

1. Le fichier principal est inclus ; les constantes, l'autoloader et les hooks listés ci-dessus sont enregistrés.
2. WordPress déclenche plugins_loaded à la priorité 1 : as24ci_load_textdomain() exécute load_plugin_textdomain() afin que les traductions soient disponibles avant le rendu de toute chaîne traduisible.
3. WordPress déclenche plugins_loaded à la priorité par défaut : AS24CI\Plugin::init() construit le singleton.
4. Le constructeur de AS24CI\Plugin : - Instancie les services partagés : Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler. - Appelle Vehicle_Field_Resolver::set_repository() pour que le résolveur de champs central puisse lire à partir de la table des véhicules. - Appelle Vehicle_Deleter::set_repository() et Vehicle_Deleter::register_hooks() afin que chaque chemin de suppression définitive (WordPress natif, synchronisation complète de l'importateur, action groupée) passe par un nettoyage unique et idempotent. - Appelle register_hooks() pour connecter toutes les fonctionnalités pour la requête en cours.
5. register_hooks() connecte deux callbacks admin_init (ils sont connectés pendant plugins_loaded mais ne se déclenchent que lors d'un admin_init ultérieur dans wp-admin) : - AS24CI\Plugin::maybe_upgrade_caps() — garantit que les rôles et les capacités existent pour la version actuelle du plugin. - AS24CI\Plugin::maybe_upgrade() — exécute les migrations d'options/données.
6. register_hooks() enregistre ensuite les propres hooks de chaque sous-système : - Toujours activés : 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 (avec planification quotidienne), Financing_Calculator, Rest_Api, Locations, Seller_Profile_Fields, plus le planificateur. Le service privé Updater est également connecté ici, limité aux contextes d'administration / WP-Cron / WP-CLI. - Limités par les options de fonctionnalités sur AS24CI\Options : Schema (plus Seo_Compatibility), Sitemap, Social_Share, Pdf_Datasheet, Favorites, Compare, Export, Bulk_Actions, Search_Agent. - Administration uniquement (is_admin() vrai) : le contrôleur AS24CI\Admin, Admin_Team (CMH Team), Update_Visibility et Admin_Setup_Wizard, et — lorsque Options::FEATURE_DASHBOARD_WIDGET est activé — le widget du tableau de bord.
7. WordPress poursuit le reste du cycle de vie de la requête. La plupart des classes de fonctionnalités enregistrent des hooks supplémentaires sur des actions ultérieures telles que init (types de publication, taxonomies, création de tables pour les alertes de recherche), rest_api_init (routes REST), wp_footer (pixel de suivi analytique) ou admin_init (mises à niveau de tables réservées à l'administration).

Activation

AS24CI\Plugin::activate() est enregistré avec register_activation_hook et s'exécute une fois lorsqu'un administrateur active le plugin. Il effectue le travail suivant, dans l'ordre :

1. Appelle seed_safe_defaults(), qui utilise add_option() pour installer des valeurs par défaut prudentes pour la première configuration. Les valeurs existantes ne sont jamais écrasées. Valeurs par défaut notables : - as24ci_default_currency = EUR. - as24ci_default_post_status = draft afin que les administrateurs puissent vérifier les mappings avant la publication. - as24ci_max_images = 30 (une limite définie plutôt qu'illimitée). - as24ci_full_sync = 0 (la suppression définitive reste facultative). - Les fonctionnalités orientées frontend (sitemap, schema, favoris, comparaison, financement, widget de tableau de bord, export, lazy loading, gestionnaire de mise en page) sont activées par défaut ; les fonctionnalités de suivi, externes, par lots et risquées (analyses, API REST, Assistant IA, partage social, PDF datasheet, essai routier) sont désactivées par défaut.
2. Appelle add_option( Options::SETUP_FIRST_ACTIVATION_AT, gmdate('c') ) pour enregistrer l'horodatage de la première activation utilisé par la notification d'administration de l'assistant de configuration. Comme add_option() est sans effet lorsque la valeur existe, les réactivations préservent la date d'origine.
3. Appelle ensure_roles_and_caps() qui : - Crée le rôle as24ci_editor s'il n'existe pas. - Accorde l'ensemble de capacités as24ci_car / as24ci_cars à la fois à as24ci_editor et à administrator. - Ajoute la capacité manage_as24_imports (la constante Plugin::CAP_MANAGE) aux administrateurs uniquement. Cette capacité restreint l'accès à l'interface utilisateur de l'importateur, des réglages, des outils et des journaux.
4. Définit as24ci_caps_version sur 1 afin que la migration des capacités ne s'exécute pas à nouveau lors des requêtes ultérieures.
5. Définit as24ci_db_version sur 5 afin que les migrations de données définies dans maybe_upgrade() soient ignorées lors d'une nouvelle installation.
6. Appelle maybe_create_default_pages() pour créer éventuellement les pages Cars, Compare Cars et Favorites et stocker leurs ID de publication dans as24ci_page_archive_id, as24ci_page_compare_id et as24ci_page_favorites_id. Ce comportement est contrôlé par l'option as24ci_create_default_pages et les filtres as24ci_default_pages_enabled et as24ci_default_pages.
7. Appelle Analytics::maybe_create_table() pour créer la table d'analyses.
8. Appelle Vehicle_Repository::maybe_create_table() pour créer la table dédiée aux véhicules.
9. Planifie le nettoyage quotidien de la rétention des analyses (as24ci_daily_cleanup) s'il n'est pas déjà planifié.
10. Appelle License_Manager::ensure_cron_scheduled() pour planifier l'événement quotidien de re-validation de licence (as24ci_license_refresh).
11. Appelle CPT::register_post_type() puis flush_rewrite_rules() pour que l'archive /cars fonctionne immédiatement après l'activation.
12. Enregistre Plugin activated (v<version>). via AS24CI\Logger.

Les tables Content Studio sont créées par un hook d'activation distinct (Content_Studio_Repository::maybe_create_tables) enregistré dans le fichier principal du plugin, et non par Plugin::activate().

activate() ne pré-remplit délibérément pas les URL d'API par défaut. Les configurations manquantes sont signalées via l'interface utilisateur d'état du système / de santé et par des erreurs client lors de l'exécution de l'importateur.

Migration des capacités et des données

Deux méthodes statiques sont connectées sur admin_init (et non plugins_loaded) pour maintenir les installations existantes synchronisées avec la version actuelle du plugin. L'utilisation de admin_init évite de forcer le chargement précoce de la pile d'authentification pluggable à chaque requête :

• maybe_upgrade_caps() — Connecté sur admin_init. Il protège contre les requêtes AJAX, cron et REST (en retournant immédiatement dans ces contextes) et utilise un verrou statique par requête afin que le corps de la migration ne s'exécute au plus qu'une seule fois. Il n'est pas limité par manage_options. Compare as24ci_caps_version à la valeur cible (1 au moment de la rédaction) et réexécute ensure_roles_and_caps() si nécessaire.
• maybe_upgrade() — Connecté sur admin_init ; retourne immédiatement à moins que is_admin(). Compare as24ci_db_version à la valeur cible (5) et applique toutes les étapes de migration en attente. Chaque étape est idempotente :
• Migration 1 : marqueur uniquement, aucune modification de données.
• Migration 2 : force l'option de consentement aux analyses (Options::ANALYTICS_REQUIRE_CONSENT) sur 0. Les administrateurs peuvent la réactiver depuis l'interface des réglages.
• Migration 3 : migre l'ancienne option FINANCING_PLACEMENT vers les nouvelles zones du gestionnaire de mise en page. La migration n'écrit dans une zone du gestionnaire de mise en page que si cette zone n'a pas encore été enregistrée, préservant ainsi les mises en page existantes.
• Migration 4 : réapplique seed_safe_defaults() afin que les installations existantes reçoivent toutes les nouvelles valeurs par défaut sécurisées sans écraser les valeurs que l'administrateur a déjà définies.
• Migration 5 : protège les secrets en texte clair stockés. Les secrets réversibles (Options::CLIENT_SECRET, Options::HUB_API_KEY, Options::WEBHOOK_SECRET) sont enveloppés via Secrets::encrypt(), et le jeton cron (Options::CRON_TOKEN) est remplacé par son hachage HMAC clé via Secrets::hash_token(). La migration est idempotente (les lignes déjà protégées sont ignorées) et le jeton d'accès OAuth mis en cache est effacé afin d'être stocké à nouveau via le chemin chiffré. Après toutes les étapes applicables, l'option est mise à jour vers la version cible actuelle.

---

Désactivation

AS24CI\Plugin::deactivate() s'exécute une fois lorsqu'un administrateur désactive le plugin. Les données existantes sont conservées. La méthode :

1. Appelle wp_clear_scheduled_hook( Scheduler::CRON_HOOK ) pour supprimer les événements as24ci_scheduled_import en attente.
2. Appelle wp_clear_scheduled_hook( Analytics::ANALYTICS_CLEANUP_CRON_HOOK ) pour supprimer l'événement quotidien de rétention des analyses.
3. Appelle Ai_Assistant::clear_ai_queue_schedule() pour supprimer l'événement cron de la file d'attente de l'Assistant IA en arrière-plan.
4. Appelle Pricing_Engine::clear_schedule() pour supprimer l'événement cron quotidien du moteur de tarification.
5. Appelle License_Manager::clear_cron() pour supprimer l'événement quotidien de revalidation de licence (as24ci_license_refresh).
6. Appelle wp_clear_scheduled_hook( 'as24ci_competitor_watcher_cron' ) uniquement pour un nettoyage hérité (legacy) — la fonctionnalité Competitor Watcher (et sa classe) ayant été supprimée ; le nom du hook est codé en dur ici afin que tout événement planifié restant sur les installations mises à niveau depuis d'anciennes versions soit tout de même effacé.
7. Supprime le transient Scheduler::LOCK_TRANSIENT (as24ci_cron_import_running) au cas où le plugin serait désactivé pendant qu'un import est en cours.
8. Appelle flush_rewrite_rules() et enregistre Plugin deactivated. dans les journaux.

Comme la désactivation ne touche pas aux tables de la base de données, aux types de publication personnalisés (CPT) ou aux options, la réactivation du plugin rétablit l'état précédent.

Désinstallation

Lorsque le plugin est supprimé de l'administration WordPress (et pas seulement désactivé), WordPress exécute uninstall.php. Le script :

1. Charge AS24CI\Options (si le fichier existe) afin que la liste faisant autorité des clés d'option puisse être dérivée de Options::get_all_keys(), plus un petit ensemble de clés supplémentaires (as24ci_models_cache_keys, as24ci_page_archive_id, as24ci_page_compare_id et l'ancienne clé héritée as24ci_api_total_cache). Une liste de secours codée en dur est utilisée si la classe ne peut pas être chargée.
2. Supprime les transients du plugin (as24ci_access_token, as24ci_cron_import_running, as24ci_image_queue_running).
3. Annule la planification des événements en attente pour as24ci_scheduled_import et as24ci_daily_cleanup.
4. Lit l'option as24ci_delete_data_on_uninstall. Lorsque la valeur est 1, le script supprime : - Tous les posts as24ci_car (suppression forcée). - Tous les ID de pièces jointes stockés dans les postmeta _as24ci_image_ids de chaque voiture. Les pièces jointes manuelles de la galerie (_as24ci_manual_image_ids) ne sont volontairement pas supprimées. - L'image mise en avant de chaque voiture (nettoyage défensif). - Tous les posts as24ci_lead. - Les pages Cars, Compare et Favorites créées lors de l'activation.
5. Supprime toujours les tables personnalisées (quel que soit le choix de l'option d'activation) : - {$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 Les options de version de schéma correspondantes (as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version) sont également supprimées.
6. Supprime toutes les clés d'option collectées pour le site.
7. Sur les installations multisites, la même routine s'exécute une fois par site via switch_to_blog().

Référence de configuration

Le comportement d'initialisation (bootstrap) et de cycle de vie est influencé par les options suivantes (toutes définies comme des constantes sur AS24CI\Options). Le catalogue complet est documenté dans le document Options And Settings Storage ; seules les entrées pertinentes pour le cycle de vie sont répertoriées ici.

Notes opérationnelles

• register_activation_hook est déclenché uniquement lorsqu'un administrateur active le plugin depuis l'écran des Extensions. La mise à jour des fichiers du plugin ne déclenche pas l'activation ; c'est pourquoi maybe_upgrade() existe.
• Étant donné que maybe_upgrade() et maybe_upgrade_caps() sont accrochés sur admin_init et s'exécutent uniquement lors des chargements réels de pages d'administration (pas AJAX, REST ou cron), les requêtes uniquement front-end ne subissent pas le coût des vérifications de migration. Le premier chargement de page d'administration après une mise à jour applique toute migration en attente.
• Les TTL de verrouillage WP-Cron du plugin sont conservateurs : le verrou d'importation (Scheduler::LOCK_TTL) est d'environ 40 minutes. Si un processus est interrompu en cours d'exécution, le verrou est libéré automatiquement à l'expiration du transient. La récupération manuelle est décrite dans la documentation du planificateur.
• La désinstallation supprime toujours les tables d'analyses, de véhicules et d'agents de recherche car elles peuvent contenir des données personnelles ou de visiteurs. Les posts et les options ne sont supprimés que si l'administrateur a activé l'option via le réglage as24ci_delete_data_on_uninstall.

Dépannage

• L'activation ne crée pas la page Cars. Confirmez que as24ci_create_default_pages est défini sur 1 et qu'aucun thème ou autre plugin ne filtre as24ci_default_pages_enabled vers false. La page n'est pas non plus recréée si une page avec le même titre existe déjà ; dans ce cas, son ID est réutilisé.
• Les capacités personnalisées sont manquantes pour un administrateur. Visitez n'importe quelle page d'administration pour que maybe_upgrade_caps() puisse s'exécuter sur admin_init, ou supprimez temporairement as24ci_caps_version de wp_options pour forcer la réexécution de la migration. La migration est ignorée lors des requêtes AJAX, REST et cron, elle doit donc s'exécuter lors d'un chargement réel de page d'administration.
• Une étape de migration ne s'est pas appliquée. Vérifiez la valeur de as24ci_db_version. Si elle est déjà égale à la cible, la migration a déjà été exécutée. Ne baissez la valeur manuellement que si vous comprenez les conséquences pour votre installation.
• L'archive /cars renvoie une erreur 404 immédiatement après l'activation. L'activation appelle déjà flush_rewrite_rules(). Si l'archive n'est toujours pas accessible, visitez Réglages → Permaliens et enregistrez une fois pour forcer WordPress à reconstruire son cache de réécriture.

Documents connexes

• Aperçu de l'architecture
• Modèle de données
• Schéma de la base de données
• Aperçu de la section