Image Workflows

Image Preview #

The plugin’s Image Preview workflow is the non-persistent path for testing image transformations before writing anything into the Media Library. In the documented UI, the Image tab supports chips, fields, and output mode, and preview sends a request to /image/preview and returns preview URLs for display. The user guide is explicit that no attachment write happens in the preview path.

On the server side, the preview workflow is documented as:

• trigger: POST /davix-h2i/v1/image/preview
• callback chain: davix_h2i_image_preview() → davix_h2i_handle_image_request(..., 'preview')
• permission gate: davix_h2i_rest_permissions()
• nonce header: x_wp_nonce
• nonce action: wp_rest
• capability requirement: upload_files
• per-attachment permission check: current_user_can( 'edit_post', $attachment_id )

The documented request inputs for preview are:

• ids
• chips
• fields
• output

Those values are sanitized before the PixLab request is built:

• ids are converted with absint and empty values are removed
• chips are sanitized with sanitize_key and intersected with the allowlist
• fields are parsed through davix_h2i_parse_image_fields()
• output is sanitized with davix_h2i_sanitize_output_settings()

The preview response shape is documented as:

{
  "results": [
    {
      "id": 123,
      "url": "..."
    }
  ]
}

The behavior docs explain that preview parses results or a body fallback, aligns missing id values by input index when needed, and extracts preview URLs from the response. No attachment or file persistence is performed in this path.

Image Generate #

The Image Generate workflow is the persistent path. In the UI, generate sends a request to /image/generate and writes results into the Media Library. The plugin overview and user guide both describe generate as the flow that downloads or sideloads the output and then either replaces the existing attachment or creates a new attachment.

The documented server-side flow is:

• trigger: POST /davix-h2i/v1/image/generate
• callback chain: davix_h2i_image_generate() → davix_h2i_handle_image_request(..., 'generate')
• same permission requirements as preview
• same request input and sanitization model as preview
• external call through davix_h2i_call_image_api($payload, 'image generate', 'generate')

The generate path differs from preview in output handling. The documented behavior is:

• it extracts either a URL or binary result for each item
• URL output is downloaded and sideloaded
• binary output is written to a temp file and then sideloaded
• it then calls davix_h2i_create_or_replace_attachment(...)
• replace is used when output mode is replace; otherwise copy behavior is used

The documented response model for generate is array-of-results based, because the handler processes ids as an array even when a user selected a single item. The response returns per-item objects inside results, and item-level failures stay embedded in those result objects instead of always being promoted to a top-level WP_Error.

Supported Image Chips #

The Image modal tab supports a chip-based model. The documented allowed chip keys are:

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

The appendix glossary describes a chip as a named image operation group used to control which image fields are allowed, stored, and sent in requests. It also confirms that chip enforcement happens by intersecting requested chips with allowed chips and then filtering fields to chip-allowed keys before building the final payload.

This chip model is not limited to the modal UI. The same documented behavior appears in:

• settings sanitization for image defaults
• manual image preview and generate handling
• auto-optimize processing on upload

[Image placeholder — Image tab showing chip selection for smart, format, resize, crop, transform, effects, padding, frame, background, and watermark]

Field Filtering Behavior #

Field filtering is a core rule of the image workflow. The user guide states that only fields belonging to the selected chips are sent from the modal UI, and the server side also sanitizes and accepts only known image fields.

The behavior docs describe the sanitization chain in more detail:

• chips are sanitized and intersected with the allowlist
• fields are passed through davix_h2i_parse_image_fields()
• for auto-optimize, fields are first filtered with davix_h2i_filter_chip_fields() and then parsed again

This means the image workflow has two layers of protection:

• the interface only collects fields for the chosen chips
• the backend still re-validates and filters fields before sending anything to PixLab

That behavior applies both to manual image actions and to auto-optimize on upload.

Replace vs Copy Output Modes #

Image generation supports two output modes:

• replace
• copy

The user guide confirms the interface behavior:

• output mode values are replace or copy
• the suffix field is shown only when mode is copy
• suffix is applied only when not replacing

The appendix glossary defines output mode more formally:

• replace overwrites the existing attachment file and record path
• copy creates a new attachment
• both are supported for image and H2I outputs

Replace Mode #

In replace mode, the plugin updates the existing attachment. The admin-operations docs confirm that the replace path in davix_h2i_create_or_replace_attachment() performs:

• wp_update_post(...)
• update_attached_file( $attachment_id, $file_path )
• metadata regeneration via wp_generate_attachment_metadata
• metadata update via wp_update_attachment_metadata

The troubleshooting guide also documents an important consequence: replace mode can overwrite the original image mapping, and no backup or rollback is created in that function.

Copy Mode #

In copy mode, the plugin inserts a new attachment instead of overwriting the existing one. The user guide describes this as “new attachment is inserted,” and the admin-operations docs confirm that the copy path uses wp_insert_attachment and then generates metadata for the new attachment ID.

Suffix Behavior #

Suffix belongs to output settings and is used only when the mode is not replace. The documented UI behavior is that the suffix field appears when mode is copy, and the behavior docs confirm that the suffix is applied inside the non-replace branch.

[Image placeholder — Output mode controls showing Replace and Copy, with the suffix field visible only for Copy]

Bulk Image Processing Behavior #

Bulk processing is a first-class part of the image workflow. The plugin overview explicitly states that image handlers process an ids array and iterate over each selected attachment ID.

The user-facing bulk entry point in WordPress admin is the Media Library bulk action:

• hook: bulk_actions-upload
• action key: davix_h2i_edit
• label: Edit with Davix H2I

When that action is selected and applied in the Media Library list table, the documented JavaScript behavior is that it intercepts the action and opens the Davix modal for the selected IDs.

On the backend, both preview and generate are array-based flows.

Bulk Preview Behavior #

The preview flow:

• requires ids
• validates each attachment permission
• parses results as an array
• aligns missing IDs by input index
• returns results with per-item id and url values

Bulk Generate Behavior #

The generate flow:

• also uses the ids array
• processes output per result item
• can embed per-item errors inside the returned results
• still uses top-level WP_Error only for request-level failures such as permission, validation, or transport/upstream problems

This matters for user-facing behavior: in bulk generation, some items can fail while others succeed, and the workflow returns item-level result objects rather than a single all-or-nothing response shape.

Attachment and Permission Checks #

Image workflows are not anonymous actions. The documented permission model for image preview and generate is:

• valid x_wp_nonce
• nonce action wp_rest
• upload_files capability
• per-attachment edit_post permission checks

The troubleshooting guide adds practical implications for these checks:

• missing or invalid nonce results in davix_h2i_invalid_nonce with status 403
• if one attachment in a bulk request is not editable by the current user, handlers can emit davix_h2i_forbidden_attachment
• if the user lacks upload_files, the general permission callback returns false for image routes

Source File Requirements #

The image workflow requires real attachment files to exist on disk. The troubleshooting guide documents the davix_h2i_missing_file error and explains that the plugin validates source files through get_attached_file() and file_exists() checks.

This is relevant for both preview and generate, because the workflow prepares image files before sending them to PixLab. If the attachment entry exists in WordPress but the physical file is missing, image operations can fail before any upstream processing happens.

Auto-Optimize and Image Workflow Relationship #

Although auto-optimize is configured separately, it uses the same image-processing model. The behavior docs show that the upload-time auto-optimize flow:

• runs on wp_generate_attachment_metadata
• reads chips, fields, and optional prefix
• sanitizes chips through the allowlist
• filters and parses fields
• calls the image API in generate mode
• always persists through replace mode
• marks successful results with _davix_h2i_auto_optimized = 1

The documented skip rules for auto-optimize include:

• feature disabled
• recursion guard hit
• generated-image skip condition when apply_to_generated is false
• already auto-optimized marker present
• non-image MIME type
• missing file
• downstream processing failures, in which case original metadata is returned

This matters because the same chip and field rules from manual image workflows also govern the automatic workflow.

Common Image Workflow Errors #

The troubleshooting guide documents the main image-specific failures users may encounter.

davix_h2i_missing_ids #

Thrown when the image request does not include a usable ids array.

davix_h2i_missing_file #

Returned when the attachment’s physical source file cannot be found.

davix_h2i_missing_output_url #

In preview, this means the parsed PixLab response did not contain a usable preview URL. In generate, the behavior docs explain that if a result has neither a usable URL nor binary content, the item response contains an embedded error such as Missing output URL. for that item.

Replace-Mode Overwrite Behavior #

The troubleshooting guide explicitly notes that replace mode overwrites the attachment mapping through update_attached_file(...), and no rollback is created in that function.

End-to-End Image Workflow Summary #

The fully documented image workflow is:

1. Open the Davix H2I modal from the Media Library or attachment edit context.
2. Select one or more attachments. Bulk mode uses the ids array.
3. Choose image chips and provide only the fields relevant to those chips.
4. Choose output mode:
   • replace to update the current attachment
   • copy to create a new attachment, optionally with suffix
5. Run Preview to get URLs only, with no Media Library write.
6. Run Generate to download or sideload output and persist it in the Media Library.