From 8760c9a91d017e318cf3d2ea52b87789fd3e3628 Mon Sep 17 00:00:00 2001
From: Ryan McCue <me@ryanmccue.info>
Date: Tue, 8 Nov 2016 04:29:32 +0000
Subject: [PATCH] REST API: Change attachment caption & description to objects.

Just like excerpt and content for regular posts, these have transformations applied that can make the content significantly different from the raw value.

Props jnylen0.
Fixes #38679.

Built from https://develop.svn.wordpress.org/trunk@39154


git-svn-id: http://core.svn.wordpress.org/trunk@39094 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 .../class-wp-rest-attachments-controller.php  | 75 +++++++++++++++----
 wp-includes/version.php                       |  2 +-
 2 files changed, 62 insertions(+), 15 deletions(-)

diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php
index 9d8e7d438f..bcbd524560 100644
--- a/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php
+++ b/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php
@@ -247,12 +247,22 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 	protected function prepare_item_for_database( $request ) {
 		$prepared_attachment = parent::prepare_item_for_database( $request );
 
+		// Attachment caption (post_excerpt internally)
 		if ( isset( $request['caption'] ) ) {
-			$prepared_attachment->post_excerpt = $request['caption'];
+			if ( is_string( $request['caption'] ) ) {
+				$prepared_attachment->post_excerpt = wp_filter_post_kses( $request['caption'] );
+			} elseif ( isset( $request['caption']['raw'] ) ) {
+				$prepared_attachment->post_excerpt = wp_filter_post_kses( $request['caption']['raw'] );
+			}
 		}
 
+		// Attachment description (post_content internally)
 		if ( isset( $request['description'] ) ) {
-			$prepared_attachment->post_content = $request['description'];
+			if ( is_string( $request['description'] ) ) {
+				$prepared_attachment->post_content = wp_filter_post_kses( $request['description'] );
+			} elseif ( isset( $request['description']['raw'] ) ) {
+				$prepared_attachment->post_content = wp_filter_post_kses( $request['description']['raw'] );
+			}
 		}
 
 		if ( isset( $request['post'] ) ) {
@@ -276,9 +286,20 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 		$response = parent::prepare_item_for_response( $post, $request );
 		$data = $response->get_data();
 
+		$data['description'] = array(
+			'raw'       => $post->post_content,
+			/** This filter is documented in wp-includes/post-template.php */
+			'rendered'  => apply_filters( 'the_content', $post->post_content ),
+		);
+
+		/** This filter is documented in wp-includes/post-template.php */
+		$caption = apply_filters( 'the_excerpt', apply_filters( 'get_the_excerpt', $post->post_excerpt, $post ) );
+		$data['caption'] = array(
+			'raw'       => $post->post_excerpt,
+			'rendered'  => $caption,
+		);
+
 		$data['alt_text']      = get_post_meta( $post->ID, '_wp_attachment_image_alt', true );
-		$data['caption']       = $post->post_excerpt;
-		$data['description']   = $post->post_content;
 		$data['media_type']    = wp_attachment_is_image( $post->ID ) ? 'image' : 'file';
 		$data['mime_type']     = $post->post_mime_type;
 		$data['media_details'] = wp_get_attachment_metadata( $post->ID );
@@ -366,20 +387,46 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 		);
 
 		$schema['properties']['caption'] = array(
-			'description'     => __( 'The caption for the resource.' ),
-			'type'            => 'string',
-			'context'         => array( 'view', 'edit' ),
-			'arg_options'     => array(
-				'sanitize_callback' => 'wp_filter_post_kses',
+			'description' => __( 'The caption for the resource.' ),
+			'type'        => 'object',
+			'context'     => array( 'view', 'edit', 'embed' ),
+			'arg_options' => array(
+				'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database()
+			),
+			'properties'  => array(
+				'raw' => array(
+					'description' => __( 'Caption for the resource, as it exists in the database.' ),
+					'type'        => 'string',
+					'context'     => array( 'edit' ),
+				),
+				'rendered' => array(
+					'description' => __( 'HTML caption for the resource, transformed for display.' ),
+					'type'        => 'string',
+					'context'     => array( 'view', 'edit', 'embed' ),
+					'readonly'    => true,
+				),
 			),
 		);
 
 		$schema['properties']['description'] = array(
-			'description'     => __( 'The description for the resource.' ),
-			'type'            => 'string',
-			'context'         => array( 'view', 'edit' ),
-			'arg_options'     => array(
-				'sanitize_callback' => 'wp_filter_post_kses',
+			'description' => __( 'The description for the resource.' ),
+			'type'        => 'object',
+			'context'     => array( 'view', 'edit' ),
+			'arg_options' => array(
+				'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database()
+			),
+			'properties'  => array(
+				'raw' => array(
+					'description' => __( 'Description for the object, as it exists in the database.' ),
+					'type'        => 'string',
+					'context'     => array( 'edit' ),
+				),
+				'rendered' => array(
+					'description' => __( 'HTML description for the object, transformed for display.' ),
+					'type'        => 'string',
+					'context'     => array( 'view', 'edit' ),
+					'readonly'    => true,
+				),
 			),
 		);
 
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d8a4bef637..c4575683ed 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.7-beta2-39153';
+$wp_version = '4.7-beta2-39154';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.