Use wp_update_image_subsizes() for --only-missing on WP 5.3+ (#236)

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

features/media-regenerate.feature

@@ -869,6 +869,50 @@ Feature: Regenerate WordPress attachments
       {SCALED_CHECKSUM}
       """
 
+  @require-wp-5.3
+  Scenario: Regenerating only-missing sizes on WP 5.3+ uses wp_update_image_subsizes and does not recreate the scaled version
+    Given download:
+      | path                        | url                                          |
+      | {CACHE_DIR}/large-image.jpg | http://wp-cli.org/behat-data/large-image.jpg |
+    And I run `wp option update uploads_use_yearmonth_folders 0`
+
+    When I run `wp media import {CACHE_DIR}/large-image.jpg --title="My imported attachment" --porcelain`
+    Then save STDOUT as {ATTACHMENT_ID}
+    And the wp-content/uploads/large-image-scaled.jpg file should exist
+    And the wp-content/uploads/large-image-300x225.jpg file should exist
+
+    # Save a checksum of the scaled image before any regeneration.
+    When I run `md5sum wp-content/uploads/large-image-scaled.jpg`
+    Then save STDOUT as {SCALED_CHECKSUM}
+
+    # Add a new image size and a filter that produces drastically different output quality
+    # if the scaled image were regenerated from scratch.
+    Given a wp-content/mu-plugins/media-settings.php file:
+      """
+      <?php
+      add_action( 'after_setup_theme', function(){
+        add_image_size( 'test1', 400, 300, true );
+      });
+      // If the scaled image is regenerated, its checksum will differ because of this low quality.
+      add_filter( 'jpeg_quality', function() { return 1; } );
+      """
+
+    When I run `wp media regenerate {ATTACHMENT_ID} --only-missing --yes`
+    Then STDOUT should contain:
+      """
+      1/1 Regenerated thumbnails for "My imported attachment"
+      """
+    And the wp-content/uploads/large-image-400x300.jpg file should exist
+
+    # Verify the scaled image was NOT regenerated by wp_update_image_subsizes()
+    # (checksum should be unchanged, because wp_update_image_subsizes() only generates
+    # the missing sub-sizes and does not recreate the scaled/attached file).
+    When I run `md5sum wp-content/uploads/large-image-scaled.jpg`
+    Then STDOUT should be:
+      """
+      {SCALED_CHECKSUM}
+      """
+
   @require-wp-4.7.3 @require-extension-imagick
   Scenario: Regenerate a specific image size for a PDF attachment
     Given download:

src/Media_Command.php

@@ -775,6 +775,31 @@ private function process_regeneration( $id, $skip_delete, $only_missing, $delete
 		}
 		$site_icon_filter = $this->add_site_icon_filter( $id );
 
+		// On WP 5.3+, for the --only-missing case (no specific image sizes, not a PDF, and not a
+		// site-icon attachment), prefer wp_update_image_subsizes() which only generates sub-sizes
+		// that are absent from the attachment metadata and saves metadata incrementally after each
+		// sub-size, so partial progress is preserved if the server runs out of resources.
+		$can_use_wp53_subsizes = $only_missing && ! $image_sizes && ! $is_pdf && ! $site_icon_filter
+			&& function_exists( 'wp_get_missing_image_subsizes' ) && function_exists( 'wp_update_image_subsizes' );
+		if ( $can_use_wp53_subsizes ) {
+			$missing_sizes = wp_get_missing_image_subsizes( $id );
+			if ( ! empty( $missing_sizes ) ) {
+				$result = wp_update_image_subsizes( $id );
+				if ( is_wp_error( $result ) ) {
+					WP_CLI::warning( sprintf( '%s (ID %d)', $result->get_error_message(), $id ) );
+					WP_CLI::log( "$progress Couldn't regenerate thumbnails for $att_desc." );
+					++$errors;
+					return;
+				}
+				WP_CLI::log( "$progress Regenerated thumbnails for $att_desc." );
+				++$successes;
+				return;
+			}
+			// $missing_sizes is empty but needs_regeneration() returned true, which means some
+			// thumbnail files are physically missing from disk even though the metadata is intact.
+			// Fall through to the wp_generate_attachment_metadata() path below.
+		}
+
 		// When regenerating specific image size(s), use the file that WordPress normally
 		// serves (the scaled version for big images), not the original pre-scaled file.
 		// This prevents wp_generate_attachment_metadata() from re-creating the scaled