Changeset 60908 for trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

Timestamp:

10/06/2025 11:50:00 PM (11 months ago)

Author:

ramonopoly

Message:

Attachments REST API endpoint: update attachments controller to support flip and to customize attachment fields

This commit enhances media editor capabilities pursuant to the Phase 3: Collaboration > Media Library. See ​https://make.wordpress.org/core/2023/07/07/media-library/

It adds the following functionality:

• the ability to flip an image horizontally and vertically
• the ability to send arguments to update the new image's caption, description, and title, post and alt_text fields.

Props ramonopoly, mukesh27, isabel_brison, andrewserong.
Fixes #64035.

File:

• trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php (modified) (9 diffs)

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

@@ -544 +544 @@
          *
          * @since 5.5.0
+         * @since 6.9.0 Adds flips capability and editable fields for the newly-created attachment post.
          *
          * @param WP_REST_Request $request Full details about the request.
@@ -584 +585 @@
                 } else {
                         $modifiers = array();
+
+                        if ( isset( $request['flip']['horizontal'] ) || isset( $request['flip']['vertical'] ) ) {
+                                $flip_args = array(
+                                        'vertical'   => isset( $request['flip']['vertical'] ) ? (bool) $request['flip']['vertical'] : false,
+                                        'horizontal' => isset( $request['flip']['horizontal'] ) ? (bool) $request['flip']['horizontal'] : false,
+                                );
+
+                                $modifiers[] = array(
+                                        'type' => 'flip',
+                                        'args' => array(
+                                                'flip' => $flip_args,
+                                        ),
+                                );
+                        }
 
                         if ( ! empty( $request['rotation'] ) ) {
@@ -638 +653 @@
                         $args = $modifier['args'];
                         switch ( $modifier['type'] ) {
+                                case 'flip':
+                                        /*
+                                         * Flips the current image.
+                                         * The vertical flip is the first argument (flip along horizontal axis), the horizontal flip is the second argument (flip along vertical axis).
+                                         * See: WP_Image_Editor::flip()
+                                         */
+                                        $result = $image_editor->flip( $args['flip']['vertical'], $args['flip']['horizontal'] );
+                                        if ( is_wp_error( $result ) ) {
+                                                return new WP_Error(
+                                                        'rest_image_flip_failed',
+                                                        __( 'Unable to flip this image.' ),
+                                                        array( 'status' => 500 )
+                                                );
+                                        }
+                                        break;
                                 case 'rotate':
                                         // Rotation direction: clockwise vs. counterclockwise.
@@ -712 +742 @@
                 }
 
-                // Create new attachment post.
-                $new_attachment_post = array(
-                        'post_mime_type' => $saved['mime-type'],
-                        'guid'           => $uploads['url'] . "/$filename",
-                        'post_title'     => $image_name,
-                        'post_content'   => '',
-                );
-
-                // Copy post_content, post_excerpt, and post_title from the edited image's attachment post.
-                $attachment_post = get_post( $attachment_id );
-
-                if ( $attachment_post ) {
-                        $new_attachment_post['post_content'] = $attachment_post->post_content;
-                        $new_attachment_post['post_excerpt'] = $attachment_post->post_excerpt;
-                        $new_attachment_post['post_title']   = $attachment_post->post_title;
-                }
-
+                // Grab original attachment post so we can use it to set defaults.
+                $original_attachment_post = get_post( $attachment_id );
+
+                // Check request fields and assign default values.
+                $new_attachment_post                 = $this->prepare_item_for_database( $request );
+                $new_attachment_post->post_mime_type = $saved['mime-type'];
+                $new_attachment_post->guid           = $uploads['url'] . "/$filename";
+
+                // Unset ID so wp_insert_attachment generates a new ID.
+                unset( $new_attachment_post->ID );
+
+                // Set new attachment post title with fallbacks.
+                $new_attachment_post->post_title = $new_attachment_post->post_title ?? $original_attachment_post->post_title ?? $image_name;
+
+                // Set new attachment post caption (post_excerpt).
+                $new_attachment_post->post_excerpt = $new_attachment_post->post_excerpt ?? $original_attachment_post->post_excerpt ?? '';
+
+                // Set new attachment post description (post_content) with fallbacks.
+                $new_attachment_post->post_content = $new_attachment_post->post_content ?? $original_attachment_post->post_content ?? '';
+
+                // Set post parent if set in request, else the default of `0` (no parent).
+                $new_attachment_post->post_parent = $new_attachment_post->post_parent ?? 0;
+
+                // Insert the new attachment post.
                 $new_attachment_id = wp_insert_attachment( wp_slash( $new_attachment_post ), $saved['path'], 0, true );
 
@@ -741 +778 @@
                 }
 
-                // Copy the image alt text from the edited image.
-                $image_alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
+                // First, try to use the alt text from the request. If not set, copy the image alt text from the original attachment.
+                $image_alt = isset( $request['alt_text'] ) ? sanitize_text_field( $request['alt_text'] ) : get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
 
                 if ( ! empty( $image_alt ) ) {
@@ -1481 +1518 @@
          *
          * @since 5.5.0
+         * @since 6.9.0 Adds flips capability and editable fields for the newly-created attachment post.
          *
          * @return array
          */
         protected function get_edit_media_item_args() {
-                return array(
+                $args = array(
                         'src'       => array(
                                 'description' => __( 'URL to the edited image file.' ),
@@ -1492 +1530 @@
                                 'required'    => true,
                         ),
+                        // The `modifiers` param takes precedence over the older format.
                         'modifiers' => array(
                                 'description' => __( 'Array of image edits.' ),
@@ -1504 +1543 @@
                                         ),
                                         'oneOf'       => array(
+                                                array(
+                                                        'title'      => __( 'Flip' ),
+                                                        'properties' => array(
+                                                                'type' => array(
+                                                                        'description' => __( 'Flip type.' ),
+                                                                        'type'        => 'string',
+                                                                        'enum'        => array( 'flip' ),
+                                                                ),
+                                                                'args' => array(
+                                                                        'description' => __( 'Flip arguments.' ),
+                                                                        'type'        => 'object',
+                                                                        'required'    => array(
+                                                                                'flip',
+                                                                        ),
+                                                                        'properties'  => array(
+                                                                                'flip' => array(
+                                                                                        'description' => __( 'Flip direction.' ),
+                                                                                        'type'        => 'object',
+                                                                                        'required'    => array(
+                                                                                                'horizontal',
+                                                                                                'vertical',
+                                                                                        ),
+                                                                                        'properties'  => array(
+                                                                                                'horizontal' => array(
+                                                                                                        'description' => __( 'Whether to flip in the horizontal direction.' ),
+                                                                                                        'type' => 'boolean',
+                                                                                                ),
+                                                                                                'vertical' => array(
+                                                                                                        'description' => __( 'Whether to flip in the vertical direction.' ),
+                                                                                                        'type' => 'boolean',
+                                                                                                ),
+                                                                                        ),
+                                                                                ),
+                                                                        ),
+                                                                ),
+                                                        ),
+                                                ),
                                                 array(
                                                         'title'      => __( 'Rotation' ),
@@ -1601 +1677 @@
                         ),
                 );
+
+                /*
+                 * Get the args based on the post schema. This calls `rest_get_endpoint_args_for_schema()`,
+                 * which also takes care of sanitization and validation.
+                 */
+                $update_item_args = $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE );
+
+                if ( isset( $update_item_args['caption'] ) ) {
+                        $args['caption'] = $update_item_args['caption'];
+                }
+
+                if ( isset( $update_item_args['description'] ) ) {
+                        $args['description'] = $update_item_args['description'];
+                }
+
+                if ( isset( $update_item_args['title'] ) ) {
+                        $args['title'] = $update_item_args['title'];
+                }
+
+                if ( isset( $update_item_args['post'] ) ) {
+                        $args['post'] = $update_item_args['post'];
+                }
+
+                if ( isset( $update_item_args['alt_text'] ) ) {
+                        $args['alt_text'] = $update_item_args['alt_text'];
+                }
+
+                return $args;
         }
 }