HTML API: Backport from Gutenberg of layout image container refactor.

Trac ticket: Core-63694.
See WordPress/gutenberg#72264.

For classic themes, image blocks need to create a DIV wrapper which
contains alignment classes from the inner FIGURE. This has been
processed using PCRE matching.

With this change the HTML API is used instead of PCRE functions to
provide more semantic transformation, clearer intent, and eliminate
possible parsing issues.

Author: dmsnell

src/wp-includes/block-supports/layout.php

@@ -1074,50 +1074,53 @@ static function ( $matches ) {
  * @return string Filtered block content.
  */
 function wp_restore_image_outer_container( $block_content, $block ) {
-	$image_with_align = "
-/# 1) everything up to the class attribute contents
-(
-	^\s*
-	<figure\b
-	[^>]*
-	\bclass=
-	[\"']
-)
-# 2) the class attribute contents
-(
-	[^\"']*
-	\bwp-block-image\b
-	[^\"']*
-	\b(?:alignleft|alignright|aligncenter)\b
-	[^\"']*
-)
-# 3) everything after the class attribute contents
-(
-	[\"']
-	[^>]*
-	>
-	.*
-	<\/figure>
-)/iUx";
+	if ( wp_theme_has_theme_json() ) {
+		return $block_content;
+	}
 
+	$figure_processor = new WP_HTML_Tag_Processor( $block_content );
 	if (
-		wp_theme_has_theme_json() ||
-		0 === preg_match( $image_with_align, $block_content, $matches )
+		! $figure_processor->next_tag( 'FIGURE' ) ||
+		! $figure_processor->has_class( 'wp-block-image' ) ||
+		! (
+			$figure_processor->has_class( 'alignleft' ) ||
+			$figure_processor->has_class( 'aligncenter' ) ||
+			$figure_processor->has_class( 'alignright' )
+		)
 	) {
 		return $block_content;
 	}
 
-	$wrapper_classnames = array( 'wp-block-image' );
+	/*
+	 * The next section of code wraps the existing figure in a new DIV element.
+	 * While doing it, it needs to transfer the layout and the additional CSS
+	 * class names from the original figure upward to the wrapper.
+	 *
+	 * Example:
+	 *
+	 *     // From this…
+	 *     <!-- wp:image {"className":"hires"} -->
+	 *     <figure class="wp-block-image wide hires">…
+	 *
+	 *     // To this…
+	 *     <div class="wp-block-image hires"><figure class="wide">…
+	 */
+	$wrapper_processor = new WP_HTML_Tag_Processor( '<div>' );
+	$wrapper_processor->next_token();
+	$wrapper_processor->set_attribute(
+		'class',
+		is_string( $block['attrs']['className'] ?? null )
+			? "wp-block-image {$block['attrs']['className']}"
+			: 'wp-block-image'
+	);
 
-	// If the block has a classNames attribute these classnames need to be removed from the content and added back
-	// to the new wrapper div also.
-	if ( ! empty( $block['attrs']['className'] ) ) {
-		$wrapper_classnames = array_merge( $wrapper_classnames, explode( ' ', $block['attrs']['className'] ) );
+	// And remove them from the existing content; it has been transferred upward.
+	$figure_processor->remove_class( 'wp-block-image' );
+	foreach ( $wrapper_processor->class_list() as $class_name ) {
+		$figure_processor->remove_class( $class_name );
 	}
-	$content_classnames          = explode( ' ', $matches[2] );
-	$filtered_content_classnames = array_diff( $content_classnames, $wrapper_classnames );
 
-	return '<div class="' . implode( ' ', $wrapper_classnames ) . '">' . $matches[1] . implode( ' ', $filtered_content_classnames ) . $matches[3] . '</div>';
+	return "{$wrapper_processor->get_updated_html()}{$figure_processor->get_updated_html()}</div>";
 }
 
 add_filter( 'render_block_core/image', 'wp_restore_image_outer_container', 10, 2 );

tests/phpunit/tests/block-supports/layout.php

@@ -74,7 +74,7 @@ public function test_outer_container_not_restored_for_non_aligned_image_block_wi
 		$block_content = '<figure class="wp-block-image size-full"><img src="/my-image.jpg"/></figure>';
 		$expected      = '<figure class="wp-block-image size-full"><img src="/my-image.jpg"/></figure>';
 
-		$this->assertSame( $expected, wp_restore_image_outer_container( $block_content, $block ) );
+		$this->assertEqualHTML( $expected, wp_restore_image_outer_container( $block_content, $block ) );
 	}
 
 	/**
@@ -90,7 +90,7 @@ public function test_outer_container_restored_for_aligned_image_block_with_non_t
 		$block_content = '<figure class="wp-block-image alignright size-full"><img src="/my-image.jpg"/></figure>';
 		$expected      = '<div class="wp-block-image"><figure class="alignright size-full"><img src="/my-image.jpg"/></figure></div>';
 
-		$this->assertSame( $expected, wp_restore_image_outer_container( $block_content, $block ) );
+		$this->assertEqualHTML( $expected, wp_restore_image_outer_container( $block_content, $block ) );
 	}
 
 	/**
@@ -111,7 +111,7 @@ public function test_additional_styles_moved_to_restored_outer_container_for_ali
 			),
 		);
 
-		$this->assertSame( $expected, wp_restore_image_outer_container( $block_image_html, $block ) );
+		$this->assertEqualHTML( $expected, wp_restore_image_outer_container( $block_image_html, $block ) );
 	}
 
 	/**
@@ -165,7 +165,7 @@ public function test_outer_container_not_restored_for_aligned_image_block_with_t
 		$block_content = '<figure class="wp-block-image alignright size-full is-style-round my-custom-classname"><img src="/my-image.jpg"/></figure>';
 		$expected      = '<figure class="wp-block-image alignright size-full is-style-round my-custom-classname"><img src="/my-image.jpg"/></figure>';
 
-		$this->assertSame( $expected, wp_restore_image_outer_container( $block_content, $block ) );
+		$this->assertEqualHTML( $expected, wp_restore_image_outer_container( $block_content, $block ) );
 	}
 
 	/**