Enhance gallery and image block markup for ap_posts (#2519)

Author: obenland

.github/changelog/2519-from-description

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Improve gallery and image block markup for ap_posts with better alt text and optimized layouts.

includes/class-attachments.php

@@ -634,7 +634,12 @@ private static function generate_media_markup( $attachment_ids ) {
 			);
 		}
 
-		// Multiple attachments or images: use gallery block.
+		// Single image: use standalone image block.
+		if ( 1 === \count( $attachment_ids ) && 'image' === $type ) {
+			return self::get_image_block( $attachment_ids[0] );
+		}
+
+		// Multiple attachments: use gallery block.
 		return self::get_gallery_block( $attachment_ids );
 	}
 
@@ -684,10 +689,65 @@ private static function generate_files_markup( $files ) {
 			);
 		}
 
-		// Multiple attachments or images: use gallery block.
+		// Single image: use standalone image block.
+		if ( 1 === \count( $files ) && 'image' === $type ) {
+			return self::get_files_image_block( $files[0] );
+		}
+
+		// Multiple attachments: use gallery block.
 		return self::get_files_gallery_block( $files );
 	}
 
+	/**
+	 * Get standalone image block markup for file-based attachments.
+	 *
+	 * @param array $file {
+	 *     File data array.
+	 *
+	 *     @type string $url       Full URL to the file.
+	 *     @type string $mime_type MIME type of the file.
+	 *     @type string $alt       Alt text for the file.
+	 * }
+	 *
+	 * @return string The image block markup.
+	 */
+	private static function get_files_image_block( $file ) {
+		$block  = '<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->' . "\n";
+		$block .= '<figure class="wp-block-image size-large">';
+		$block .= '<img src="' . \esc_url( $file['url'] ) . '" alt="' . \esc_attr( $file['alt'] ) . '"/>';
+		$block .= '</figure>' . "\n";
+		$block .= '<!-- /wp:image -->';
+
+		return $block;
+	}
+
+	/**
+	 * Get standalone image block markup.
+	 *
+	 * @param int $attachment_id The attachment ID.
+	 *
+	 * @return string The image block markup.
+	 */
+	private static function get_image_block( $attachment_id ) {
+		$image_src = \wp_get_attachment_image_src( $attachment_id, 'large' );
+		if ( ! $image_src ) {
+			return '';
+		}
+
+		$alt = \get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
+		if ( ! $alt ) {
+			$alt = \get_post_field( 'post_excerpt', $attachment_id );
+		}
+
+		$block  = '<!-- wp:image {"id":' . \esc_attr( $attachment_id ) . ',"sizeSlug":"large","linkDestination":"none"} -->' . "\n";
+		$block .= '<figure class="wp-block-image size-large">';
+		$block .= '<img src="' . \esc_url( $image_src[0] ) . '" alt="' . \esc_attr( $alt ) . '" class="' . \esc_attr( 'wp-image-' . $attachment_id ) . '"/>';
+		$block .= '</figure>' . "\n";
+		$block .= '<!-- /wp:image -->';
+
+		return $block;
+	}
+
 	/**
 	 * Get gallery block markup.
 	 *
@@ -696,19 +756,23 @@ private static function generate_files_markup( $files ) {
 	 * @return string The gallery block markup.
 	 */
 	private static function get_gallery_block( $attachment_ids ) {
-		$gallery  = '<!-- wp:gallery {"ids":[' . \implode( ',', $attachment_ids ) . '],"linkTo":"none"} -->' . "\n";
-		$gallery .= '<figure class="wp-block-gallery has-nested-images columns-default is-cropped">';
+		$gallery  = '<!-- wp:gallery {"columns":2,"linkTo":"none","sizeSlug":"large","imageCrop":true} -->' . "\n";
+		$gallery .= '<figure class="wp-block-gallery has-nested-images columns-2 is-cropped">';
 
 		foreach ( $attachment_ids as $id ) {
 			$image_src = \wp_get_attachment_image_src( $id, 'large' );
 			if ( ! $image_src ) {
 				continue;
 			}
 
-			$caption  = \get_post_field( 'post_content', $id );
-			$gallery .= "\n<!-- wp:image {\"id\":{$id},\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n";
+			$alt = \get_post_meta( $id, '_wp_attachment_image_alt', true );
+			if ( ! $alt ) {
+				$alt = \get_post_field( 'post_excerpt', $id );
+			}
+
+			$gallery .= "\n" . '<!-- wp:image {"id":' . \esc_attr( $id ) . ',"sizeSlug":"large","linkDestination":"none"} -->' . "\n";
 			$gallery .= '<figure class="wp-block-image size-large">';
-			$gallery .= '<img src="' . \esc_url( $image_src[0] ) . '" alt="' . \esc_attr( $caption ) . '" class="' . \esc_attr( 'wp-image-' . $id ) . '"/>';
+			$gallery .= '<img src="' . \esc_url( $image_src[0] ) . '" alt="' . \esc_attr( $alt ) . '" class="' . \esc_attr( 'wp-image-' . $id ) . '"/>';
 			$gallery .= '</figure>';
 			$gallery .= "\n<!-- /wp:image -->\n";
 		}
@@ -733,8 +797,8 @@ private static function get_gallery_block( $attachment_ids ) {
 	 * @return string The gallery block markup.
 	 */
 	private static function get_files_gallery_block( $files ) {
-		$gallery  = '<!-- wp:gallery {"linkTo":"none"} -->' . "\n";
-		$gallery .= '<figure class="wp-block-gallery has-nested-images columns-default is-cropped">';
+		$gallery  = '<!-- wp:gallery {"columns":2,"linkTo":"none","imageCrop":true} -->' . "\n";
+		$gallery .= '<figure class="wp-block-gallery has-nested-images columns-2 is-cropped">';
 
 		foreach ( $files as $file ) {
 			$gallery .= "\n<!-- wp:image {\"sizeSlug\":\"large\",\"linkDestination\":\"none\"} -->\n";

tests/phpunit/tests/includes/class-test-attachments.php

@@ -300,7 +300,7 @@ public function test_process_multiple_attachments() {
 
 		// Verify content includes gallery block.
 		$post = get_post( self::$post_id );
-		$this->assertStringContainsString( 'wp:gallery', $post->post_content );
+		$this->assertStringContainsString( '<!-- wp:gallery', $post->post_content );
 	}
 
 	/**
@@ -486,8 +486,8 @@ public function test_inline_images_with_attachment_overlap() {
 		$attachments = \get_attached_media( '', $post_id );
 		$this->assertCount( 3, $attachments ); // shared.jpg, inline-only.jpg, attachment-only.jpg.
 
-		// Verify gallery was added for attachment-only.jpg.
-		$this->assertStringContainsString( '<!-- wp:gallery', $post->post_content );
+		// Verify image block was added for attachment-only.jpg (single images use standalone blocks).
+		$this->assertStringContainsString( '<!-- wp:image', $post->post_content );
 
 		// Clean up.
 		\wp_delete_post( $post_id, true );