Media: Rename the original attachment to the edit root.

`wp_get_original_attachment_id()` sat next to `wp_get_original_image_path()`
and `wp_get_original_image_url()`, which describe the unscaled upload of
the same attachment rather than the attachment a chain of edits started
from. The names now say which one they mean:

- `wp_get_original_attachment_id()` -> `wp_get_edit_root_attachment_id()`
- `_wp_delete_original_attachment_id()` -> `_wp_delete_edit_root_attachment_id()`
- `_wp_attachment_original_id` postmeta -> `_wp_attachment_edit_root_id`
- `original_attachment` REST field -> `edit_root`
- `wp:original-attachment` link relation -> `wp:edit-root`

No change in behaviour.

See #65987.

Author: ramonjd

src/wp-includes/default-filters.php

@@ -696,7 +696,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' );
+add_action( 'delete_attachment', '_wp_delete_edit_root_attachment_id' );
 
 // Client-side media processing.
 add_action( 'admin_init', 'wp_set_client_side_media_processing_flag' );

src/wp-includes/post.php

@@ -8827,14 +8827,14 @@ function wp_get_original_image_url( $attachment_id ) {
 }
 
 /**
- * Retrieves the ID of the attachment an edited image originally came from.
+ * Retrieves the edit root of an attachment: the attachment its chain of edits started 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.
+ * so this function can find the edit root 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
@@ -8846,41 +8846,41 @@ function wp_get_original_image_url( $attachment_id ) {
  * @return int ID of the attachment the chain of edits started from, or `$attachment_id`
  *             if none is recorded.
  */
-function wp_get_original_attachment_id( $attachment_id ) {
-	$original_id = (int) get_post_meta( $attachment_id, '_wp_attachment_original_id', true );
+function wp_get_edit_root_attachment_id( $attachment_id ) {
+	$edit_root_id = (int) get_post_meta( $attachment_id, '_wp_attachment_edit_root_id', true );
 
-	return $original_id > 0 ? $original_id : (int) $attachment_id;
+	return $edit_root_id > 0 ? $edit_root_id : (int) $attachment_id;
 }
 
 /**
- * Clears the recorded original attachment ID from any attachment pointing at a deleted one.
+ * Clears the recorded edit root 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.
+ * trash first, attachments keep pointing at the trashed edit root 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 ) {
+function _wp_delete_edit_root_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
+	 * Deletes the meta from every attachment recording this ID as its edit root. 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 );
+	delete_metadata( 'post', 0, '_wp_attachment_edit_root_id', $post_id, true );
 }
 
 /**

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

@@ -1357,15 +1357,15 @@ public function edit_media_item( $request ) {
 		);
 
 		/*
-		 * Record the attachment this chain of edits started from, so the original can be
+		 * Record the attachment this chain of edits started from, so the edit root 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
+		 * the edit root 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 )
+			'_wp_attachment_edit_root_id',
+			wp_get_edit_root_attachment_id( $attachment_id )
 		);
 
 		/**
@@ -1526,10 +1526,10 @@ public function prepare_item_for_response( $item, $request ) {
 		 * Edit context only, since only editors need it.
 		 * Not validated: deleting an attachment clears it from images edited from it.
 		 */
-		if ( in_array( 'original_attachment', $fields, true ) && 'edit' === $request['context'] ) {
-			$original_id = wp_get_original_attachment_id( $post->ID );
+		if ( in_array( 'edit_root', $fields, true ) && 'edit' === $request['context'] ) {
+			$edit_root_id = wp_get_edit_root_attachment_id( $post->ID );
 
-			$data['original_attachment'] = $original_id !== (int) $post->ID ? $original_id : 0;
+			$data['edit_root'] = $edit_root_id !== (int) $post->ID ? $edit_root_id : 0;
 		}
 
 		if ( in_array( 'source_url', $fields, true ) ) {
@@ -1691,15 +1691,15 @@ public function prepare_item_for_response( $item, $request ) {
 		}
 
 		/*
-		 * Let clients fetch the original attachment in the same request with `_embed`,
+		 * Let clients fetch the edit root in the same request with `_embed`,
 		 * the way `featured_media` is paired with its own link. Added here rather than in
 		 * `prepare_links()` because that method cannot see the request, and this belongs
 		 * in the `edit` context only, alongside the field itself.
 		 */
-		if ( ! empty( $data['original_attachment'] ) ) {
+		if ( ! empty( $data['edit_root'] ) ) {
 			$response->add_link(
-				'https://api.w.org/original-attachment',
-				rest_url( rest_get_route_for_post( $data['original_attachment'] ) ),
+				'https://api.w.org/edit-root',
+				rest_url( rest_get_route_for_post( $data['edit_root'] ) ),
 				array( 'embeddable' => true )
 			);
 		}
@@ -1842,7 +1842,7 @@ public function get_item_schema() {
 			'context'     => array( 'view', 'edit' ),
 		);
 
-		$schema['properties']['original_attachment'] = array(
+		$schema['properties']['edit_root'] = array(
 			'description' => __( 'The ID of the attachment this attachment\'s chain of edits started from, or 0 if none is recorded.' ),
 			'type'        => 'integer',
 			'context'     => array( 'edit' ),