Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
26.67%
36 / 135
33.33%
1 / 3
 CRAP
0.00%
0 / 1
WPCOM_JSON_API_Update_Media_v1_1_Endpoint
51.43%
36 / 70
33.33%
1 / 3
 90.00
0.00%
0 / 1
 current_user_can_edit_media_item
100.00%
8 / 8
100.00%
1 / 1
 4
 callback
55.32%
26 / 47
0.00%
0 / 1
 42.78
 handle_video_meta
13.33%
2 / 15
0.00%
0 / 1
 8.86
1<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
2/**
3 * Update media item info v1.1 endpoint.
4 *
5 * Endpoint: v1.1/sites/%s/media/%d
6 */
7
8if ( ! defined( 'ABSPATH' ) ) {
9    exit( 0 );
10}
11
12new WPCOM_JSON_API_Update_Media_v1_1_Endpoint(
13    array(
14        'description'          => 'Edit basic information about a media item.',
15        'group'                => 'media',
16        'stat'                 => 'media:1:POST',
17        'min_version'          => '1.1',
18        'max_version'          => '1.1',
19        'method'               => 'POST',
20        'path'                 => '/sites/%s/media/%d',
21        'path_labels'          => array(
22            '$site'     => '(int|string) Site ID or domain',
23            '$media_ID' => '(int) The ID of the media item',
24        ),
25
26        'request_format'       => array(
27            'parent_id'       => '(int) ID of the post this media is attached to',
28            'title'           => '(string) The file name.',
29            'caption'         => '(string) File caption.',
30            'description'     => '(HTML) Description of the file.',
31            'alt'             => '(string) Alternative text for image files.',
32            'rating'          => '(string) Video only. Video rating.',
33            'display_embed'   => '(string) Video only. Whether to share or not the video.',
34            'allow_download'  => '(string) Video only. Whether the video can be downloaded or not.',
35            'privacy_setting' => '(int) Video only. The privacy level for the video.',
36            'artist'          => '(string) Audio Only. Artist metadata for the audio track.',
37            'album'           => '(string) Audio Only. Album metadata for the audio track.',
38        ),
39
40        'response_format'      => array(
41            'ID'                         => '(int) The ID of the media item',
42            'date'                       => '(ISO 8601 datetime) The date the media was uploaded',
43            'post_ID'                    => '(int) ID of the post this media is attached to',
44            'author_ID'                  => '(int) ID of the user who uploaded the media',
45            'URL'                        => '(string) URL to the file',
46            'guid'                       => '(string) Unique identifier',
47            'file'                       => '(string) File name',
48            'extension'                  => '(string) File extension',
49            'mime_type'                  => '(string) File mime type',
50            'title'                      => '(string) File name',
51            'caption'                    => '(string) User provided caption of the file',
52            'description'                => '(string) Description of the file',
53            'alt'                        => '(string)  Alternative text for image files.',
54            'thumbnails'                 => '(object) Media item thumbnail URL options',
55            'height'                     => '(int) (Image & video only) Height of the media item',
56            'width'                      => '(int) (Image & video only) Width of the media item',
57            'length'                     => '(int) (Video & audio only) Duration of the media item, in seconds',
58            'exif'                       => '(array) (Image & audio only) Exif (meta) information about the media item',
59            'rating'                     => '(string) (Video only) VideoPress rating of the video',
60            'display_embed'              => '(string) Video only. Whether to share or not the video.',
61            'allow_download'             => '(string) Video only. Whether the video can be downloaded or not.',
62            'privacy_setting'            => '(int) Video only. The privacy level for the video.',
63            'videopress_guid'            => '(string) (Video only) VideoPress GUID of the video when uploaded on a blog with VideoPress',
64            'videopress_processing_done' => '(bool) (Video only) If the video is uploaded on a blog with VideoPress, this will return the status of processing on the video.',
65        ),
66
67        'example_request'      => 'https://public-api.wordpress.com/rest/v1.1/sites/82974409/media/446',
68        'example_request_data' => array(
69            'headers' => array(
70                'authorization' => 'Bearer YOUR_API_TOKEN',
71            ),
72            'body'    => array(
73                'title' => 'Updated Title',
74            ),
75        ),
76    )
77);
78
79// phpcs:disable PEAR.NamingConventions.ValidClassName.Invalid
80/**
81 * Update media item info v1.1 class.
82 *
83 * @phan-constructor-used-for-side-effects
84 */
85class WPCOM_JSON_API_Update_Media_v1_1_Endpoint extends WPCOM_JSON_API_Endpoint {
86    /**
87     * Whether the current user may edit the given media item.
88     *
89     * `upload_files` is a primitive capability and ignores any object passed to it,
90     * so it only tells us the caller may upload something, never that they may edit
91     * this particular item. A missing item is passed through so the caller receives
92     * the endpoint's own 404 rather than a 403. A userless request gets no exemption:
93     * `edit_post` fails closed for user 0 like any other caller.
94     *
95     * Non-attachments are refused outright. `get_post()` resolves any post type, so
96     * without this test a media endpoint edits ordinary posts, pages and revisions.
97     * The post-type test must stay below the missing-post passthrough: that branch
98     * returns true, so testing there would skip `edit_post` for ordinary posts.
99     *
100     * A non-attachment yields 403, not the 404 a missing item gets. This is a boolean
101     * gate, and `get_media_item*()` resolves any post type, so a passthrough would
102     * return 200 rather than 404. Revisit if clients conflate it with an auth failure.
103     *
104     * Do not move this into a trait: this file instantiates the endpoint above the
105     * class declaration, and `use Trait;` disables PHP early binding, which makes the
106     * file fatal with "Class not found".
107     *
108     * @param int $media_id Media post ID.
109     * @return bool
110     */
111    protected function current_user_can_edit_media_item( $media_id ) {
112        if ( ! current_user_can( 'upload_files' ) ) {
113            return false;
114        }
115
116        $post = get_post( $media_id );
117
118        if ( ! $post ) {
119            return true;
120        }
121
122        if ( 'attachment' !== $post->post_type ) {
123            return false;
124        }
125
126        return current_user_can( 'edit_post', $media_id );
127    }
128
129    /**
130     * Update media item info API v1.1 callback.
131     *
132     * @param string $path API path.
133     * @param int    $blog_id Blog ID.
134     * @param int    $media_id Media ID.
135     *
136     * @return object|WP_Error
137     */
138    public function callback( $path = '', $blog_id = 0, $media_id = 0 ) {
139        $blog_id = $this->api->switch_to_blog_and_validate_user( $this->api->get_blog_id( $blog_id ) );
140        if ( is_wp_error( $blog_id ) ) {
141            return $blog_id;
142        }
143
144        if ( ! $this->current_user_can_edit_media_item( $media_id ) ) {
145            return new WP_Error( 'unauthorized', 'User cannot edit media', 403 );
146        }
147
148        $item = $this->get_media_item_v1_1( $media_id );
149
150        if ( is_wp_error( $item ) ) {
151            return new WP_Error( 'unknown_media', 'Unknown Media', 404 );
152        }
153
154        $input  = $this->input( true );
155        $insert = array();
156
157        if ( isset( $input['title'] ) ) {
158            $insert['post_title'] = $input['title'];
159        }
160
161        if ( isset( $input['caption'] ) ) {
162            $insert['post_excerpt'] = $input['caption'];
163        }
164
165        if ( isset( $input['description'] ) ) {
166            $insert['post_content'] = $input['description'];
167        }
168
169        if ( isset( $input['parent_id'] ) ) {
170            $parent_id = (int) $input['parent_id'];
171
172            /*
173             * Attaching media to a post is an edit of that post, so it takes `edit_post` on
174             * the target, as core's WP_REST_Attachments_Controller does for the same field.
175             * Without this a caller attaches their own media to any post on the site.
176             *
177             * Zero is exempt: it detaches the item rather than naming a target, and
178             * `edit_post` fails closed on 0, which would make detaching impossible.
179             */
180            if ( $parent_id && ! current_user_can( 'edit_post', $parent_id ) ) {
181                return new WP_Error( 'unauthorized', 'User cannot edit the parent post', 403 );
182            }
183
184            $insert['post_parent'] = $parent_id;
185        }
186
187        if ( isset( $input['alt'] ) ) {
188            $alt = wp_strip_all_tags( $input['alt'], true );
189            update_post_meta( $media_id, '_wp_attachment_image_alt', $alt );
190        }
191
192        // audio only artist/album info.
193        if ( str_starts_with( $item->mime_type, 'audio/' ) ) {
194            $changed = false;
195            $id3data = wp_get_attachment_metadata( $media_id );
196
197            if ( ! is_array( $id3data ) ) {
198                $changed = true;
199                $id3data = array();
200            }
201
202            $id3_keys = array(
203                'artist' => __( 'Artist', 'jetpack' ),
204                'album'  => __( 'Album', 'jetpack' ),
205            );
206
207            foreach ( $id3_keys as $key => $label ) {
208                if ( isset( $input[ $key ] ) ) {
209                    $changed         = true;
210                    $id3data[ $key ] = wp_strip_all_tags( $input[ $key ], true );
211                }
212            }
213
214            if ( $changed ) {
215                wp_update_attachment_metadata( $media_id, $id3data );
216            }
217        }
218
219        // Pass the item to the handle_video_meta() that checks if it's a VideoPress item and saves it.
220        $result = $this->handle_video_meta( $media_id, $input, $item );
221
222        if ( is_wp_error( $result ) ) {
223            return $result;
224        }
225
226        $insert['ID'] = $media_id;
227        wp_update_post( (object) $insert );
228
229        $item = $this->get_media_item_v1_1( $media_id );
230        return $item;
231    }
232
233    /**
234     * Persist the VideoPress metadata if the given item argument is a VideoPress item.
235     *
236     * @param string   $media_id The ID of the video.
237     * @param array    $input    The request input.
238     * @param stdClass $item     The response item.
239     *
240     * @return bool|WP_Error
241     */
242    public function handle_video_meta( $media_id, $input, $item ) {
243        if ( ! class_exists( \Videopress_Attachment_Metadata::class ) ) {
244            return false;
245        }
246
247        if ( ! \Videopress_Attachment_Metadata::is_videopress_media( $item ) ) {
248            return false;
249        }
250
251        return \Videopress_Attachment_Metadata::persist_metadata(
252            $media_id,
253            $item->videopress_guid,
254            $input['title'] ?? null,
255            $input['caption'] ?? null,
256            $input['description'] ?? null,
257            $input['rating'] ?? null,
258            $input['display_embed'] ?? null,
259            $input['allow_download'] ?? null,
260            $input['privacy_setting'] ?? null
261        );
262    }
263}