Automatic Optimization

How Auto-Optimize Works #

The plugin’s automatic optimization workflow runs during WordPress attachment metadata generation. It is not a background queue, cron job, or delayed processor. The loaded docs confirm that auto-optimize is attached directly to the wp_generate_attachment_metadata filter and runs synchronously inside that lifecycle.

The documented hook registration is:

add_filter( 'wp_generate_attachment_metadata', 'davix_h2i_auto_optimize_attachment', 20, 2 )

The source-backed behavior docs describe the flow as:

• WordPress triggers wp_generate_attachment_metadata
• the plugin runs davix_h2i_auto_optimize_attachment( $metadata, $attachment_id )
• it checks whether auto-optimize is enabled and whether the attachment should be skipped
• it reads configured chips, fields, and optional prefix from settings
• it sanitizes and filters those values
• it builds an image-service request payload
• it sends that payload to PixLab through the image API wrapper
• it parses the returned result
• it downloads or reconstructs the optimized file
• it replaces the original attachment
• it writes the auto-optimize marker meta
• if anything fails, it returns the original metadata unchanged

This is a replace-only workflow. The loaded overview docs explicitly confirm that auto optimization always calls attachment save with $replace = true.

When Auto-Optimize Runs #

Auto-optimize runs only during the attachment metadata generation lifecycle and only when the feature is enabled. The user guide describes this as Auto-optimize on Upload, and the troubleshooting guide confirms the same hook path.

The configuration lives in the option:

• davix_h2i_auto_optimize

The documented option shape is:

• enabled
• apply_to_generated
• chips
• fields
• prefix

The installation and configuration docs confirm the read-side defaults used by the UI and sanitization layer:

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

That means the first-run default behavior is that auto-optimize is off until it is explicitly enabled in settings.

What It Processes #

The auto-optimize workflow processes image attachments only. The troubleshooting guide and overview both confirm that it skips attachments whose MIME type does not begin with image/.

The workflow reads these user-configurable values from the auto-optimize settings:

• selected image chips
• selected image fields
• optional prefix

Before sending anything upstream, the plugin sanitizes and filters those values:

• chips are sanitized with sanitize_key
• chips are intersected with the allowed image chip list
• fields are filtered according to the selected chips
• fields are then parsed through the image field parser
• prefix is sanitized for filename-safe use

Because auto-optimize uses the same image-processing model as manual image workflows, it is constrained by the same chip system. The allowed chip groups documented for the plugin are:

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

The plugin does not document auto-optimize as applying to arbitrary non-media content or non-image uploads. Its documented scope is upload-time processing of image attachments inside the WordPress media lifecycle.

[Image placeholder — Auto-Optimize settings showing enable, apply-to-generated, chips, fields, and prefix]

Replace-Only Behavior #

Auto-optimize always uses replace behavior. The loaded docs are explicit on this point:

• the overview states that auto optimization always calls attachment save with $replace = true
• the user guide says it updates the original attachment when successful
• the upload automation flow is described as replacing the attachment rather than creating a copy

That means auto-optimize does not use the Image output mode setting to choose between replace and copy. Unlike manual Image generate or H2I generate, auto-optimize is not described as having a copy mode. It is a direct in-place optimization path for the original attachment.

This also means the plugin persists the optimized result back onto the existing media item instead of inserting a second attachment for the same upload.

Generated Attachment Handling #

Two post meta markers are central to the automatic optimization workflow:

• _davix_h2i_generated
• _davix_h2i_auto_optimized

The appendix documents their roles clearly:

• _davix_h2i_generated marks attachments generated by plugin output flows and is used by auto-optimize when apply_to_generated is false
• _davix_h2i_auto_optimized marks successful auto-optimization and is checked at the start of auto-optimize to prevent repeat processing

The user guide also explains the user-facing behavior of Apply auto-optimize to Davix-generated images:

• when it is disabled, the workflow can skip attachments already marked with _davix_h2i_generated

This is important because the plugin distinguishes between:

• assets produced by the plugin’s own image or H2I generation flows
• attachments that have already been auto-optimized successfully

Skip Conditions and Safeguards #

The loaded docs provide a detailed set of skip conditions for davix_h2i_auto_optimize_attachment().

Feature Disabled #

If davix_h2i_auto_optimize['enabled'] is empty or false, auto-optimize exits immediately and returns the original metadata.

Invalid or Unusable Attachment Context #

The overview docs include invalid attachment ID among the documented skip rules for the auto-optimize flow.

Recursion Guard #

The workflow uses a static in-progress guard keyed by attachment ID. This prevents recursive re-entry during metadata generation.

Generated-Image Skip #

If apply_to_generated is false and _davix_h2i_generated exists on the attachment, the workflow skips that item.

Already Auto-Optimized Skip #

If _davix_h2i_auto_optimized already exists, the plugin skips processing to avoid repeated optimization on the same attachment.

Non-Image MIME Skip #

If get_post_mime_type() does not start with image/, the workflow skips the attachment.

Missing File Skip #

If get_attached_file() is missing or the file does not exist on disk, the workflow skips processing.

Downstream Failure Safeguards #

The overview and behavior docs also mention downstream failures as skip or exit conditions that result in returning the original metadata rather than surfacing a REST error. This includes failures in request execution, output parsing, downloading, temp writing, sideloading, or replacement.

Unlike manual REST workflows, auto-optimize does not return a WP_Error to a user-facing request path. Failures are logged when logging is enabled, and the original metadata is returned.

Output Retrieval and Persistence Path #

The behavior docs describe the output-handling path in detail. After the plugin sends the image-service request, it parses the response and attempts to extract:

• a result URL
• or binary output content

The persistence paths are:

URL Result Path #

• download with download_url(..., 60)
• sideload with davix_h2i_handle_sideload_file()
• replace the original attachment with davix_h2i_create_or_replace_attachment(..., true)

Binary Result Path #

• write temp content via davix_h2i_write_binary_to_temp()
• sideload via davix_h2i_handle_sideload_file()
• replace the original attachment with davix_h2i_create_or_replace_attachment(..., true)

This confirms again that auto-optimize is not a preview workflow and not a non-persistent analysis flow. It is a synchronous request-and-replace pipeline.

Logging and Failure Visibility #

The loaded docs state that auto-optimize failures are logged and the original metadata is returned. That means the best user-visible troubleshooting path for auto-optimize issues is the plugin’s logging system when logging is enabled.

The Debug Log setting controls whether logs are written. When enabled, logs are stored in:

wp_upload_dir()['basedir'] . '/davix-h2i/logs/davix-h2i-<token>.log'

The troubleshooting guide also gives a concise verification checklist for auto-optimize not triggering:

• inspect option davix_h2i_auto_optimize and confirm enabled and apply_to_generated
• inspect post meta _davix_h2i_generated
• inspect post meta _davix_h2i_auto_optimized
• verify post_mime_type
• verify the path from get_attached_file() exists on disk

No Queue or Deferred Processing #

The loaded overview docs explicitly confirm that there is:

• no background queue system
• no cron scheduling for this workflow

That is important for public documentation because it means auto-optimize happens inline with the upload metadata process, not later in an asynchronous worker.

End-to-End Automatic Optimization Summary #

The fully source-backed automatic optimization workflow is:

1. WordPress generates attachment metadata for an uploaded media item.
2. The plugin’s davix_h2i_auto_optimize_attachment() filter runs.
3. It checks whether auto-optimize is enabled and whether the attachment should be skipped.
4. It verifies the item is an image and that the file exists.
5. It reads configured chips, fields, and optional prefix from davix_h2i_auto_optimize.
6. It sanitizes and filters those values according to the image chip model.
7. It sends the request to PixLab through the image API wrapper.
8. It downloads or reconstructs the optimized output.
9. It replaces the original attachment.
10. It writes _davix_h2i_auto_optimized = 1 on success.
11. If anything fails, it logs the issue when logging is enabled and returns the original metadata.