Configuration Reference

General Settings #

The plugin registers its settings through the WordPress Settings API in davix_h2i_register_settings(). The documented configuration surface includes API and auth settings, idempotency settings, timeout and retry settings, H2I payload settings, feature defaults, output settings, auto-optimize settings, tools defaults, and the logging toggle. The General tab is the main place for global connection and request-behavior controls.

The user-facing General tab includes these verified control areas:

• API key
• auth mode
• idempotency
• HTTP timeout
• retry count
• H2I max payload
• debug logging toggle

The loaded docs also confirm visible default examples shown in the settings view for timeout, retry, and H2I payload settings. For exact numeric limits and system-wide interpretation, use the central Errors and Limits page where relevant.

API Key #

The API key option is davix_h2i_api_key, represented by DAVIX_H2I_OPTION_API_KEY. It is used by the outbound PixLab client when building request headers. The sanitization behavior documented in the setup materials is:

• blank submission does not clear the existing key
• non-empty input replaces the stored value

Authentication Mode #

The auth mode option is davix_h2i_auth_mode, represented by DAVIX_H2I_OPTION_AUTH_MODE. The integration and security docs confirm these runtime behaviors:

• bearer sends Authorization: Bearer <api_key>
• any other value falls back to X-Api-Key: <api_key>
• the default and fallback auth mode is x-api-key

H2I Max Payload #

The H2I payload setting is stored in davix_h2i_h2i_max_payload_kb, represented by DAVIX_H2I_OPTION_H2I_MAX_PAYLOAD_KB. The runtime compares the combined byte length of HTML and CSS against this configured value. The loaded docs confirm that this setting is part of the General tab and is enforced at runtime. Oversized single requests can return davix_h2i_payload_too_large, while bulk requests can produce item-level errors.

Image Defaults #

Image defaults are stored in option davix_h2i_image_defaults. The developer reference describes this option as an array containing selected chips and filtered fields, sanitized by davix_h2i_sanitize_image_defaults(). Chips are intersected with the allowlist, and fields are filtered according to the selected chips and allowed field types. If unset, the read-side default is an empty array before sanitization.

The documented chip groups supported by the plugin are:

• smart
• format
• resize
• crop
• transform
• effects
• padding
• frame
• background
• watermark

The key configuration behavior for Image Defaults is filtering. The plugin documentation confirms that the chip system controls which fields are allowed to be stored and later sent. That filtering behavior appears in settings sanitization, manual image requests, and upload auto-optimize. In practice, unsupported or non-chip-matching image fields are not preserved as active defaults.

From the user-facing settings perspective, the Image tab contains default image chips and fields, and those defaults are surfaced to the admin UI through DavixH2IData.defaults.imageDefaults.

[Image placeholder — Image Defaults section showing selected chips and related default fields]

Image Output Settings #

Image output settings are stored in davix_h2i_image_output. The documented option shape is:

• mode
• suffix

Sanitization is handled by davix_h2i_sanitize_output_settings(). The mode allowlist is:

• replace
• copy

If the option is not set, the documented fallback configuration is:

• mode: 'replace'
• suffix: ''

The user guide explains the output behavior this configuration controls:

• replace updates the existing attachment file/reference and regenerates metadata
• copy inserts a new Media Library attachment
• suffix is applied only in copy mode

The loaded plugin docs also note, in user-facing terms, that replace mode does not create a plugin-managed backup or rollback path before overwriting the attachment mapping.

Auto-Optimize Settings #

Auto-optimize settings are stored in option davix_h2i_auto_optimize. The documented option shape is:

• enabled
• apply_to_generated
• chips
• fields
• prefix

Sanitization is handled by davix_h2i_sanitize_auto_optimize(). The documented fallback defaults are:

• enabled = 0
• apply_to_generated = 1
• chips = []
• fields = []
• prefix = ''

The user-facing settings page confirms that the Auto-Optimize subtab exposes these controls:

• enable checkbox
• apply-to-generated checkbox
• chips and fields selection
• optional prefix

The runtime behavior of those settings is also documented clearly:

• auto-optimize runs on wp_generate_attachment_metadata
• it runs only when enabled is truthy
• it can skip generated files when apply_to_generated is false and _davix_h2i_generated exists
• it skips already auto-optimized files when _davix_h2i_auto_optimized exists
• it skips non-image MIME types
• it uses replace behavior when successful

The prefix value is sanitized for filename use and is described as optional text used in the generated output filename path for auto-optimize results.

[Image placeholder — Auto-Optimize settings showing enable, apply-to-generated, chip selection, field selection, and prefix]

H2I Defaults #

H2I defaults are stored in option davix_h2i_h2i_defaults. The documented option shape is:

• html
• css
• width
• height
• format

Sanitization is handled by davix_h2i_sanitize_h2i_defaults(). The format allowlist documented for stored defaults is:

• png
• jpeg

If the option is not set, the read-side state is an empty array before sanitization.

The settings page and user guide describe the H2I tab as the place for default:

• HTML
• CSS
• size
• format
• output settings

The H2I configuration model also includes token-aware content. The plugin supports these replacement tokens in H2I HTML and CSS templates:

• {site_name}
• {site_logo_url}
• {selected_image_url}
• {author_name}
• {date}
• {post_title}

These tokens are not separate saved options, but they are part of how users configure reusable H2I template defaults in the settings interface and later in the modal. The user-facing settings page includes a Supported Tokens section.

H2I Output Settings #

H2I output settings are stored in davix_h2i_h2i_output. Like image output settings, the documented shape is:

• mode
• suffix

Sanitization is handled by the same davix_h2i_sanitize_output_settings() function. The documented fallback is:

• mode: 'replace'
• suffix: ''

The user guide confirms that H2I generate follows the same output-mode model as Image generate:

• replace updates the selected existing attachment file/reference and regenerates metadata
• copy creates a new attachment
• suffix is applied only in copy mode

Because the plugin uses one shared output-settings sanitizer for both image and H2I outputs, the configuration model and behavioral expectations are aligned across both feature areas.

Tools Defaults #

Tools defaults are stored in davix_h2i_tools_defaults. The developer reference documents that they are sanitized by davix_h2i_sanitize_tools_defaults(). If the option is not set, the read-side default is an empty array.

The sanitization and behavior docs confirm these supported tools settings:

• hash types: phash, md5, sha1, sha256
• similarity mode: pairs, tofirst
• similarity threshold: supported and sanitized
• selection normalization for use_hash and use_similarity

The user-facing Tools settings area is described as containing default tool selection plus similarity and hash defaults. Those values are then surfaced to the modal through DavixH2IData.defaults.toolsDefaults.

The same settings family corresponds to the Tools modal behavior described in the user guide:

• selectable tools: hash, similarity
• supported hash types: phash, md5, sha1, sha256
• supported similarity modes: pairs, tofirst
• similarity requires at least two images

Logging Settings #

Logging is controlled by option davix_h2i_log_enabled, also represented by DAVIX_H2I_LOG_OPTION. It is registered through the settings system and read as an integer/bool-like flag. The developer reference notes that read sites treat the fallback as false.

The user-facing settings page exposes this as the Enable debug logging toggle, and the user guide states its default is off.

When this option changes, the plugin’s update hook triggers davix_h2i_log_option_updated(), which calls davix_h2i_toggle_log(). The documented side effects are:

When enabled

• hardens the log directory
• truncates or creates the active log file

When disabled

• deletes matching davix-h2i*.log* files
• does not necessarily remove the log directory or hardening files in all documented descriptions of disable behavior

The primary log path model is also documented:

• directory: <uploads basedir>/davix-h2i/logs
• file: <uploads basedir>/davix-h2i/logs/davix-h2i-<token>.log

The log subsystem also creates hardening files when missing:

• index.php
• .htaccess
• web.config

[Image placeholder — Debug Log settings section with the Enable debug logging toggle]

Idempotency Settings #

Idempotency is configured through two settings:

• davix_h2i_idempotency_enabled
• davix_h2i_idempotency_header

The settings page exposes the enable toggle as Idempotency enabled. The allowed header names are documented as:

• Idempotency-Key
• X-Idempotency-Key

If an invalid header name is saved, sanitization falls back to Idempotency-Key.

The outbound request client applies the idempotency header whenever idempotency is enabled. The key value itself is generated by davix_h2i_generate_idempotency_key() using wp_generate_uuid4(). This behavior applies across PixLab service requests because Image, H2I, and Tools wrappers all call the shared davix_h2i_request() client.

Timeout and Retry Settings #

The plugin exposes timeout and retry as configurable settings in the General tab.

Timeout #

Timeout is stored in option davix_h2i_timeout, represented by DAVIX_H2I_OPTION_TIMEOUT. The user guide confirms the field label HTTP timeout (seconds). The troubleshooting guide documents runtime clamping behavior.

Retry Count #

Retry count is stored in option davix_h2i_retry_count, represented by DAVIX_H2I_OPTION_RETRY. The user guide confirms the field label Retry count. The troubleshooting guide documents runtime clamping behavior and confirms that attempts equal retry plus one.

The overview and architecture docs also confirm that the shared client implements retry attempts in a simple immediate retry loop and does not document exponential backoff logic.

Configuration Data in the Admin UI #

The plugin’s admin UI localizes a DavixH2IData object that includes a defaults section with:

• imageDefaults
• imageOutput
• autoOptimize
• h2iDefaults
• h2iOutput
• toolsDefaults

That means the saved configuration described above is not only stored in WordPress options; it is also surfaced to the settings and modal interfaces as the current default state for those workflows.

Configuration Summary by Option Key #

The loaded docs confirm this configuration map:

• davix_h2i_log_enabled — debug logging toggle
• davix_h2i_api_key — API key
• davix_h2i_auth_mode — auth mode
• davix_h2i_idempotency_enabled — idempotency toggle
• davix_h2i_idempotency_header — idempotency header name
• davix_h2i_timeout — HTTP timeout
• davix_h2i_retry_count — retry count
• davix_h2i_h2i_max_payload_kb — H2I payload setting
• davix_h2i_image_defaults — default image chips and fields
• davix_h2i_image_output — image output mode and suffix
• davix_h2i_auto_optimize — auto-optimize configuration
• davix_h2i_h2i_defaults — default H2I HTML, CSS, size, and format
• davix_h2i_h2i_output — H2I output mode and suffix
• davix_h2i_tools_defaults — tools defaults