Media: Track the original attachment for edited images.

Editing an image via the `wp/v2/media/<id>/edit` REST endpoint saves the
result as a new attachment and leaves the edited image untouched, so a
site can build up a chain: an upload, a crop of it, a crop of that crop.
`parent_image` records only the immediately preceding image, so finding
the image a chain started from meant walking it one attachment at a time.

Each attachment created by an edit now records the ID at the top of its
chain in `_wp_attachment_original_id` postmeta, inheriting it from the
image being edited. `wp_get_original_attachment_id()` reads it back in a
single lookup, and returns the ID it was given for attachments that were
uploaded rather than edited.

The attachments REST controller exposes the result as
`media_details.original_attachment` in the `edit` context only, giving
editors what they need to offer a way back to the original without
telling visitors which images were made from which.

Deleting an attachment clears the record from any image edited from it,
so nothing is left pointing at an ID that could later be reused.

Records are written going forward only; images edited before this lands
are not backfilled.

Props ramonjd.
Fixes #65987.

Author: ramonjd

src/wp-includes/default-filters.php

@@ -692,6 +692,7 @@
 add_action( 'customize_controls_enqueue_scripts', 'wp_plupload_default_settings' );
 add_action( 'plugins_loaded', '_wp_add_additional_image_sizes', 0 );
 add_filter( 'plupload_default_settings', 'wp_show_heic_upload_error' );
+add_action( 'delete_attachment', '_wp_delete_original_attachment_id' );
 
 // Client-side media processing.
 add_action( 'admin_init', 'wp_set_client_side_media_processing_flag' );

src/wp-includes/post.php

@@ -8751,6 +8751,63 @@ function wp_get_original_image_url( $attachment_id ) {
 	return apply_filters( 'wp_get_original_image_url', $original_image_url, $attachment_id );
 }
 
+/**
+ * Retrieves the ID of the attachment an edited image originally came from.
+ *
+ * Editing an image through the `wp/v2/media/<id>/edit` REST endpoint does not change the
+ * image that was edited. It saves the result as a brand new attachment, so a site can end
+ * up with a chain of attachments: an upload, a crop of it, a crop of that crop, and so on.
+ *
+ * Every attachment created that way stores the ID of the attachment at the top of its chain,
+ * so this function can find the original in one lookup no matter how long the chain is.
+ *
+ * Attachments that were uploaded rather than created by editing have no chain of their own,
+ * and this returns the ID that was passed in. To tell the two cases apart, compare the
+ * result against that ID.
+ *
+ * @since 7.2.0
+ *
+ * @param int $attachment_id Attachment ID.
+ * @return int ID of the attachment the chain started from, or `$attachment_id` when the
+ *             attachment was not created by editing another one.
+ */
+function wp_get_original_attachment_id( $attachment_id ) {
+	$original_id = (int) get_post_meta( $attachment_id, '_wp_attachment_original_id', true );
+
+	return $original_id > 0 ? $original_id : (int) $attachment_id;
+}
+
+/**
+ * Clears the recorded original attachment ID from any attachment pointing at a deleted one.
+ *
+ * Without this, attachments created by editing the deleted image would keep pointing at an
+ * ID that no longer exists, and could later point at an unrelated attachment if WordPress
+ * reuses that ID.
+ *
+ * This only runs when an attachment is deleted for good. On sites where media goes to the
+ * trash first, attachments keep pointing at the trashed original until the trash is emptied.
+ *
+ * @since 7.2.0
+ *
+ * @access private
+ *
+ * @param int $post_id Attachment ID being deleted.
+ */
+function _wp_delete_original_attachment_id( $post_id ) {
+	$post_id = (int) $post_id;
+
+	if ( $post_id <= 0 ) {
+		return;
+	}
+
+	/*
+	 * Deletes the meta from every attachment recording this ID as its original. The meta key
+	 * is indexed, so this only scans the rows for attachments created by editing an image,
+	 * and it avoids searching the serialized attachment metadata for the ID.
+	 */
+	delete_metadata( 'post', 0, '_wp_attachment_original_id', $post_id, true );
+}
+
 /**
  * Filters callback which sets the status of an untrashed post to its previous status.
  *

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

@@ -1356,6 +1356,18 @@ public function edit_media_item( $request ) {
 			'file'          => _wp_relative_upload_path( $image_file ),
 		);
 
+		/*
+		 * Record the attachment this chain of edits started from, so the original can be
+		 * found in one lookup from any image later in the chain. The new attachment inherits
+		 * the original recorded on the image being edited, or that image itself when it was
+		 * uploaded rather than edited.
+		 */
+		update_post_meta(
+			$new_attachment_id,
+			'_wp_attachment_original_id',
+			wp_get_original_attachment_id( $attachment_id )
+		);
+
 		/**
 		 * Filters the meta data for the new image created by editing an existing image.
 		 *
@@ -1503,6 +1515,31 @@ public function prepare_item_for_response( $item, $request ) {
 			} else {
 				$data['media_details']['sizes'] = new stdClass();
 			}
+
+			/*
+			 * Point an image created by editing another one back at the attachment its chain
+			 * of edits started from, so editors can offer a way to get back to the original.
+			 *
+			 * Only sent in the `edit` context: this is for people editing the image, and it
+			 * would otherwise tell visitors which images were made from which.
+			 *
+			 * Left out when the attachment was not created by editing another one, and when
+			 * the original no longer has a URL, which happens if its file is missing.
+			 */
+			if ( 'edit' === $request['context'] && is_array( $data['media_details'] ) ) {
+				$original_id = wp_get_original_attachment_id( $post->ID );
+
+				if ( $original_id !== (int) $post->ID ) {
+					$original_url = wp_get_attachment_url( $original_id );
+
+					if ( is_string( $original_url ) && '' !== $original_url ) {
+						$data['media_details']['original_attachment'] = array(
+							'attachment_id' => $original_id,
+							'source_url'    => $original_url,
+						);
+					}
+				}
+			}
 		}
 
 		if ( in_array( 'post', $fields, true ) ) {
@@ -1797,6 +1834,29 @@ public function get_item_schema() {
 			'type'        => 'object',
 			'context'     => array( 'view', 'edit', 'embed' ),
 			'readonly'    => true,
+			'properties'  => array(
+				'original_attachment' => array(
+					'description' => __( 'The attachment this image was originally created from by editing. Only present for images created by editing another image.' ),
+					'type'        => 'object',
+					'context'     => array( 'edit' ),
+					'readonly'    => true,
+					'properties'  => array(
+						'attachment_id' => array(
+							'description' => __( 'The ID of the original attachment.' ),
+							'type'        => 'integer',
+							'context'     => array( 'edit' ),
+							'readonly'    => true,
+						),
+						'source_url'    => array(
+							'description' => __( 'URL to the original attachment file.' ),
+							'type'        => 'string',
+							'format'      => 'uri',
+							'context'     => array( 'edit' ),
+							'readonly'    => true,
+						),
+					),
+				),
+			),
 		);
 
 		$schema['properties']['post'] = array(

tests/phpunit/tests/rest-api/rest-attachments-controller.php

@@ -6063,4 +6063,169 @@ public function test_url_arg_rejects_unsafe_urls() {
 			$this->assertSame( 400, $result->get_error_data()['status'] );
 		}
 	}
+
+	/**
+	 * Edits an image and returns the ID of the attachment the edit created.
+	 *
+	 * @param int $attachment_id Attachment to edit.
+	 * @return int New attachment ID.
+	 */
+	private function edit_image_and_get_new_id( $attachment_id ) {
+		$request = new WP_REST_Request( 'POST', "/wp/v2/media/{$attachment_id}/edit" );
+		$request->set_body_params(
+			array(
+				'rotation' => 60,
+				'src'      => wp_get_attachment_image_url( $attachment_id, 'full' ),
+			)
+		);
+
+		$response = rest_do_request( $request );
+		$this->assertSame( 201, $response->get_status(), 'The image edit should have succeeded.' );
+
+		$data = $response->get_data();
+
+		return $data['id'];
+	}
+
+	/**
+	 * @ticket 65987
+	 */
+	public function test_get_original_attachment_id_returns_same_id_for_an_upload() {
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$this->assertSame( $attachment, wp_get_original_attachment_id( $attachment ) );
+	}
+
+	/**
+	 * @ticket 65987
+	 * @requires function imagejpeg
+	 */
+	public function test_edit_records_the_edited_image_as_the_original() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$edited = $this->edit_image_and_get_new_id( $attachment );
+
+		$this->assertSame( $attachment, wp_get_original_attachment_id( $edited ) );
+	}
+
+	/**
+	 * @ticket 65987
+	 * @requires function imagejpeg
+	 */
+	public function test_editing_an_edited_image_keeps_the_first_original() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$edited       = $this->edit_image_and_get_new_id( $attachment );
+		$edited_again = $this->edit_image_and_get_new_id( $edited );
+
+		$this->assertSame(
+			$attachment,
+			wp_get_original_attachment_id( $edited_again ),
+			'An edit of an edit should still point at the image the chain started from.'
+		);
+	}
+
+	/**
+	 * @ticket 65987
+	 * @requires function imagejpeg
+	 */
+	public function test_edited_image_response_includes_the_original_attachment() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$edited = $this->edit_image_and_get_new_id( $attachment );
+
+		$request = new WP_REST_Request( 'GET', "/wp/v2/media/{$edited}" );
+		$request->set_param( 'context', 'edit' );
+		$data = rest_do_request( $request )->get_data();
+
+		$this->assertArrayHasKey( 'original_attachment', $data['media_details'] );
+		$this->assertSame(
+			$attachment,
+			$data['media_details']['original_attachment']['attachment_id']
+		);
+		$this->assertSame(
+			wp_get_attachment_url( $attachment ),
+			$data['media_details']['original_attachment']['source_url']
+		);
+	}
+
+	/**
+	 * @ticket 65987
+	 */
+	public function test_uploaded_image_response_omits_the_original_attachment() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$request = new WP_REST_Request( 'GET', "/wp/v2/media/{$attachment}" );
+		$request->set_param( 'context', 'edit' );
+		$data = rest_do_request( $request )->get_data();
+
+		$this->assertArrayNotHasKey( 'original_attachment', $data['media_details'] );
+	}
+
+	/**
+	 * @ticket 65987
+	 * @requires function imagejpeg
+	 */
+	public function test_view_context_omits_the_original_attachment() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		$edited = $this->edit_image_and_get_new_id( $attachment );
+
+		$request = new WP_REST_Request( 'GET', "/wp/v2/media/{$edited}" );
+		$request->set_param( 'context', 'view' );
+		$data = rest_do_request( $request )->get_data();
+
+		$this->assertArrayNotHasKey( 'original_attachment', $data['media_details'] );
+	}
+
+	/**
+	 * An attachment recorded as its own original is a broken record, not a chain,
+	 * so nothing should be reported for it.
+	 *
+	 * @ticket 65987
+	 */
+	public function test_attachment_recorded_as_its_own_original_omits_the_field() {
+		wp_set_current_user( self::$superadmin_id );
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+
+		update_post_meta( $attachment, '_wp_attachment_original_id', $attachment );
+
+		$request = new WP_REST_Request( 'GET', "/wp/v2/media/{$attachment}" );
+		$request->set_param( 'context', 'edit' );
+		$data = rest_do_request( $request )->get_data();
+
+		$this->assertArrayNotHasKey( 'original_attachment', $data['media_details'] );
+	}
+
+	/**
+	 * @ticket 65987
+	 * @requires function imagejpeg
+	 */
+	public function test_deleting_an_original_clears_it_from_the_images_edited_from_it() {
+		wp_set_current_user( self::$superadmin_id );
+
+		$attachment = self::factory()->attachment->create_upload_object( self::$test_file );
+		$edited     = $this->edit_image_and_get_new_id( $attachment );
+
+		$unrelated        = self::factory()->attachment->create_upload_object( self::$test_file );
+		$unrelated_edited = $this->edit_image_and_get_new_id( $unrelated );
+
+		wp_delete_attachment( $attachment, true );
+
+		$this->assertSame(
+			'',
+			get_post_meta( $edited, '_wp_attachment_original_id', true ),
+			'The record pointing at the deleted attachment should have been cleared.'
+		);
+		$this->assertSame(
+			$unrelated,
+			wp_get_original_attachment_id( $unrelated_edited ),
+			'An unrelated image should have kept its record.'
+		);
+	}
 }