Plugin-Bootstrap und Lebenszyklus

--- This document describes how the ADP Car Market Hub plugin loads, what happens during activation, deactivation and uninstall, and which migrations the plugin runs as it boots.

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin geladen wird, was während der Aktivierung, Deaktivierung und Deinstallation geschieht und welche Migrationen das Plugin beim Start ausführt.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Den Ablauf verfolgen, in dem der Plugin-Code während einer WordPress-Anfrage ausgeführt wird.
• Verstehen, welche Aktionen bei der Aktivierung und Deaktivierung ausgeführt werden (Berechtigungen, Standardseiten, benutzerdefinierte Tabellen, geplante Ereignisse).
• Ein Upgrade planen oder Fehler bei einer Migration beheben, die nicht angewendet wurde.
• Entscheiden, wo Sie benutzerdefinierten Code einhaken, damit er ausgeführt wird, nachdem die Dienste des Plugins verfügbar sind.
• Trace the order in which plugin code executes during a WordPress request.
• Understand which actions run on activation and deactivation (capabilities, default pages, custom tables, scheduled events).
• Plan an upgrade or troubleshoot a migration that did not apply.
• Decide where to hook custom code so that it runs after the plugin's services are available.

Übersicht

Das Plugin wird aus der Hauptdatei adp-car-market-hub.php gebootstrappt. Diese Datei ist bewusst kurz gehalten und führt nur Arbeiten aus, die zum Zeitpunkt des Ladens der Datei erfolgen müssen. Der gesamte Feature-Code wird über einen Autoloader im PSR-4-Stil geladen und vom AS24CI\Plugin-Singleton bei der Aktion plugins_loaded verknüpft.

Beim Laden definierte Konstanten

adp-car-market-hub.php definiert die folgenden Konstanten, bevor Hooks ausgeführt werden:

• AS24CI_VERSION — Aktuelle Plugin-Version (wird mit dem Plugin-Header und readme.txt synchron gehalten).
• AS24CI_PLUGIN_FILE — Absoluter Pfad zur Haupt-Plugin-Datei.
• AS24CI_PLUGIN_DIR — Verzeichnis des Plugins (mit abschließendem Schrägstrich).
• AS24CI_PLUGIN_URL — URL zum Plugin-Verzeichnis, nützlich für das Einreihen von Assets.

Die Datei ruft auch require_once AS24CI_PLUGIN_DIR . 'src/Core/Helpers.php' auf, um gemeinsam genutzte prozedurale Helfer zu laden, und definiert bedingt die globalen Helfer as24ci_format() und as24ci_get_available_ai_models(), falls zuvor keine Funktion mit demselben Namen deklariert wurde.

Autoloader

Unmittelbar nach den Konstanten registriert die Datei einen kleinen PSR-4-kompatiblen Autoloader für den Namespace AS24CI\. Klassennamen werden Dateinamen der Form class-as24ci-<lower-dashed-name>.php zugeordnet. Der Autoloader sucht zuerst in includes/ und weicht für reine Admin-Klassen auf includes/admin/ aus.

Hook-Registrierung beim Laden

Die Hauptdatei registriert die folgenden Hooks, bevor Feature-Code ausgeführt wird:

Die Hauptdatei bootstrappt auch das Content Studio-Modul beim Laden, unabhängig vom AS24CI\Plugin-Router:

• register_activation_hook → AS24CI\Content_Studio_Repository::maybe_create_tables (erstellt die Content Studio-Tabellen bei der Aktivierung).
• admin_menu (Priorität 30) → AS24CI\Admin_Tab_Content_Studio::register_menu.
• plugins_loaded (Priorität 20) → AS24CI\Content_Studio_Admin_Worker::register_hooks.

Das benutzerdefinierte WP-Cron-Intervall wird bedingungslos registriert, sodass WordPress immer davon weiß, selbst wenn einzelne Feature-Optionen, die es verwenden, deaktiviert sind.

Bootstrap-Ablauf (normale Anfrage)

Wenn WordPress das Plugin während einer normalen Anfrage lädt, erfolgen die folgenden Schritte in dieser Reihenfolge:

1. Die Hauptdatei wird eingebunden; Konstanten, Autoloader und die oben aufgeführten Hooks werden registriert.
2. WordPress löst plugins_loaded mit Priorität 1 aus: as24ci_load_textdomain() führt load_plugin_textdomain() aus, damit Übersetzungen verfügbar sind, bevor eine übersetzbare Zeichenfolge gerendert wird.
3. WordPress löst plugins_loaded mit der Standardpriorität aus: AS24CI\Plugin::init() erstellt das Singleton.
4. Der Konstruktor von AS24CI\Plugin: - Instanziiert die gemeinsam genutzten Dienste: Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler. - Ruft Vehicle_Field_Resolver::set_repository() auf, damit der zentrale Feld-Resolver aus der Fahrzeugtabelle lesen kann. - Ruft Vehicle_Deleter::set_repository() und Vehicle_Deleter::register_hooks() auf, damit jeder Pfad zum endgültigen Löschen (natives WordPress, vollständige Synchronisierung des Importers, Massenaktion) über eine einzige, idempotente Bereinigung läuft. - Ruft register_hooks() auf, um alle Funktionen für die aktuelle Anfrage zu verknüpfen.
5. register_hooks() verknüpft zwei admin_init-Callbacks (sie werden während plugins_loaded verknüpft, lösen aber erst bei einem späteren admin_init in wp-admin aus): - AS24CI\Plugin::maybe_upgrade_caps() — stellt sicher, dass Rollen und Berechtigungen für die aktuelle Plugin-Version existieren. - AS24CI\Plugin::maybe_upgrade() — führt Options-/Datenmigrationen aus.
6. register_hooks() registriert dann die eigenen Hooks jedes Subsystems: - Immer aktiv: 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 (mit täglichem Zeitplan), Financing_Calculator, Rest_Api, Locations, Seller_Profile_Fields, plus der Scheduler. Das private Updater wird hier ebenfalls verknüpft, beschränkt auf Admin- / WP-Cron- / WP-CLI-Kontexte. - Durch Feature-Optionen auf AS24CI\Options gesteuert: Schema (plus Seo_Compatibility), Sitemap, Social_Share, Pdf_Datasheet, Favorites, Compare, Export, Bulk_Actions, Search_Agent. - Nur Admin (is_admin() ist true): der AS24CI\Admin-Controller, Admin_Team (CMH Team), Update_Visibility und Admin_Setup_Wizard sowie — wenn Options::FEATURE_DASHBOARD_WIDGET aktiviert ist — das Dashboard-Widget.
7. WordPress fährt mit dem Rest des Anfrage-Lebenszyklus fort. Die meisten Feature-Klassen registrieren zusätzliche Hooks bei späteren Aktionen wie init (Post-Typen, Taxonomien, Tabellenerstellung für Suchaufträge), rest_api_init (REST-Routen), wp_footer (Analytics-Tracking-Pixel) oder admin_init (reine Admin-Tabellen-Upgrades).

Aktivierung

AS24CI\Plugin::activate() ist bei register_activation_hook registriert und wird einmal ausgeführt, wenn ein Administrator das Plugin aktiviert. Es führt die folgenden Arbeiten in dieser Reihenfolge aus:

1. Ruft seed_safe_defaults() auf, das add_option() verwendet, um konservative Standardwerte für die Ersteinrichtung zu installieren. Bestehende Werte werden niemals überschrieben. Wichtige Standardwerte: - as24ci_default_currency = EUR. - as24ci_default_post_status = draft, damit Admins die Zuordnungen vor der Veröffentlichung überprüfen können. - as24ci_max_images = 30 (eine feste Obergrenze statt unbegrenzt). - as24ci_full_sync = 0 (endgültiges Löschen bleibt Opt-in). - Frontend-freundliche Funktionen (Sitemap, Schema, Favoriten, Vergleich, Finanzierung, Dashboard-Widget, Export, Lazy Loading, Layout-Manager) sind standardmäßig aktiviert; Tracking, externe, Batch- und risikoreiche Funktionen (Analytics, REST-API, KI-Assistent, Social Share, PDF-Datenblatt, Probefahrt) sind standardmäßig deaktiviert.
2. Ruft add_option( Options::SETUP_FIRST_ACTIVATION_AT, gmdate('c') ) auf, um den Zeitstempel der Erstaktivierung zu erfassen, der vom Setup-Assistenten-Admin-Hinweis verwendet wird. Da add_option() wirkungslos bleibt, wenn der Wert bereits existiert, bleibt das ursprüngliche Datum bei Reaktivierungen erhalten.
3. Ruft ensure_roles_and_caps() auf, was: - Die Rolle as24ci_editor erstellt, falls sie nicht existiert. - Die Berechtigungen as24ci_car / as24ci_cars sowohl für as24ci_editor als auch für administrator gewährt. - Die Berechtigung manage_as24_imports (die Konstante Plugin::CAP_MANAGE) nur für Administratoren hinzufügt. Diese Berechtigung steuert den Zugriff auf die Benutzeroberfläche für Importer, Einstellungen, Werkzeuge und Protokolle.
4. Setzt as24ci_caps_version auf 1, damit die Berechtigungsmigration bei nachfolgenden Anfragen nicht erneut ausgeführt wird.
5. Setzt as24ci_db_version auf 5, sodass die in maybe_upgrade() definierten Datenmigrationen bei einer Neuinstallation übersprungen werden.
6. Ruft maybe_create_default_pages() auf, um optional die Seiten Cars, Compare Cars und Favorites zu erstellen und deren Post-IDs in as24ci_page_archive_id, as24ci_page_compare_id und as24ci_page_favorites_id zu speichern. Dieses Verhalten wird durch die Option as24ci_create_default_pages und die Filter as24ci_default_pages_enabled und as24ci_default_pages gesteuert.
7. Ruft Analytics::maybe_create_table() auf, um die Analytics-Tabelle zu erstellen.
8. Ruft Vehicle_Repository::maybe_create_table() auf, um die dedizierte Fahrzeugtabelle zu erstellen.
9. Plant die tägliche Bereinigung der Analytics-Daten (as24ci_daily_cleanup), falls noch nicht geplant.
10. Ruft License_Manager::ensure_cron_scheduled() auf, um das tägliche Ereignis zur Lizenz-Revalidierung (as24ci_license_refresh) zu planen.
11. Ruft CPT::register_post_type() und dann flush_rewrite_rules() auf, damit das Archiv /cars sofort nach der Aktivierung funktioniert.
12. Protokolliert Plugin activated (v<version>). über AS24CI\Logger.

Die Content Studio-Tabellen werden durch einen separaten Aktivierungs-Hook (Content_Studio_Repository::maybe_create_tables) erstellt, der in der Haupt-Plugin-Datei registriert ist, nicht durch Plugin::activate().

activate() fügt bewusst keine Standard-API-URLs ein. Fehlende Konfigurationen werden über die Systemstatus- / Systemzustands-UI sowie über Client-Fehler beim Ausführen des Importers gemeldet.

Berechtigungs- und Datenmigrationen

Zwei statische Methoden sind auf admin_init (nicht plugins_loaded) verknüpft, um bestehende Installationen mit der aktuellen Plugin-Version synchron zu halten. Das Einhaken auf admin_init verhindert, dass der erweiterbare Authentifizierungs-Stack bei jeder Anfrage frühzeitig geladen werden muss:

• maybe_upgrade_caps() — Verknüpft auf admin_init. Schützt vor AJAX-, Cron- und REST-Anfragen (bricht in diesen Kontexten frühzeitig ab) und verwendet eine statische Sperre pro Anfrage, sodass der Migrationskörper höchstens einmal ausgeführt wird. Sie ist nicht von manage_options abhängig. Vergleicht as24ci_caps_version mit dem Zielwert (zum Zeitpunkt der Erstellung dieses Dokuments 1) und führt ensure_roles_and_caps() bei Bedarf erneut aus.
• maybe_upgrade() — Verknüpft auf admin_init; bricht frühzeitig ab, es sei denn, is_admin() ist erfüllt. Vergleicht as24ci_db_version mit dem Zielwert (5) und wendet alle ausstehenden Migrationsschritte an. Jeder Schritt ist idempotent:
• Migration 1: Nur eine Markierung, keine Datenänderungen.
• Migration 2: Erzwingt die Analytics-Einwilligungsoption (Options::ANALYTICS_REQUIRE_CONSENT) auf 0. Administratoren können sie in den Einstellungen wieder aktivieren.
• Migration 3: Migriert die veraltete Option FINANCING_PLACEMENT in die neuen Zonen des Layout-Managers. Die Migration schreibt nur dann in eine Layout-Manager-Zone, wenn diese Zone noch nicht gespeichert wurde, sodass bestehende Layouts erhalten bleiben.
• Migration 4: Wendet seed_safe_defaults() erneut an, damit bestehende Installationen neue sichere Standardwerte erhalten, ohne Werte zu überschreiben, die der Administrator bereits festgelegt hat.
• Migration 5: Schützt Klartext-Geheimnisse im Ruhezustand. Reversible Geheimnisse (Options::CLIENT_SECRET, Options::HUB_API_KEY, Options::WEBHOOK_SECRET) werden über Secrets::encrypt() verschlüsselt, und das Cron-Token (Options::CRON_TOKEN) wird über Secrets::hash_token() durch seinen keyed HMAC-Hash ersetzt. Die Migration ist idempotent (bereits geschützte Zeilen werden übersprungen) und das zwischengespeicherte OAuth-Bearer-Token wird gelöscht, sodass es über den verschlüsselten Pfad neu gespeichert wird. Nach allen anwendbaren Schritten wird die Option auf die aktuelle Zielversion aktualisiert.

---

---

Deaktivierung

AS24CI\Plugin::deactivate() wird einmal ausgeführt, wenn ein Administrator das Plugin deaktiviert. Bestehende Daten bleiben erhalten. Die Methode:

1. Ruft wp_clear_scheduled_hook( Scheduler::CRON_HOOK ) auf, um ausstehende as24ci_scheduled_import-Ereignisse zu entfernen.
2. Ruft wp_clear_scheduled_hook( Analytics::ANALYTICS_CLEANUP_CRON_HOOK ) auf, um das tägliche Ereignis zur Aufbewahrung von Analysedaten zu entfernen.
3. Ruft Ai_Assistant::clear_ai_queue_schedule() auf, um das Cron-Ereignis für die KI-Hintergrundwarteschlange zu entfernen.
4. Ruft Pricing_Engine::clear_schedule() auf, um das tägliche Cron-Ereignis der Preisfindungs-Engine zu entfernen.
5. Ruft License_Manager::clear_cron() auf, um das tägliche Ereignis zur Lizenz-Revalidierung (as24ci_license_refresh) zu entfernen.
6. Ruft wp_clear_scheduled_hook( 'as24ci_competitor_watcher_cron' ) auf – ausschließlich als Legacy-Bereinigung –, da die Funktion "Competitor Watcher" (und ihre Klasse) entfernt wurde; der Hook-Name ist hier fest codiert, damit etwaige verbleibende geplante Ereignisse auf Installationen, die von älteren Versionen aktualisiert wurden, weiterhin gelöscht werden.
7. Löscht den Transient Scheduler::LOCK_TRANSIENT (as24ci_cron_import_running), falls das Plugin deaktiviert wird, während ein Import läuft.
8. Ruft flush_rewrite_rules() auf und protokolliert Plugin deactivated.

Da die Deaktivierung die Datenbanktabellen, benutzerdefinierten Inhaltstypen oder Optionen nicht berührt, stellt eine Reaktivierung des Plugins den vorherigen Zustand wieder her.

Deinstallation

Wenn das Plugin aus der WordPress-Verwaltung gelöscht wird (nicht nur deaktiviert), führt WordPress die Funktion uninstall.php aus. Das Skript:

1. Lädt AS24CI\Options (falls die Datei existiert), damit die maßgebliche Liste der Optionsschlüssel aus Options::get_all_keys() abgeleitet werden kann, zuzüglich eines kleinen Satzes zusätzlicher Schlüssel (as24ci_models_cache_keys, as24ci_page_archive_id, as24ci_page_compare_id und des veralteten as24ci_api_total_cache). Eine fest codierte Fallback-Liste wird verwendet, wenn die Klasse nicht geladen werden kann.
2. Löscht Plugin-Transients (as24ci_access_token, as24ci_cron_import_running, as24ci_image_queue_running).
3. Löscht geplante Ereignisse für as24ci_scheduled_import und as24ci_daily_cleanup.
4. Liest die Option as24ci_delete_data_on_uninstall. Wenn der Wert 1 ist, löscht das Skript: - Alle as24ci_car-Beiträge (erzwungen). - Alle Medien-IDs, die in den _as24ci_image_ids-Metadaten jedes Fahrzeugs gespeichert sind. Manuelle Galerie-Anhänge (_as24ci_manual_image_ids) werden absichtlich nicht gelöscht. - Das Beitragsbild (Featured Image) jedes Fahrzeugs (defensive Bereinigung). - Alle as24ci_lead-Beiträge. - Die bei der Aktivierung erstellten Seiten für Fahrzeuge, Vergleich und Favoriten.
5. Löscht immer die benutzerdefinierten Tabellen (unabhängig vom Opt-in-Flag): - {$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 Die passenden Schema-Versionsoptionen (as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version) werden ebenfalls entfernt.
6. Löscht alle gesammelten Optionsschlüssel für die Website.
7. Bei Multisite-Installationen wird dieselbe Routine einmal pro Website über switch_to_blog() ausgeführt.

Konfigurationsreferenz

Das Bootstrap- und Lebenszyklus-Verhalten wird durch die folgenden Optionen beeinflusst (alle als Konstanten in AS24CI\Options definiert). Der vollständige Katalog ist im Dokument Options- und Einstellungsspeicherung dokumentiert; hier sind nur die für den Lebenszyklus relevanten Einträge aufgeführt.

Betriebshinweise

• register_activation_hook wird nur ausgelöst, wenn ein Administrator das Plugin über die Plugin-Übersicht aktiviert. Das Aktualisieren der Plugin-Dateien löst keine Aktivierung aus; aus diesem Grund existiert maybe_upgrade().
• Da maybe_upgrade() und maybe_upgrade_caps() an admin_init gekoppelt sind und nur bei echten Admin-Seitenaufrufen ausgeführt werden (nicht bei AJAX, REST oder Cron), zahlen reine Frontend-Anfragen nicht den Preis für Migrationsprüfungen. Der erste Admin-Seitenaufruf nach einem Update wendet alle ausstehenden Migrationen an.
• Die WP-Cron-Sperrzeiten (Lock TTLs) des Plugins sind konservativ: Die Importsperre (Scheduler::LOCK_TTL) beträgt etwa 40 Minuten. Wenn ein Prozess mitten im Lauf abgebrochen wird, wird die Sperre automatisch aufgehoben, wenn der Transient abläuft. Die manuelle Wiederherstellung ist in der Scheduler-Dokumentation beschrieben.
• Die Deinstallation löscht immer die Tabellen für Analysen, Fahrzeuge und Suchaufträge, da diese personenbezogene Daten oder Besucherdaten enthalten können. Beiträge und Optionen werden nur entfernt, wenn der Administrator dies über die Einstellung as24ci_delete_data_on_uninstall aktiviert hat.

Fehlerbehebung

• Die Aktivierung erstellt die Fahrzeugseite nicht. Vergewissern Sie sich, dass as24ci_create_default_pages auf 1 gesetzt ist und dass kein Theme oder anderes Plugin as24ci_default_pages_enabled auf false filtert. Die Seite wird auch dann nicht neu erstellt, wenn bereits eine Seite mit demselben Titel existiert; in diesem Fall wird deren ID wiederverwendet.
• Benutzerdefinierte Berechtigungen fehlen für einen Administrator. Rufen Sie eine beliebige Admin-Seite auf, damit maybe_upgrade_caps() auf admin_init ausgeführt werden kann, oder löschen Sie vorübergehend as24ci_caps_version aus wp_options, um die erneute Ausführung der Migration zu erzwingen. Die Migration wird bei AJAX-, REST- und Cron-Anfragen übersprungen, sie muss also während eines echten Admin-Seitenaufrufs ausgeführt werden.
• Ein Migrationsschritt wurde nicht angewendet. Überprüfen Sie den Wert von as24ci_db_version. Wenn er bereits dem Zielwert entspricht, wurde die Migration bereits ausgeführt. Senken Sie den Wert nur dann manuell ab, wenn Sie die Konsequenzen für Ihre Installation verstehen.
• Das Archiv /cars gibt unmittelbar nach der Aktivierung einen 404-Fehler zurück. Die Aktivierung ruft bereits flush_rewrite_rules() auf. Wenn das Archiv immer noch nicht erreichbar ist, rufen Sie Einstellungen → Permalinks auf und speichern Sie einmal, um WordPress zu zwingen, seinen Rewrite-Cache neu aufzubauen.

Verwandte Dokumente

• Architekturübersicht
• Datenmodell
• Datenbankschema
• Sektionsübersicht