URL Management

How Picture Optimizer keeps all image URLs consistent after filename changes.

The Problem

When Picture Optimizer replaces an image with a processed version, the filename and/or extension may change:

  • AI-generated filename: IMG_4521.jpg → sunset-california-beach-landscape.webp
  • Format conversion only: photo.jpg → photo.webp

These changes break any existing references to the old URL — in post content, page builders, widgets, theme settings, and external links.

The Solution

Picture Optimizer implements a four-layer approach to ensure all references stay working:

Layer 1: Database Search & Replace

The plugin searches and replaces old URLs with new URLs across three database tables:

TableColumnWhat It Catches
wp_postspost_contentGutenberg blocks, classic editor HTML, image tags
wp_postmetameta_valuePage builder data (Elementor, WPBakery, Beaver Builder, Divi, etc.)
wp_optionsoption_valueWidget settings, theme mods, Customizer data, site options

The replacement covers:

  • The full-size image URL (e.g., image.jpg → image.webp)
  • All thumbnail URLs (e.g., image-300x200.jpg → image-300x200.webp)

A mapping of old → new filenames is built by correlating old WordPress thumbnail metadata with newly regenerated thumbnail metadata.

Layer 2: .htaccess Redirects

A RedirectMatch 301 rule is added to .htaccess as a safety net:

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

This catches references that the database search missed:

  • External websites linking to your images
  • Cached pages served by CDN or browser cache
  • RSS feed readers that cached the old URL
  • Social media embeds with the old URL

Layer 3: GUID Column Update

The WordPress guid column on the attachment post is updated to the new URL. While WordPress core doesn't use guid for front-end display, some plugins and RSS feeds read it directly.

Layer 4: Action Hook

A custom action hook fires after every replacement:

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

This allows third-party integrations to handle additional URL updates, such as:

  • Purging CDN caches
  • Updating custom database tables
  • Notifying external services

Revert Reversal

When an image is reverted, all URL management is undone:

  • Database replacements are reversed (new → old URLs)
  • .htaccess redirect rules are removed
  • GUID is restored to the original URL
  • A revert action hook fires for CDN purge

The replacement map is stored in _image_forge_url_replacements post meta, making the reversal exact and complete.

When URLs Don't Change

If the filename and extension remain the same after processing (e.g., compressing a JPEG to a smaller JPEG with the same name), no URL management is needed. The plugin detects $old_url === $new_url and skips all four layers.

Smart Skip & Re-process
How Picture Optimizer detects already-processed images and avoids redundant work.
CDN Integration
Using action hooks to integrate Picture Optimizer with CDN and caching systems.