Image Replacement

When you process images with the Analyze & Export or Compress & Export Only pipelines, Picture Optimizer replaces the original attachment file in WordPress with the processed version. This page explains what happens during replacement and how your site stays consistent.

What Happens During Replacement

1. Backup Original

Before any changes, the original file is copied to a dedicated backup directory:

wp-content/uploads/image-forge-originals/YYYY/MM/original-filename.jpg

The backup path is stored in the _image_forge_original_file post meta for the attachment.

2. Download Processed File

The processed image is downloaded from the Picture Optimizer cloud service to a temporary location on your server.

3. Replace the File

• Old thumbnails generated by WordPress are deleted
• The processed file is copied to the attachment's location
• If the filename or extension changed, _wp_attached_file meta is updated
• WordPress regenerates all thumbnail sizes from the new file
• The attachment's MIME type is updated if the format changed

4. Update URL References

If the filename or extension changed (e.g., IMG_1234.jpg → sunset-beach-landscape.webp), the plugin runs a multi-layer URL update:

Content Search & Replace

All old URLs are replaced with new URLs across:

• wp_posts.post_content — Page and post content (Gutenberg blocks, classic editor HTML)
• wp_postmeta.meta_value — Page builder data (Elementor, WPBakery, Beaver Builder, etc.)
• wp_options.option_value — Widget settings, theme mods, Customizer data

This covers both the full-size image URL and all thumbnail URLs (e.g., image-300x200.jpg → mapped to the new equivalent).

.htaccess Redirect

A RedirectMatch 301 rule is added as a safety net:

# BEGIN Picture Optimizer Redirects
RedirectMatch 301 ^/wp-content/uploads/2024/03/IMG_1234\.jpg$ /wp-content/uploads/2024/03/sunset-beach-landscape.webp
# END Picture Optimizer Redirects

This catches any references the database search missed — external links, cached pages, RSS feeds, etc.

GUID Update

The WordPress guid column on the attachment post is updated to the new URL. Some plugins and RSS feeds read this column directly.

5. Apply Metadata

AI-generated metadata is stored and applied:

• post_title — Descriptive title
• _wp_attachment_image_alt — Alt text
• post_excerpt — Caption
• Custom post meta _image_forge_metadata — Full AI output (tags, filename, etc.)

6. Fire Action Hook

After replacement, the plugin fires:

do_action( 'image_forge_after_replace', $attachment_id, $old_url, $new_url, $backup_path );

Third-party plugins can hook into this for CDN cache purging, logging, or other integrations. See CDN Integration.

What Gets Backed Up

All of this data is used by the revert system to fully restore the original state.