Documentation · Technical Documentation

Options And Settings Storage

This document describes how the ADP Car Market Hub plugin stores its settings: which keys are used, where they live in the database and how the values are read and written by the plugin.

When to use this document

Read this document if you need to:

  • Locate a specific plugin setting in wp_options.
  • Understand which option drives a particular feature toggle.
  • Plan a backup, environment migration or staging-to-production deployment that includes plugin settings.
  • Build a custom integration that reads a plugin option from outside the plugin code.

For the underlying tables and entities, see Database Schema and Data Model.

Overview

All user-configurable settings are stored as standard WordPress options in the wp_options table. The plugin does not maintain a separate settings table.

Option keys are defined as constants on the AS24CI\Options class so that:

  • The keys exist in exactly one place in the source code.
  • The uninstall routine can derive the full option list automatically from AS24CI\Options::get_all_keys().
  • Code that reads or writes a setting can refer to the constant instead of repeating the raw string.

Most settings are scalar (string, integer, boolean encoded as 0/1). A few are arrays (for example seller IDs, mapping overrides, layout zones, social-share networks). Arrays are stored using WordPress's default option serialisation.

Naming conventions

All plugin option keys begin with the as24ci_ prefix. Subsystem prefixes group related settings:

  • as24ci_design_*, as24ci_archive_*, as24ci_single_*, as24ci_fav_*, as24ci_comp_* — design and typography settings.
  • as24ci_cron_*, as24ci_image_queue* — scheduler and image queue.
  • as24ci_lead_* — contact form, consent and email templates.
  • as24ci_ai_* — AI Assistant.
  • as24ci_analytics_* — analytics and consent.
  • as24ci_test_drive_* — test-drive booking.
  • as24ci_envkv_* — German EnVKV / WLTP running-cost configuration.
  • as24ci_lm_*, as24ci_layout_* — Layout Manager zones and archive layout.
  • as24ci_feature_* — feature toggles for optional subsystems.

The full inventory of option keys is the public list returned by AS24CI\Options::get_all_keys().

Categories of settings

The Options class defines well over a hundred constants. The list below groups them by purpose. Where a default value is documented in code (constant default, add_option() in seed_safe_defaults(), or inline get_option(..., $default) calls), it is stated. Verify any non-default value against the current plugin version before publishing.

API and authentication

Used by AS24CI\Client to talk to the AutoScout24 API.

  • as24ci_base_url (Options::BASE_URL) — API base URL.
  • as24ci_token_url (Options::TOKEN_URL) — OAuth token URL.
  • as24ci_seller_ids (Options::SELLER_IDS) — comma-separated list of seller identifiers.
  • as24ci_client_id (Options::CLIENT_ID) — OAuth client ID.
  • as24ci_client_secret (Options::CLIENT_SECRET) — OAuth client secret.
  • as24ci_token_audience (Options::TOKEN_AUDIENCE) — OAuth audience parameter.
  • as24ci_default_currency (Options::DEFAULT_CURRENCY) — default ISO 4217 currency code (seeded as EUR on activation).

These values are required for any import to work and should be treated as confidential. They are not displayed to non-administrators.

Importer behaviour

Used by AS24CI\Importer and AS24CI\Image_Importer.

  • as24ci_default_post_status (Options::DEFAULT_POST_STATUS) — status assigned to newly imported vehicles. Seeded as draft so administrators can review mappings before publishing.
  • as24ci_default_post_author (Options::DEFAULT_POST_AUTHOR) — default author user ID.
  • as24ci_import_images (Options::IMPORT_IMAGES) — whether to import images.
  • as24ci_max_images (Options::MAX_IMAGES) — maximum number of images per vehicle. Seeded as 30. A value of 0 is treated as no limit by the importer; the image importer additionally enforces the limit defensively.
  • as24ci_convert_to_webp (Options::CONVERT_TO_WEBP) — convert imported images to WebP.
  • as24ci_webp_quality (Options::WEBP_QUALITY) — WebP quality (1–100; defaults to 80 if unset).
  • as24ci_full_sync (Options::FULL_SYNC) — when enabled, vehicles no longer present in the API are deleted after each import. Seeded as 0.
  • as24ci_verbose_logging (Options::VERBOSE_LOGGING) — verbose per-vehicle / per-image log lines.
  • as24ci_mapping_overrides (Options::MAPPING_OVERRIDES) — array of label and visibility overrides per AS24 field.

Scheduler and automation

Used by AS24CI\Scheduler and AS24CI\Cron_Endpoint.

  • as24ci_auto_import_enabled (Options::AUTO_IMPORT_ENABLED).
  • as24ci_cron_schedule (Options::CRON_SCHEDULE) — one of hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom. Default: hourly.
  • as24ci_cron_start_time (Options::CRON_START_TIME) — start time for daily / twice-daily schedules in HH:MM (24 h, WordPress site timezone). Default: 06:00.
  • as24ci_cron_custom_minutes (Options::CRON_CUSTOM_MINUTES) — interval for the custom schedule. Minimum: 15. Default: 30.
  • as24ci_cron_mode (Options::CRON_MODE) — wp-cron or server-cron.
  • as24ci_cron_token (Options::CRON_TOKEN) — token for the REST cron-import endpoint.
  • as24ci_cron_max_vehicles (Options::CRON_MAX_VEHICLES) — vehicle cap per cron run. 0 = unlimited.
  • as24ci_cron_image_queue (Options::CRON_IMAGE_QUEUE) — enable image queue mode during cron runs. Default: 1.
  • as24ci_image_queue (Options::IMAGE_QUEUE_DATA) — persistent pending image queue payload.
  • as24ci_image_queue_last_run (Options::IMAGE_QUEUE_LAST_RUN) — stats from the last image-queue worker run.
  • as24ci_last_run_time (Options::LAST_RUN_TIME) — Unix timestamp of the last completed import.
  • as24ci_last_run_status (Options::LAST_RUN_STATUS) — counts array { inserted, updated, skipped, errors, sync_deleted }.
  • as24ci_last_external_cron_run (Options::LAST_EXTERNAL_CRON_RUN) — Unix timestamp of the last successful external cron ping.

Default pages and lifecycle

  • as24ci_create_default_pages (Options::CREATE_DEFAULT_PAGES) — whether to create the Cars / Compare / Favorites pages on activation.
  • as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id — IDs of the activation-created pages.
  • as24ci_delete_data_on_uninstall (Options::DELETE_DATA_ON_UNINSTALL) — when set to 1, the uninstall routine deletes vehicles, leads, imported attachments and the activation-created pages.
  • as24ci_caps_version (Options::CAPS_VERSION) — capability migration marker.
  • as24ci_db_version (Options::DB_VERSION) — data/schema migration marker.

Custom-table schema markers

  • as24ci_vehicles_db_version — schema version of the as24_vehicles table.
  • as24ci_search_agent_db_version — schema version of the as24ci_search_agents table.
  • as24ci_content_studio_db_version — shared schema version of the as24ci_content_studio_jobs and as24ci_content_studio_assets tables.
  • as24ci_analytics_db_version — schema version of the as24ci_analytics table (constant AS24CI\Analytics::DB_VERSION_KEY).

Feature toggles

All feature toggles live on AS24CI\Options::FEATURE_*. Defaults are seeded by AS24CI\Plugin::seed_safe_defaults() on activation:

  • Defaulted to on: FEATURE_SCHEMA, FEATURE_SOCIAL_SHARE, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, FEATURE_SITEMAP, FEATURE_DASHBOARD_WIDGET, FEATURE_LAZY_LOADING, FEATURE_BULK_ACTIONS, FEATURE_EXPORT, FINANCING_ENABLED, LAYOUT_MANAGER_ENABLED. FEATURE_SEARCH_AGENT has no explicit seeded default but its register-time check treats anything other than '0' as enabled, so it is effectively on out of the box.
  • Defaulted to off for safety/compliance: ANALYTICS_ENABLED, REST_API_ENABLED, AI_ASSISTANT_ENABLED, TEST_DRIVE_ENABLED.

The full list of toggles and their semantics is documented in the class docblock for each constant.

Lead form and email

Used by AS24CI\Contact_Form and AS24CI\Leads_CPT.

  • as24ci_lead_recipient_email — override recipient email.
  • as24ci_lead_field_* (name/email/phone/message) — show/hide form fields. Defaults to 1.
  • as24ci_lead_consent_enabled, as24ci_lead_consent_text, as24ci_lead_privacy_url — consent checkbox configuration.
  • as24ci_lead_msg_success, as24ci_lead_msg_error — custom user messages.
  • as24ci_lead_email_subject_dealer, as24ci_lead_email_subject_customer, as24ci_lead_email_template_dealer, as24ci_lead_email_template_customer — email templates with placeholder support.

Analytics

  • as24ci_analytics_enabled — master toggle. Default: 0.
  • as24ci_analytics_retention_days — retention window in days. Default: 180.
  • as24ci_analytics_bi_enabled — BI / extended event tracking.
  • as24ci_analytics_require_consent — when 1, blocks tracking until an external consent signal arrives via the as24ci_analytics_consent_check filter.
  • as24ci_analytics_filter_minimization — strip free-text search values from analytics payloads. Default: 1.
  • as24ci_analytics_privacy_jurisdiction — auto, gdpr, dsgvo, revdsg, uk_gdpr or generic.

AI Assistant

  • as24ci_ai_assistant_enabled (Options::AI_ASSISTANT_ENABLED).
  • as24ci_ai_assistant_language, as24ci_ai_assistant_tone, as24ci_ai_assistant_max_length, as24ci_ai_assistant_custom_prompt.
  • as24ci_ai_assistant_auto_generate, as24ci_ai_gen_alt_text, as24ci_ai_gen_seo, as24ci_ai_extract_highlights.

AI features use a managed Google Gemini configuration. The hard-coded Gemini key/model constants on AS24CI\Ai_Config have been removed; Ai_Config is now a thin facade (get_managed_gemini_api_key() / get_effective_model()) that sources the customer Gemini key from the encrypted credential synced by the API Platform and managed by AS24CI\Ai_Credential_Manager (runtime model is always Ai_Credential_Manager::PRIMARY_MODEL). No provider, model or API key option exists in wp_options, and the key is never shown in the admin UI; customer AI provisioning is completed server-to-server by AD Promotion after installation.

Test drive booking

Used by AS24CI\Test_Drive.

  • as24ci_test_drive_enabled — master toggle. Default: 0.
  • as24ci_test_drive_available_days — array of ISO day numbers (1=Mon … 7=Sun).
  • as24ci_test_drive_start_time, as24ci_test_drive_end_time — time window (HH:MM, 24 h). Defaults 08:00 / 18:00.
  • as24ci_test_drive_slot_duration — slot length in minutes. Default: 30.
  • as24ci_test_drive_blackout_dates — array of Y-m-d strings.

Webhooks, REST API and external services

  • as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import, as24ci_webhook_secret.
  • as24ci_rest_api_enabled (Options::REST_API_ENABLED).
  • as24ci_hub_api_key, as24ci_hub_target_market — Market Hub integration (default target market: DE).
  • as24ci_locations — array of dealership locations (autoload OFF; loaded only on single vehicle pages and the Locations admin tab).

Licensing and managed access

Used by AS24CI\License_Manager. These hold the ADP Car Market Hub API Platform license state and feature rights:

  • as24ci_license_plan, as24ci_license_status, as24ci_license_last_error, as24ci_license_support_until, as24ci_license_expires_at, as24ci_license_installation_uid, as24ci_license_normalized_domain (constants Options::LICENSE_*).
  • Feature-rights state gates the operational (import/write) and AI paths; it is refreshed by the daily as24ci_license_refresh cron and by the inbound license-refresh-signal endpoint.

CMH Team

Used by AS24CI\Team (option-based storage, mirroring Locations):

  • as24ci_team_members (Options::TEAM_MEMBERS) — array of sales contacts (no WordPress user accounts required).
  • as24ci_team_location_defaults, as24ci_team_standards, as24ci_team_rules — supporting configuration.

Content Studio

Content Studio keys are defined on AS24CI\Content_Studio_Options (not AS24CI\Options) and are appended explicitly to the uninstall list:

  • as24ci_content_studio_db_version — shared schema version of the two Content Studio tables.
  • as24ci_content_studio_google_api_key, as24ci_content_studio_default_language, as24ci_content_studio_default_tone, as24ci_content_studio_brand_voice, as24ci_content_studio_disclaimer_text, as24ci_content_studio_compliance_notes.

Layout Manager and archive layout

  • as24ci_layout_manager_enabled — master toggle. Seeded as 1 (on) by seed_safe_defaults().
  • as24ci_lm_zone_* — per-zone layout arrays for search filters, archive cards, single main/sidebar/bottom, compare and favorites.
  • as24ci_lm_block_<id> — per-block field configuration.
  • as24ci_layout_archive_columns — 1–4. Default: 3.
  • as24ci_archive_default_sort — date_desc, price_asc, price_desc or mileage_asc.
  • as24ci_archive_per_page — vehicles per page. Default: 24.
  • as24ci_archive_list_excerpt_length — characters from excerpt in list view (0–500). Default: 75.
  • as24ci_layout_search_filters, as24ci_layout_single_main, as24ci_layout_single_sidebar, as24ci_layout_single_bottom — ordered arrays of block keys with documented default lists.

Design and typography

as24ci_design_* plus the page-specific as24ci_single_*, as24ci_archive_*, as24ci_fav_* and as24ci_comp_* typography options. They drive the colour scheme, fonts, layouts, badges and gallery options exposed in the **Design & Styles** admin tab. The full list is enumerated as constants on AS24CI\Options.

EnVKV / WLTP

For German market compliance, used by the EnVKV running-costs calculator on single vehicle pages.

  • as24ci_envkv_year — reference year (default 2024).
  • as24ci_envkv_price_petrol, as24ci_envkv_price_diesel, as24ci_envkv_price_electric — fuel/electricity prices.
  • as24ci_envkv_co2_price_low, as24ci_envkv_co2_price_med, as24ci_envkv_co2_price_high — CO₂ cost per tonne.
  • as24ci_envkv_show_costs_100km — display running costs (default no).

Step by step instructions

The plugin's settings UI is the supported way to change options. The items below describe the supported lifecycle.

  1. First setup. On activation, seed_safe_defaults() writes a conservative set of defaults using add_option(). Existing values are never overwritten. Open the relevant admin tab to review the defaults before going live.
  2. Day-to-day changes. Edit settings in the corresponding admin tab (Importer, Automation, Design & Styles, Mapping, AI Assistant, etc.). Changes are saved through the WordPress Settings API.
  3. Backups. Standard WordPress database backups capture all plugin options because they live in wp_options. No additional backup is required.
  4. Environment migrations. When moving a site between environments, copy the relevant as24ci_* rows along with the rest of wp_options. Treat as24ci_client_id, as24ci_client_secret, as24ci_cron_token and the webhook secret (as24ci_webhook_secret) as confidential. Note that on installs migrated to data version 5 these reversible secrets are stored AES-256-GCM-encrypted and the cron token is stored hashed (see migration step 5 in Plugin Bootstrap And Lifecycle). The managed Gemini key is not stored in wp_options; it is synced server-to-server by the API Platform (held encrypted by AS24CI\Ai_Credential_Manager) and is not migrated through database moves.
  5. Resetting a setting. Delete the option (or use the admin tab's reset button where provided). The plugin will fall back to the default value documented for that setting.

Configuration reference

Use AS24CI\Options::get_all_keys() (returned by reflection on the class) for the authoritative, complete list of option keys at any plugin version. The list above is grouped for reference; new constants added to Options are automatically included in uninstall cleanup.

Operational notes

  • All option reads in plugin code go through get_option() with a documented default, so missing rows behave the same as freshly installed defaults.
  • A small number of options are intentionally autoload = false to keep the autoloaded options table small. Notable examples include as24ci_image_queue, as24ci_image_queue_last_run and as24ci_locations.
  • seed_safe_defaults() re-runs as part of migration step 4 so that existing installations receive any new safe defaults without overwriting administrator-modified values.
  • Multisite installations store options per site. The uninstall routine iterates each site via switch_to_blog().

Troubleshooting

  • A setting reverts after upgrade. The plugin never overwrites existing option values during upgrades. Verify that the change was saved (the option row exists in wp_options) and that no configuration management tool is restoring an older value.
  • Cron schedule changes are ignored. The scheduler reschedules WP-Cron only when its reschedule() method is called. Use the Import & Limits tab to save the new schedule rather than editing the option directly.
  • A migration unexpectedly resets an option. Only the ANALYTICS_REQUIRE_CONSENT value is intentionally normalised by migration step 2 (forced to 0). All other settings are preserved by the migration steps.
  • Stale or large autoloaded data. Inspect the autoloaded option size in wp_options and disable autoload for any custom plugin options you may have added that store large arrays.