Bootstrap e ciclo di vita del plugin

Questo documento descrive come si carica il plugin ADP Car Market Hub, cosa succede durante l'attivazione, la disattivazione e la disinstallazione, e quali migrazioni esegue il plugin all'avvio.

Quando usare questo documento

Leggere questo documento se si ha la necessità di:

• Tracciare l'ordine in cui viene eseguito il codice del plugin durante una richiesta WordPress.
• Comprendere quali azioni vengono eseguite all'attivazione e alla disattivazione (funzionalità, pagine predefinite, tabelle personalizzate, eventi pianificati).
• Pianificare un aggiornamento o risolvere i problemi di una migrazione che non è stata applicata.
• Decidere dove agganciare il codice personalizzato in modo che venga eseguito dopo che i servizi del plugin sono disponibili.

Panoramica

Il plugin viene avviato dal file principale adp-car-market-hub.php. Questo file è breve per progettazione ed esegue solo il lavoro che deve avvenire al momento del caricamento del file. Tutto il codice delle funzionalità viene caricato tramite un autoloader in stile PSR-4 e collegato dal singleton AS24CI\Plugin sull'azione plugins_loaded.

Costanti definite al caricamento

adp-car-market-hub.php definisce le seguenti costanti prima dell'esecuzione di qualsiasi hook:

• AS24CI_VERSION — Versione corrente del plugin (mantenuta in sincrono con l'intestazione del plugin e readme.txt).
• AS24CI_PLUGIN_FILE — Percorso assoluto del file principale del plugin.
• AS24CI_PLUGIN_DIR — Directory del plugin (con barra finale).
• AS24CI_PLUGIN_URL — URL della directory del plugin, utile per l'accodamento degli asset.

Il file chiama anche require_once AS24CI_PLUGIN_DIR . 'src/Core/Helpers.php' per caricare gli helper procedurali condivisi e definisce in modo condizionale gli helper globali as24ci_format() e as24ci_get_available_ai_models() se non è stata dichiarata in precedenza alcuna funzione con lo stesso nome.

Autoloader

Subito dopo le costanti, il file registra un piccolo autoloader compatibile con PSR-4 per lo spazio dei nomi AS24CI\. I nomi delle classi sono mappati su nomi di file nel formato class-as24ci-<lower-dashed-name>.php. L'autoloader cerca prima in includes/ e ripiega su includes/admin/ per le classi destinate solo all'amministrazione.

Registrazione degli hook al caricamento

Il file principale registra i seguenti hook prima dell'esecuzione di qualsiasi codice di funzionalità:

Il file principale avvia anche il modulo Content Studio al momento del caricamento, indipendentemente dal router AS24CI\Plugin:

• register_activation_hook → AS24CI\Content_Studio_Repository::maybe_create_tables (crea le tabelle di Content Studio all'attivazione).
• admin_menu (priorità 30) → AS24CI\Admin_Tab_Content_Studio::register_menu.
• plugins_loaded (priorità 20) → AS24CI\Content_Studio_Admin_Worker::register_hooks.

L'intervallo WP-Cron personalizzato viene registrato incondizionatamente in modo che WordPress ne sia sempre a conoscenza, anche quando le singole opzioni delle funzionalità che lo utilizzano sono disabilitate.

Sequenza di bootstrap (richiesta normale)

Quando WordPress carica il plugin durante una normale richiesta, si verificano i seguenti passaggi in ordine:

1. Il file principale viene incluso; vengono registrati le costanti, l'autoloader e gli hook sopra elencati.
2. WordPress attiva plugins_loaded alla priorità 1: as24ci_load_textdomain() esegue load_plugin_textdomain() in modo che le traduzioni siano disponibili prima del rendering di qualsiasi stringa traducibile.
3. WordPress attiva plugins_loaded alla priorità predefinita: AS24CI\Plugin::init() costruisce il singleton.
4. Il costruttore di AS24CI\Plugin: - Istanzia i servizi condivisi: Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler. - Chiama Vehicle_Field_Resolver::set_repository() in modo che il risolutore di campi centrale possa leggere dalla tabella dei veicoli. - Chiama Vehicle_Deleter::set_repository() e Vehicle_Deleter::register_hooks() in modo che ogni percorso di eliminazione permanente (il WordPress nativo, la sincronizzazione completa dell'importatore, l'azione di massa) passi attraverso un'unica pulizia idempotente. - Chiama register_hooks() per collegare tutte le funzionalità per la richiesta corrente.
5. register_hooks() collega due callback admin_init (vengono collegati durante plugins_loaded ma si attivano solo su un successivo admin_init in wp-admin): - AS24CI\Plugin::maybe_upgrade_caps() — assicura che i ruoli e le funzionalità esistano per la versione corrente del plugin. - AS24CI\Plugin::maybe_upgrade() — esegue le migrazioni di opzioni/dati.
6. register_hooks() registra quindi gli hook specifici di ciascun sottosistema: - Sempre attivi: 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 pianificazione giornaliera), Financing_Calculator, Rest_Api, Locations, Seller_Profile_Fields, oltre al pianificatore. Anche il metodo privato Updater è collegato qui, limitato ai contesti admin / WP-Cron / WP-CLI. - Vincolati dalle opzioni delle funzionalità su AS24CI\Options: Schema (più Seo_Compatibility), Sitemap, Social_Share, Pdf_Datasheet, Favorites, Compare, Export, Bulk_Actions, Search_Agent. - Solo per amministratori (is_admin() vero): il controller AS24CI\Admin, Admin_Team (CMH Team), Update_Visibility e Admin_Setup_Wizard, e — quando Options::FEATURE_DASHBOARD_WIDGET è abilitato — il widget della bacheca.
7. WordPress procede con il resto del ciclo di vita della richiesta. La maggior parte delle classi di funzionalità registra hook aggiuntivi su azioni successive come init (tipi di post, tassonomie, creazione di tabelle per gli agenti di ricerca), rest_api_init (rotte REST), wp_footer (pixel di tracciamento di analytics) o admin_init (aggiornamenti delle tabelle solo per l'amministrazione).

Attivazione

AS24CI\Plugin::activate() è registrato con register_activation_hook e viene eseguito una volta quando un amministratore attiva il plugin. Esegue il seguente lavoro, in ordine:

1. Chiama seed_safe_defaults(), che utilizza add_option() per installare valori predefiniti conservativi per la prima configurazione. I valori esistenti non vengono mai sovrascritti. Valori predefiniti degni di nota: - as24ci_default_currency = EUR. - as24ci_default_post_status = draft in modo che gli amministratori possano rivedere le mappature prima della pubblicazione. - as24ci_max_images = 30 (un limite finito anziché illimitato). - as24ci_full_sync = 0 (l'eliminazione definitiva rimane opzionale). - Le funzionalità orientate al frontend (sitemap, schema, preferiti, confronto, finanziamento, widget della bacheca, esportazione, caricamento differito, layout manager) sono attive per impostazione predefinita; le funzionalità di tracciamento, esterne, in batch e a rischio (analytics, REST API, AI Assistant, condivisione social, PDF datasheet, test drive) sono disattivate per impostazione predefinita.
2. Chiama add_option( Options::SETUP_FIRST_ACTIVATION_AT, gmdate('c') ) per registrare il timestamp della prima attivazione utilizzato dall'avviso amministrativo della Configurazione guidata. Poiché add_option() non esegue alcuna operazione quando il valore esiste, le riattivazioni preservano la data originale.
3. Chiama ensure_roles_and_caps() che: - Crea il ruolo as24ci_editor se non esiste. - Concede il set di funzionalità as24ci_car / as24ci_cars sia a as24ci_editor che a administrator. - Aggiunge la funzionalità manage_as24_imports (la costante Plugin::CAP_MANAGE) solo agli amministratori. Questa funzionalità vincola l'interfaccia utente dell'importatore, delle impostazioni, degli strumenti e dei log.
4. Imposta as24ci_caps_version su 1 in modo che la migrazione delle funzionalità non venga eseguita nuovamente sulle richieste successive.
5. Imposta as24ci_db_version su 5 in modo che le migrazioni dei dati definite in maybe_upgrade() vengano saltate su una nuova installazione.
6. Chiama maybe_create_default_pages() per creare facoltativamente le pagine Cars, Compare Cars e Favorites e memorizzare i loro ID post in as24ci_page_archive_id, as24ci_page_compare_id e as24ci_page_favorites_id. Il comportamento è vincolato dall'opzione as24ci_create_default_pages e dai filtri as24ci_default_pages_enabled e as24ci_default_pages.
7. Chiama Analytics::maybe_create_table() per creare la tabella di analytics.
8. Chiama Vehicle_Repository::maybe_create_table() per creare la tabella dedicata ai veicoli.
9. Pianifica la pulizia giornaliera della conservazione dei dati di analytics (as24ci_daily_cleanup) se non è già pianificata.
10. Chiama License_Manager::ensure_cron_scheduled() per pianificare l'evento giornaliero di riconvalida della licenza (as24ci_license_refresh).
11. Chiama CPT::register_post_type() e poi flush_rewrite_rules() in modo che l'archivio /cars funzioni immediatamente dopo l'attivazione.
12. Registra Plugin activated (v<version>). tramite AS24CI\Logger.

Le tabelle di Content Studio vengono create da un hook di attivazione separato (Content_Studio_Repository::maybe_create_tables) registrato nel file principale del plugin, non da Plugin::activate().

activate() deliberatamente non inserisce URL API predefiniti. La configurazione mancante viene evidenziata attraverso l'interfaccia utente dello stato/salute del sistema e tramite errori del client quando l'importatore viene eseguito.

Migrazioni di funzionalità e dati

Due metodi statici sono collegati su admin_init (non plugins_loaded) per mantenere le installazioni esistenti sincronizzate con la versione corrente del plugin. L'aggancio su admin_init evita di forzare il caricamento anticipato dello stack di autenticazione pluggabile su ogni richiesta:

• maybe_upgrade_caps() — Collegato su admin_init. Protegge da richieste AJAX, cron e REST (ritornando anticipatamente in tali contesti) e utilizza una protezione statica per richiesta in modo che il corpo della migrazione venga eseguito al massimo una volta. Non è vincolato a manage_options. Confronta as24ci_caps_version con il valore di destinazione (1 al momento della scrittura) e riesegue ensure_roles_and_caps() se necessario.
• maybe_upgrade() — Collegato su admin_init; ritorna anticipatamente a meno che is_admin(). Confronta as24ci_db_version con il valore di destinazione (5) e applica eventuali passaggi di migrazione in sospeso. Ogni passaggio è idempotente:
• Migrazione 1: solo marcatore, nessuna modifica ai dati.
• Migrazione 2: forza l'opzione del consenso di analytics (Options::ANALYTICS_REQUIRE_CONSENT) su 0. Gli amministratori possono riabilitarla dall'interfaccia utente delle impostazioni.
• Migrazione 3: migra l'opzione legacy FINANCING_PLACEMENT alle nuove zone del Layout Manager. La migrazione scrive in una zona del Layout Manager solo se tale zona non è stata ancora salvata, in modo da preservare i layout esistenti.
• Migrazione 4: riapplica seed_safe_defaults() in modo che le installazioni esistenti ricevano eventuali nuovi valori predefiniti sicuri senza sovrascrivere i valori che l'amministratore ha già impostato.
• Migrazione 5: protegge i segreti in chiaro a riposo. I segreti reversibili (Options::CLIENT_SECRET, Options::HUB_API_KEY, Options::WEBHOOK_SECRET) vengono racchiusi tramite Secrets::encrypt(), e il token cron (Options::CRON_TOKEN) viene sostituito con il suo hash HMAC con chiave tramite Secrets::hash_token(). La migrazione è idempotente (le righe già protette vengono saltate) e il token di accesso OAuth memorizzato nella cache viene cancellato in modo da essere memorizzato nuovamente tramite il percorso crittografato. Dopo tutti i passaggi applicabili, l'opzione viene aggiornata alla versione di destinazione corrente.

---

Disattivazione

AS24CI\Plugin::deactivate() viene eseguito una volta quando un amministratore disattiva il plugin. I dati esistenti vengono preservati. Il metodo:

1. Chiama wp_clear_scheduled_hook( Scheduler::CRON_HOOK ) per rimuovere gli eventi as24ci_scheduled_import in sospeso.
2. Chiama wp_clear_scheduled_hook( Analytics::ANALYTICS_CLEANUP_CRON_HOOK ) per rimuovere l'evento di conservazione giornaliera di Analytics.
3. Chiama Ai_Assistant::clear_ai_queue_schedule() per rimuovere l'evento cron della coda AI in background.
4. Chiama Pricing_Engine::clear_schedule() per rimuovere l'evento cron giornaliero del motore di determinazione dei prezzi.
5. Chiama License_Manager::clear_cron() per rimuovere l'evento giornaliero di ri-validazione della licenza (as24ci_license_refresh).
6. Chiama wp_clear_scheduled_hook( 'as24ci_competitor_watcher_cron' ) solo come pulizia legacy — la funzionalità Competitor Watcher (e la sua classe) è stata rimossa; il nome dell'hook è codificato qui in modo che qualsiasi evento pianificato rimasto sulle installazioni aggiornate da versioni precedenti venga comunque rimosso.
7. Elimina il transient Scheduler::LOCK_TRANSIENT (as24ci_cron_import_running) nel caso in cui il plugin venga disattivato mentre è in corso un'importazione.
8. Chiama flush_rewrite_rules() e registra Plugin deactivated.

Poiché la disattivazione non tocca le tabelle del database, i custom post type o le opzioni, la riattivazione del plugin ripristina lo stato precedente.

Disinstallazione

Quando il plugin viene eliminato dall'amministrazione di WordPress (non solo disattivato), WordPress esegue uninstall.php. Lo script:

1. Carica AS24CI\Options (se il file esiste) in modo che l'elenco autorevole delle chiavi delle opzioni possa essere derivato da Options::get_all_keys(), oltre a un piccolo set di chiavi aggiuntive (as24ci_models_cache_keys, as24ci_page_archive_id, as24ci_page_compare_id e la legacy as24ci_api_total_cache). Viene utilizzato un elenco di fallback codificato se la classe non può essere caricata.
2. Elimina i transient del plugin (as24ci_access_token, as24ci_cron_import_running, as24ci_image_queue_running).
3. Annulla la pianificazione degli eventi in sospeso per as24ci_scheduled_import e as24ci_daily_cleanup.
4. Legge l'opzione as24ci_delete_data_on_uninstall. Quando il valore è 1, lo script elimina: - Tutti i post as24ci_car (forzato). - Tutti gli ID degli allegati memorizzati nel postmeta _as24ci_image_ids di ciascuna auto. Gli allegati della galleria manuale (_as24ci_manual_image_ids) non vengono intenzionalmente non eliminati. - L'immagine in evidenza allegata a ciascuna auto (pulizia difensiva). - Tutti i post as24ci_lead. - Le pagine Cars, Compare e Favorites create all'attivazione.
5. Rilascia sempre le tabelle personalizzate (indipendentemente dal flag di opt-in): - {$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 Anche le opzioni della versione dello schema corrispondenti (as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version) vengono rimosse.
6. Elimina tutte le chiavi delle opzioni raccolte per il sito.
7. Sulle installazioni multisito, la stessa routine viene eseguita una volta per sito tramite switch_to_blog().

Riferimento di configurazione

Il comportamento di bootstrap e ciclo di vita è influenzato dalle seguenti opzioni (tutte definite come costanti su AS24CI\Options). Il catalogo completo è documentato nel documento Archiviazione di opzioni e impostazioni; qui sono elencate solo le voci rilevanti per il ciclo di vita.

Note operative

• register_activation_hook viene attivato solo quando un amministratore attiva il plugin dalla schermata dei Plugin. L'aggiornamento dei file del plugin non attiva l'attivazione; ecco perché esiste maybe_upgrade().
• Poiché maybe_upgrade() e maybe_upgrade_caps() sono agganciati a admin_init e vengono eseguiti solo durante i caricamenti reali delle pagine di amministrazione (non AJAX, REST o cron), le richieste solo frontend non pagano il costo dei controlli di migrazione. Il primo caricamento della pagina di amministrazione dopo un aggiornamento applica qualsiasi migrazione in sospeso.
• I TTL di blocco WP-Cron del plugin sono conservativi: il blocco di importazione (Scheduler::LOCK_TTL) è di circa 40 minuti. Se un processo viene interrotto a metà esecuzione, il blocco viene rilasciato automaticamente alla scadenza del transient. Il ripristino manuale è descritto nella documentazione dello scheduler.
• La disinstallazione elimina sempre le tabelle di analytics, veicoli e search-agent perché potrebbero contenere dati personali o dei visitatori. I post e le opzioni vengono rimossi solo quando l'amministratore ha acconsentito tramite l'impostazione as24ci_delete_data_on_uninstall.

Risoluzione dei problemi

• L'attivazione non crea la pagina Cars. Verificare che as24ci_create_default_pages sia impostato su 1 e che nessun tema o altro plugin stia filtrando as24ci_default_pages_enabled su false. La pagina non viene ricreata anche se esiste già una pagina con lo stesso titolo; in tal caso il suo ID viene riutilizzato.
• Mancano le capacità personalizzate per un amministratore. Visitare qualsiasi pagina di amministrazione in modo che maybe_upgrade_caps() possa essere eseguito su admin_init, oppure eliminare temporaneamente as24ci_caps_version da wp_options per forzare la riesecuzione della migrazione. La migrazione viene saltata sulle richieste AJAX, REST e cron, quindi deve essere eseguita durante un caricamento reale della pagina di amministrazione.
• Un passaggio di migrazione non è stato applicato. Controllare il valore di as24ci_db_version. Se è già uguale alla destinazione, la migrazione è già stata eseguita. Abbassare il valore manualmente solo se si comprendono le conseguenze per la propria installazione.
• L'archivio /cars restituisce un errore 404 subito dopo l'attivazione. L'attivazione chiama già flush_rewrite_rules(). Se l'archivio non è ancora raggiungibile, visitare Impostazioni → Permalink e salvare una volta per forzare WordPress a ricostruire la sua cache di riscrittura.

Documenti correlati

• Panoramica dell'architettura
• Modello dei dati
• Schema del database
• Panoramica della sezione