Documentatie · Technische documentatie

Architectuuroverzicht

Dit document beschrijft de high-level architectuur van de ADP Car Market Hub WordPress plugin: hoe de broncode is georganiseerd, welke klassen de belangrijkste verantwoordelijkheden dragen en hoe de belangrijkste functies tijdens runtime met elkaar zijn verbonden.

Wanneer u dit document moet gebruiken

Lees dit document als u:

Een overzicht wilt krijgen van de PHP-codebase van de plugin voordat u in een specifiek subsysteem duikt.
Wilt begrijpen welke klasse verantwoordelijk is voor een bepaalde functie.
Een aanpassing, integratie of code-review wilt plannen.

Voor de stapsgewijze opstartvolgorde, zie Plugin Bootstrap And Lifecycle. Voor details over de opslag, zie Data Model en Database Schema.

Overzicht

De plugin is geïmplementeerd in PHP en volgt de standaard WordPress plugin-conventies. Het maakt gebruik van:

Een enkel hoofdbestand (adp-car-market-hub.php) dat plugin-constanten definieert, een autoloader registreert en bootstrap-callbacks koppelt.
Een AS24CI\ PHP-namespace voor alle klassen.
De WordPress core-API's voor custom post types, taxonomieën, opties, WP-Cron, REST API, AJAX-handlers en door dbDelta beheerde aangepaste tabellen.
Een centrale AS24CI\Plugin singleton die elke functie met elkaar verbindt tijdens de plugins_loaded actie.

Lay-out van de hoofdmap

De repository is als volgt georganiseerd (alleen mappen die relevant zijn voor de runtime-architectuur worden vermeld):

adp-car-market-hub.php — hoofdpluginbestand. Definieert constanten, registreert de autoloader, laadt het tekst-domein, registreert activerings-/deactiveringshooks, registreert aangepaste WP-Cron-intervallen en start de AS24CI\Plugin singleton op tijdens plugins_loaded.
includes/ — gedeelde en frontend PHP-klassen, één klasse per bestand. Bestandsnamen volgen het patroon class-as24ci-<name>.php en verwijzen naar de AS24CI\<Name> klasse via de autoloader.
includes/admin/ — PHP-klassen die alleen voor beheerders zijn (instellingentabbladen, list-table helpers, dashboard-widgets). Wordt opgelost door dezelfde autoloader als terugvaloptie wanneer een klasse niet wordt gevonden onder includes/.
src/Core/Helpers.php — gedeelde procedurele helpers die onvoorwaardelijk worden geladen vanuit het hoofdpluginbestand.
templates/ — frontend-templates en template-onderdelen die kunnen worden overschreven door thema's.
assets/ — CSS, JavaScript en afbeeldingen voor beheerder en frontend.
languages/ — vertaalbestanden; het tekst-domein is adp-car-market-hub.
uninstall.php — wordt uitgevoerd wanneer de plugin wordt verwijderd uit WordPress en verwijdert plugin-opties en (optioneel) geïmporteerde inhoud.

Autoloader

adp-car-market-hub.php registreert een kleine PSR-4-compatibele autoloader voor het AS24CI\ prefix. Klassennamen worden omgezet naar de bestandsnaamconventie class-as24ci-<lower-case-name-with-dashes>.php. De autoloader zoekt eerst in includes/ en daarna in includes/admin/, waardoor gedeelde klassen en klassen die alleen voor beheerders zijn, één namespace kunnen delen.

Kernklassen en hun verantwoordelijkheden

De volgende klassen vormen de ruggengraat van de plugin. Namen zijn geschreven in hun volledig gekwalificeerde vorm (AS24CI\<Class>).

Bootstrap en gedeelde services

AS24CI\Plugin — Singleton-toegangspunt. Bouwt de gedeelde service-instanties (Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler), koppelt alle WordPress hooks voor de actieve functieset en stelt de statische activate() / deactivate() / init() callbacks beschikbaar.
AS24CI\Logger — Lichtgewicht logger die in de hele plugin wordt gebruikt voor berichten van de importer en scheduler.
AS24CI\Options — Gecentraliseerd register van optiesleutels die worden weergegeven als klasseconstanten (bijv. Options::DB_VERSION, Options::DEFAULT_CURRENCY, Options::AUTO_IMPORT_ENABLED). Het uninstall.php script gebruikt Options::get_all_keys() om opties op te schonen bij het verwijderen van de plugin.

Gegevens en opslag

AS24CI\CPT — Registreert het as24ci_car custom post type met aangepaste rechtenkoppeling (as24ci_car / as24ci_cars) en de gecombineerde "AutoScout24 API Import" metabox.
AS24CI\Taxonomies — Registreert de 15 voertuigkenmerk-taxonomieën die zijn gekoppeld aan as24ci_car (merk, model, carrosserievorm, brandstoftype, transmissie, aandrijving, staat, exterieur-/interieurkleur, emissienorm, energielabel, voertuigcategorie, garantietype, garantiedetails, cilinderopstelling).
AS24CI\Leads_CPT — Registreert het as24ci_lead custom post type dat wordt gebruikt om inzendingen van contactformulieren op te slaan, met statusconstanten voor new, contacted, closed en spam.
AS24CI\Vehicle_Repository — Repository voor de speciale aangepaste tabel {$wpdb->prefix}as24_vehicles die voertuigveldgegevens bevat (in plaats van wp_postmeta). Biedt schemabeheer (maybe_create_table()), CRUD-helpers en whitelists voor filteren/sorteren die worden gebruikt door find().
AS24CI\Vehicle_Field_Resolver — Gecentraliseerde lezer die voertuigvelden ophaalt door repositorygegevens te combineren met handmatige overschrijvingen. Gekoppeld tijdens de constructie van Plugin via Vehicle_Field_Resolver::set_repository().
AS24CI\Vehicle_Deleter — Enkelvoudig, idempotent opschoonpad dat wordt gebruikt wanneer een voertuig definitief wordt verwijderd (native WP-verwijdering, volledige synchronisatieverwijdering door de importer, bulkactie). Gekoppeld tijdens de constructie van Plugin.

Import-pipeline

AS24CI\Client — HTTP-client voor de AutoScout24 API. Verwerkt authenticatie en de uitvoering van verzoeken.
AS24CI\Mapper — Mapt inkomende AutoScout24 advertentiegegevens naar de interne veldstructuur die door de repository wordt gebruikt en schrijft de _as24ci_listing_id postmeta voor achterwaartse compatibiliteit.
AS24CI\Importer — Coördineert de import per advertentie: haalt gegevens op via Client, transformeert deze via Mapper, slaat voertuigen op via de repository en houdt wijzigingen bij via de _as24ci_content_hash en _as24ci_images_hash postmeta-sleutels.
AS24CI\Image_Importer — Downloadt en koppelt voertuigafbeeldingen, en converteert deze optioneel naar WebP. Slaat attachment-ID's op in de _as24ci_image_ids postmeta.
AS24CI\Scheduler — Beheert de WP-Cron-hooks as24ci_scheduled_import en as24ci_image_queue_process, de run-lock transients (as24ci_cron_import_running, as24ci_image_queue_running) en de handmatige Batch-Wizard-wachtrij transient as24ci_batch_queue. Dezelfde run_import()-stroom wordt gebruikt door WP-Cron, het REST-cron-endpoint en de "Nu uitvoeren"-knop in het beheergedeelte.
AS24CI\Cron_Endpoint — REST-endpoint waarmee externe servers imports kunnen activeren via een met een token beveiligde URL.

Frontend, SEO en integraties

AS24CI\Templates — Stuurt het voertuigarchief en de afzonderlijke templates door de template-loader van de plugin, waardoor overschrijvingen door thema's mogelijk worden.
AS24CI\Assets — Registreert en voegt CSS- en JavaScript-bundels voor beheerder en frontend toe aan de wachtrij.
AS24CI\Archive_Filters — Rendert de UI van het archieffilter en past query-aanpassingen toe op basis van gebruikersselecties.
AS24CI\Schema — Voegt gestructureerde gegevens van Schema.org en Open Graph / Twitter Card-metatags toe aan afzonderlijke voertuigpagina's. Optioneel, afgeschermd door Options::FEATURE_SCHEMA.
AS24CI\Sitemap — Integreert voertuigen in de WordPress core sitemap en is compatibel met Yoast en Rank Math. Optioneel, afgeschermd door Options::FEATURE_SITEMAP.
AS24CI\Social_Share, AS24CI\Pdf_Datasheet, AS24CI\Favorites, AS24CI\Compare, AS24CI\Export, AS24CI\Bulk_Actions, AS24CI\Financing_Calculator, AS24CI\Test_Drive, AS24CI\Search_Agent — Optionele functies die elk hun eigen hooks registreren. De meeste zijn afgeschermd door een Options::FEATURE_*-schakelaar (zie seed_safe_defaults() in AS24CI\Plugin voor de standaardinstellingen die bij een nieuwe installatie worden geleverd).
AS24CI\Webhooks — Uitgaande webhooks voor CRM- en integratiescenario's.
AS24CI\Rest_Api — Openbare REST API voor voertuigadvertenties, afgeschermd door Options::REST_API_ENABLED.
AS24CI\Analytics — Tracking van paginaweergaven, filters en leads. Beheert de {$wpdb->prefix}as24ci_analytics-tabel en de as24ci_daily_cleanup retentie-cron.
AS24CI\Ai_Assistant — Genereert AI-beschrijvingen, SEO-metadata en uitrustingshoogtepunten met behulp van de beheerde Google Gemini-configuratie die beschikbaar wordt gesteld door AS24CI\Ai_Config. De Gemini-sleutel van de klant wordt server-naar-server geleverd door het API Platform en versleuteld opgeslagen via AS24CI\Ai_Credential_Manager; er kan geen provider, model of API-sleutel worden geselecteerd in de beheer-UI.
AS24CI\Data_Quality_Scanner — Optionele detector voor spelfouten in taxonomieën die gebruikmaakt van de AI-integratie.
AS24CI\Pricing_Engine — Dagelijkse prijsanalyse die wordt uitgevoerd op de as24ci_pricing_analysis_cron hook.
AS24CI\Locations, AS24CI\Seller_Profile_Fields — Dealerlocaties, openingstijden en metadata van het verkopersprofiel.
AS24CI\Team / AS24CI\Admin_Team — CMH Team: verkoopcontacten van de dealer die geen WordPress-gebruikersaccounts vereisen. Opslag is gebaseerd op opties (geen aangepaste tabel of CPT); contacten worden bewaard in Options::TEAM_MEMBERS en gerelateerde optiesleutels, wat het Locations-patroon weerspiegelt. Admin_Team registreert een speciaal hoofdmenu in het beheergedeelte.
AS24CI\License_Manager, AS24CI\License_Client, AS24CI\License_Refresh_Signal, AS24CI\License_Signal_Secret — ADP Car Market Hub API Platform-licentie / beheerde toegangslaag. License_Manager beheert de dagelijkse her-validatie-cron (as24ci_license_refresh), opslag van functierechten, operationele/AI-schrijfpadbeveiliging en beheerdersmeldingen. License_Refresh_Signal stelt het inkomende POST /as24ci/v1/license-refresh-signal endpoint beschikbaar.
AS24CI\Ai_Credential_Manager — Slaat de Gemini-inloggegevens van de klant op en ontsleutelt deze, geleverd door het API Platform.
Content Studio (AS24CI\Content_Studio_*, bijv. Content_Studio_Repository, Content_Studio_Options, Content_Studio_Admin_Worker, Admin_Tab_Content_Studio) — Een grotendeels op zichzelf staande module die marketinginhoud genereert op basis van bestaande voertuiggegevens. Het beheert zijn eigen tabellen (as24ci_content_studio_jobs, as24ci_content_studio_assets), zijn eigen as24ci_content_studio_* opties en een achtergrond-worker, en wordt opgestart vanuit het hoofdpluginbestand in plaats van de Admin router. Het leest bestaande voertuig-/importgegevens alleen-lezen uit.

Beheer-UI

AS24CI\Admin — Hoofdcontroller voor het beheergedeelte, alleen geïnstantieerd wanneer is_admin() waar is. Stelt intern tabbladklassen samen uit includes/admin/ (importer, instellingen, mapping, design, layout manager, leads, AI Assistant, systeemstatus, enz.).
AS24CI\Dashboard_Widget — Optionele WordPress dashboard-widget, afgeschermd door Options::FEATURE_DASHBOARD_WIDGET.

Functieschakelaars en "veilige eerste installatie"

De meeste niet-essentiële functies worden voorwaardelijk geregistreerd in AS24CI\Plugin::register_hooks() op basis van opties waarvan de constanten zijn definieerd in AS24CI\Options (bijvoorbeeld FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED).

Bij een nieuwe installatie stelt de plugin voorzichtige standaardwaarden in via AS24CI\Plugin::seed_safe_defaults(). Privacygevoelige, externe of batchfuncties staan standaard uit; frontend-vriendelijke functies (sitemap, schema, favorieten, vergelijken, financieringscalculator, dashboard-widget, export, lazy loading, layout manager) staan standaard aan. Bestaande installaties worden nooit overschreven omdat de seeder add_option() gebruikt.

Opslaglay-out (op hoofdlijnen)

De plugin maakt gebruik van drie opslaglagen:

Aangepaste databasetabellen beheerd via dbDelta: - {$wpdb->prefix}as24_vehicles — voertuigveldgegevens, eigendom van AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — analytics-gebeurtenissen, eigendom van AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — zoekalert-abonnementen, eigendom van AS24CI\Search_Agent. - {$wpdb->prefix}as24ci_content_studio_jobs en {$wpdb->prefix}as24ci_content_studio_assets — Content Studio-taken en gegenereerde assets, eigendom van AS24CI\Content_Studio_Repository.
WordPress posts en postmeta: - as24ci_car posts ondersteunen de WordPress permalinks, taxonomieën en templates voor elk voertuig. Een kleine set postmeta-sleutels blijft in wp_postmeta behouden voor achterwaartse compatibiliteit (bijvoorbeeld _as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids). - as24ci_lead posts slaan inzendingen van contactformulieren op met de status opgeslagen in _as24ci_lead_status.
wp_options — Alle door de gebruiker configureerbare instellingen. Sleutels zijn gedefinieerd als constanten op AS24CI\Options (en, voor Content Studio, op AS24CI\Content_Studio_Options). Schemaversies voor de aangepaste tabellen worden ook opgeslagen als opties (as24ci_db_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version). CMH Team-contacten worden ook opgeslagen in opties (as24ci_team_*).

Zie voor details op kolomniveau Database Schema. Zie voor het logische entiteitsmodel en hoe postmeta en de aangepaste tabel op elkaar inwerken Data Model.

Runtime-flow in vogelvlucht

Een typisch verzoek doorloopt de volgende fasen (vereenvoudigd):

WordPress laadt adp-car-market-hub.php, dat plugin-constanten definieert, de autoloader registreert en aangepaste WP-Cron-intervallen toevoegt.
Op plugins_loaded (prioriteit 1) wordt het tekstdomein geladen.
Op plugins_loaded (standaardprioriteit) wordt AS24CI\Plugin::init() uitgevoerd, die de singleton instantieert en alle hooks voor actieve functies registreert.
Feature-klassen registreren hun eigen hooks op init, rest_api_init, wp_ajax_*, wp_footer, enz.
Volgende activiteiten (een cron-run, een REST-verzoek, een frontend-paginaweergave) worden afgehandeld door de geregistreerde hooks.

Operationele opmerkingen

De plugin gaat uit van de WordPress- en PHP-versies die zijn gedeclareerd in de plugin-header (Requires at least: 6.2, Requires PHP: 8.1). Lagere versies worden niet ondersteund.
De meeste subsystemen gebruiken wpdb alleen rechtstreeks wanneer dbDelta het vereiste schema of de query niet kan uitdrukken. Directe query's zijn beperkt tot de repository-, analytics-, search-agent- en de-installatiecode.
De architectuur houdt frontend-rendering bewust gescheiden van de gegevensimport. De importeur rendert nooit templates; de templates activeren nooit netwerkverzoeken naar AutoScout24.
De plugin voegt een link "Instellingen" toe aan zijn rij op het WordPress Plugins-scherm via het plugin_action_links_<basename>-filter.

Problemen oplossen

Een functie lijkt zich niet te registreren. Controleer de bijbehorende Options::FEATURE_*-schakelaar. De register_hooks()-methode in AS24CI\Plugin slaat uitgeschakelde functies over.
Een klasse is niet gevonden. Controleer de naamgevingsconventie voor bestanden (class-as24ci-<lower-dashed-name>.php) en of het bestand zich bevindt in includes/ of includes/admin/. De autoloader zoekt alleen in deze twee mappen.
Er wordt verwezen naar een klasse die alleen voor beheerders is vanaf de frontend. Beheerdersklassen worden op aanvraag geladen door de autoloader, maar ze kunnen afhankelijk zijn van globals of rechten die alleen voor beheerders zijn. Controleer het gedrag in de huidige plugin-versie voordat u er afhankelijk van wordt.