8000 Merge pull request #2882 from schlessera/attachments-controller-comments · WP-API/WP-API@c88e2fe · GitHub
[go: up one dir, main page]
Skip to content
This repository was archived by the owner on Sep 24, 2018. It is now read-only.

Commit c88e2fe

Browse files
kadamwhitekadamwhite
authored
Merge pull request #2882 from schlessera/attachments-controller-comments
Tweak Attachments Controller comments.
2 parents 3ba64b7 + 325407c commit c88e2fe

File tree

1 file changed

+47
-46
lines changed

1 file changed

+47
-46
lines changed

‎lib/endpoints/class-wp-rest-attachments-controller.php

Lines changed: 47 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
66
* Determine the allowed query_vars for a get_items() response and
77
* prepare for WP_Query.
88
*
9-
* @param array $prepared_args
10-
* @param WP_REST_Request $request
11-
* @return array $query_args
9+
* @param array $prepared_args Optional. Array of prepared arguments.
10+
* @param WP_REST_Request $request Optional. Request to prepare items for.
11+
* @return array Array of query arguments.
1212
*/
1313
protected function prepare_items_query( $prepared_args = array(), $request = null ) {
1414
$query_args = parent::prepare_items_query( $prepared_args, $request );
@@ -32,7 +32,7 @@ protected function prepare_items_query( $prepared_args = array(), $request = nul
3232
* Check if a given request has access to create an attachment.
3333
*
3434
* @param WP_REST_Request $request Full details about the request.
35-
* @return WP_Error|boolean
35+
* @return WP_Error|true Boolean true if the attachment may be created, or a WP_Error if not.
3636
*/
3737
public function create_item_permissions_check( $request ) {
3838
$ret = parent::create_item_permissions_check( $request );
@@ -44,7 +44,7 @@ public function create_item_permissions_check( $request ) {
4444
return new WP_Error( 'rest_cannot_create', __( 'Sorry, you are not allowed to upload media on this site.' ), array( 'status' => 400 ) );
4545
}
4646

47-
// Attaching media to a post requires ability to edit said post
47+
// Attaching media to a post requires ability to edit said post.
4848
if ( ! empty( $request['post'] ) ) {
4949
$parent = $this->get_post( (int) $request['post'] );
5050
$post_parent_type = get_post_type_object( $parent->post_type );
@@ -57,10 +57,10 @@ public function create_item_permissions_check( $request ) {
5757
}
5858

5959
/**
60-
* Create a single attachment
60+
* Create a single attachment.
6161
*
62-
* @param WP_REST_Request $request Full details about the request
63-
* @return WP_Error|WP_REST_Response
62+
* @param WP_REST_Request $request Full details about the request.
63+
* @return WP_Error|WP_REST_Response Response object on success, WP_Error object on failure.
6464
*/
6565
public function create_item( $request ) {
6666

@@ -123,7 +123,7 @@ public function create_item( $request ) {
123123
}
124124
$attachment = $this->get_post( $id );
125125

126-
/** Include admin functions to get access to wp_generate_attachment_metadata() */
126+
// Include admin functions to get access to wp_generate_attachment_metadata().
127127
require_once ABSPATH . 'wp-admin/includes/admin.php';
128128

129129
wp_update_attachment_metadata( $id, wp_generate_attachment_metadata( $id, $file ) );
@@ -157,10 +157,10 @@ public function create_item( $request ) {
157157
}
158158

159159
/**
160-
* Update a single post
160+
* Update a single post.
161161
*
162-
* @param WP_REST_Request $request Full details about the request
163-
* @return WP_Error|WP_REST_Response
162+
* @param WP_REST_Request $request Full details about the request.
163+
* @return WP_Error|WP_REST_Response Response object on success, WP_Error object on failure.
164164
*/
165165
public function update_item( $request ) {
166166
if ( ! empty( $request['post'] ) && in_array( get_post_type( $request['post'] ), array( 'revision', 'attachment' ), true ) ) {
@@ -196,10 +196,10 @@ public function update_item( $request ) {
196196
}
197197

198198
/**
199-
* Prepare a single attachment for create or update
199+
* Prepare a single attachment for create or update.
200200
*
201-
* @param WP_REST_Request $request Request object
202-
* @return WP_Error|stdClass $prepared_attachment Post object
201+
* @param WP_REST_Request $request Request object.
202+
* @return WP_Error|stdClass $prepared_attachment Post object.
203203
*/
204204
protected function prepare_item_for_database( $request ) {
205205
$prepared_attachment = parent::prepare_item_for_database( $request );
@@ -220,11 +220,11 @@ protected function prepare_item_for_database( $request ) {
220220
}
221221

222222
/**
223-
* Prepare a single attachment output for response
223+
* Prepare a single attachment output for response.
224224
*
225-
* @param WP_Post $post Post object
226-
* @param WP_REST_Request $request Request object
227-
* @return WP_REST_Response $response
225+
* @param WP_Post $post Post object.
226+
* @param WP_REST_Request $request Request object.
227+
* @return WP_REST_Response Response object.
228228
*/
229229
public function prepare_item_for_response( $post, $request ) {
230230
$response = parent::prepare_item_for_response( $post, $request );
@@ -239,7 +239,7 @@ public function prepare_item_for_response( $post, $request ) {
239239
$data['post'] = ! empty( $post->post_parent ) ? (int) $post->post_parent : null;
240240
$data['source_url'] = wp_get_attachment_url( $post->ID );
241241

242-
// Ensure empty details is an empty object
242+
// Ensure empty details is an empty object.
243243
if ( empty( $data['media_details'] ) ) {
244244
$data['media_details'] = new stdClass;
245245
} elseif ( ! empty( $data['media_details']['sizes'] ) ) {
@@ -251,7 +251,7 @@ public function prepare_item_for_response( $post, $request ) {
251251
unset( $size_data['mime-type'] );
252252
}
253253

254-
// Use the same method image_downsize() does
254+
// Use the same method image_downsize() does.
255255
$image_src = wp_get_attachment_image_src( $post->ID, $size );
256256
if ( ! $image_src ) {
257257
continue;
@@ -278,7 +278,7 @@ public function prepare_item_for_response( $post, $request ) {
278278

279279
$data = $this->filter_response_by_context( $data, $context );
280280

281-
// Wrap the data in a response object
281+
// Wrap the data in a response object.
282282
$response = rest_ensure_response( $data );
283283

284284
$response->add_links( $this->prepare_links( $post ) );
@@ -296,9 +296,9 @@ public function prepare_item_for_response( $post, $request ) {
296296
}
297297

298298
/**
299-
* Get the Attachment's schema, conforming to JSON Schema
299+
* Get the Attachment's schema, conforming to JSON Schema.
300300
*
301-
* @return array
301+
* @return array Item schema as an array.
302302
*/
303303
public function get_item_schema() {
304304

@@ -363,11 +363,11 @@ public function get_item_schema() {
363363
}
364364

365365
/**
366-
* Handle an upload via raw POST data
366+
* Handle an upload via raw POST data.
367367
*
368-
* @param array $data Supplied file data
369-
* @param array $headers HTTP headers from the request
370-
* @return array|WP_Error Data from {@see wp_handle_sideload()}
368+
* @param array $data Supplied file data.
369+
* @param array $headers HTTP headers from the request.
370+
* @return array|WP_Error Data from {@see wp_handle_sideload()}.
371371
*/
372372
protected function upload_from_data( $data, $headers ) {
373373
if ( empty( $data ) ) {
@@ -398,13 +398,13 @@ protected function upload_from_data( $data, $headers ) {
398398
}
399399
}
400400

401-
// Get the content-type
401+
// Get the content-type.
402402
$type = array_shift( $headers['content_type'] );
403403

404404
/** Include admin functions to get access to wp_tempnam() and wp_handle_sideload() */
405405
require_once ABSPATH . 'wp-admin/includes/admin.php';
406406

407-
// Save the file
407+
// Save the file.
408408
$tmpfname = wp_tempnam( $filename );
409409

410410
$fp = fopen( $tmpfname, 'w+' );
@@ -416,7 +416,7 @@ protected function upload_from_data( $data, $headers ) {
416416
fwrite( $fp, $data );
417417
fclose( $fp );
418418

419-
// Now, sideload it in
419+
// Now, sideload it in.
420420
$file_data = array(
421421
'error' => null,
422422
'tmp_name' => $tmpfname,
@@ -466,7 +466,7 @@ protected function upload_from_data( $data, $headers ) {
466466
* @return string|null Filename if available, or null if not found.
467467
*/
468468
public static function get_filename_from_disposition( $disposition_header ) {
469-
// Get the filename
469+
// Get the filename.
470470
$filename = null;
471471

472472
foreach ( $disposition_header as $value ) {
@@ -506,7 +506,7 @@ public static function get_filename_from_disposition( $disposition_header ) {
506506
/**
507507
* Get the query params for collections of attachments.
508508
*
509-
* @return array
509+
* @return array Query parameters for the attachment collection as an array.
510510
*/
511511
public function get_collection_params() {
512512
$params = parent::get_collection_params();
@@ -531,10 +531,10 @@ public function get_collection_params() {
531531
/**
532532
* Validate whether the user can query private statuses
533533
*
534-
* @param mixed $value
535-
* @param WP_REST_Request $request
536-
* @param string $parameter
537-
* @return WP_Error|boolean
534+
* @param mixed $value Status value.
535+
* @param WP_REST_Request $request Request object.
536+
* @param string $parameter Additional parameter to pass to validation.
537+
* @return WP_Error|boolean Boolean true if the user may query, WP_Error if not.
538538
*/
539539
public function validate_user_can_query_private_statuses( $value, $request, $parameter ) {
540540
if ( 'inherit' === $value ) {
@@ -544,18 +544,18 @@ public function validate_user_can_query_private_statuses( $value, $request, $par
544544
}
545545

546546
/**
547-
* Handle an upload via multipart/form-data ($_FILES)
547+
* Handle an upload via multipart/form-data ($_FILES).
548548
*
549-
* @param array $files Data from $_FILES
550-
* @param array $headers HTTP headers from the request
551-
* @return array|WP_Error Data from {@see wp_handle_upload()}
549+
* @param array $files Data from $_FILES.
550+
* @param array $headers HTTP headers from the request.
551+
* @return array|WP_Error Data from {@see wp_handle_upload()}.
552552
*/
553553
protected function upload_from_file( $files, $headers ) {
554554
if ( empty( $files ) ) {
555555
return new WP_Error( 'rest_upload_no_data', __( 'No data supplied.' ), array( 'status' => 400 ) );
556556
}
557557

558-
// Verify hash, if given
558+
// Verify hash, if given.
559559
if ( ! empty( $headers['content_md5'] ) ) {
560560
$content_md5 = array_shift( $headers['content_md5'] );
561561
$expected = trim( $content_md5 );
@@ -565,16 +565,16 @@ protected function upload_from_file( $files, $headers ) {
565565
}
566566
}
567567

568-
// Pass off to WP to handle the actual upload
568+
// Pass off to WP to handle the actual upload.
569569
$overrides = array(
570570
'test_form' => false,
571571
);
572-
// Bypasses is_uploaded_file() when running unit tests
572+
// Bypasses is_uploaded_file() when running unit tests.
573573
if ( defined( 'DIR_TESTDATA' ) && DIR_TESTDATA ) {
574574
$overrides['action'] = 'wp_handle_mock_upload';
575575
}
576576

577-
/** Include admin functions to get access to wp_handle_upload() */
577+
// Include admin functions to get access to wp_handle_upload().
578578
require_once ABSPATH . 'wp-admin/includes/admin.php';
579579
$file = wp_handle_upload( $files['file'], $overrides );
580580

@@ -587,7 +587,8 @@ protected function upload_from_file( $files, $headers ) {
587587

588588
/**
589589
* Get the supported media types.
590-
* Media types are considered the MIME type category
590+
*
591+
* Media types are considered the MIME type category.
591592
*
592593
* @return array
593594
*/

0 commit comments

Comments
 (0)
0