WordPress.org

Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (15 months ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

    r47046 r47122  
    139139
    140140        if ( 'edit' === $request['context'] && ! current_user_can( $post_type->cap->edit_posts ) ) {
    141             return new WP_Error( 'rest_forbidden_context', __( 'Sorry, you are not allowed to edit posts in this post type.' ), array( 'status' => rest_authorization_required_code() ) );
     141            return new WP_Error(
     142                'rest_forbidden_context',
     143                __( 'Sorry, you are not allowed to edit posts in this post type.' ),
     144                array( 'status' => rest_authorization_required_code() )
     145            );
    142146        }
    143147
     
    157161        // Ensure a search string is set in case the orderby is set to 'relevance'.
    158162        if ( ! empty( $request['orderby'] ) && 'relevance' === $request['orderby'] && empty( $request['search'] ) ) {
    159             return new WP_Error( 'rest_no_search_term_defined', __( 'You need to define a search term to order by relevance.' ), array( 'status' => 400 ) );
     163            return new WP_Error(
     164                'rest_no_search_term_defined',
     165                __( 'You need to define a search term to order by relevance.' ),
     166                array( 'status' => 400 )
     167            );
    160168        }
    161169
    162170        // Ensure an include parameter is set in case the orderby is set to 'include'.
    163171        if ( ! empty( $request['orderby'] ) && 'include' === $request['orderby'] && empty( $request['include'] ) ) {
    164             return new WP_Error( 'rest_orderby_include_missing_include', __( 'You need to define an include parameter to order by include.' ), array( 'status' => 400 ) );
     172            return new WP_Error(
     173                'rest_orderby_include_missing_include',
     174                __( 'You need to define an include parameter to order by include.' ),
     175                array( 'status' => 400 )
     176            );
    165177        }
    166178
     
    338350
    339351        if ( $page > $max_pages && $total_posts > 0 ) {
    340             return new WP_Error( 'rest_post_invalid_page_number', __( 'The page number requested is larger than the number of pages available.' ), array( 'status' => 400 ) );
     352            return new WP_Error(
     353                'rest_post_invalid_page_number',
     354                __( 'The page number requested is larger than the number of pages available.' ),
     355                array( 'status' => 400 )
     356            );
    341357        }
    342358
     
    378394     */
    379395    protected function get_post( $id ) {
    380         $error = new WP_Error( 'rest_post_invalid_id', __( 'Invalid post ID.' ), array( 'status' => 404 ) );
     396        $error = new WP_Error(
     397            'rest_post_invalid_id',
     398            __( 'Invalid post ID.' ),
     399            array( 'status' => 404 )
     400        );
     401
    381402        if ( (int) $id <= 0 ) {
    382403            return $error;
     
    406427
    407428        if ( 'edit' === $request['context'] && $post && ! $this->check_update_permission( $post ) ) {
    408             return new WP_Error( 'rest_forbidden_context', __( 'Sorry, you are not allowed to edit this post.' ), array( 'status' => rest_authorization_required_code() ) );
     429            return new WP_Error(
     430                'rest_forbidden_context',
     431                __( 'Sorry, you are not allowed to edit this post.' ),
     432                array( 'status' => rest_authorization_required_code() )
     433            );
    409434        }
    410435
     
    412437            // Check post password, and return error if invalid.
    413438            if ( ! hash_equals( $post->post_password, $request['password'] ) ) {
    414                 return new WP_Error( 'rest_post_incorrect_password', __( 'Incorrect post password.' ), array( 'status' => 403 ) );
     439                return new WP_Error(
     440                    'rest_post_incorrect_password',
     441                    __( 'Incorrect post password.' ),
     442                    array( 'status' => 403 )
     443                );
    415444            }
    416445        }
     
    494523    public function create_item_permissions_check( $request ) {
    495524        if ( ! empty( $request['id'] ) ) {
    496             return new WP_Error( 'rest_post_exists', __( 'Cannot create existing post.' ), array( 'status' => 400 ) );
     525            return new WP_Error(
     526                'rest_post_exists',
     527                __( 'Cannot create existing post.' ),
     528                array( 'status' => 400 )
     529            );
    497530        }
    498531
     
    500533
    501534        if ( ! empty( $request['author'] ) && get_current_user_id() !== $request['author'] && ! current_user_can( $post_type->cap->edit_others_posts ) ) {
    502             return new WP_Error( 'rest_cannot_edit_others', __( 'Sorry, you are not allowed to create posts as this user.' ), array( 'status' => rest_authorization_required_code() ) );
     535            return new WP_Error(
     536                'rest_cannot_edit_others',
     537                __( 'Sorry, you are not allowed to create posts as this user.' ),
     538                array( 'status' => rest_authorization_required_code() )
     539            );
    503540        }
    504541
    505542        if ( ! empty( $request['sticky'] ) && ! current_user_can( $post_type->cap->edit_others_posts ) && ! current_user_can( $post_type->cap->publish_posts ) ) {
    506             return new WP_Error( 'rest_cannot_assign_sticky', __( 'Sorry, you are not allowed to make posts sticky.' ), array( 'status' => rest_authorization_required_code() ) );
     543            return new WP_Error(
     544                'rest_cannot_assign_sticky',
     545                __( 'Sorry, you are not allowed to make posts sticky.' ),
     546                array( 'status' => rest_authorization_required_code() )
     547            );
    507548        }
    508549
    509550        if ( ! current_user_can( $post_type->cap->create_posts ) ) {
    510             return new WP_Error( 'rest_cannot_create', __( 'Sorry, you are not allowed to create posts as this user.' ), array( 'status' => rest_authorization_required_code() ) );
     551            return new WP_Error(
     552                'rest_cannot_create',
     553                __( 'Sorry, you are not allowed to create posts as this user.' ),
     554                array( 'status' => rest_authorization_required_code() )
     555            );
    511556        }
    512557
    513558        if ( ! $this->check_assign_terms_permission( $request ) ) {
    514             return new WP_Error( 'rest_cannot_assign_term', __( 'Sorry, you are not allowed to assign the provided terms.' ), array( 'status' => rest_authorization_required_code() ) );
     559            return new WP_Error(
     560                'rest_cannot_assign_term',
     561                __( 'Sorry, you are not allowed to assign the provided terms.' ),
     562                array( 'status' => rest_authorization_required_code() )
     563            );
    515564        }
    516565
     
    528577    public function create_item( $request ) {
    529578        if ( ! empty( $request['id'] ) ) {
    530             return new WP_Error( 'rest_post_exists', __( 'Cannot create existing post.' ), array( 'status' => 400 ) );
     579            return new WP_Error(
     580                'rest_post_exists',
     581                __( 'Cannot create existing post.' ),
     582                array( 'status' => 400 )
     583            );
    531584        }
    532585
     
    651704
    652705        if ( $post && ! $this->check_update_permission( $post ) ) {
    653             return new WP_Error( 'rest_cannot_edit', __( 'Sorry, you are not allowed to edit this post.' ), array( 'status' => rest_authorization_required_code() ) );
     706            return new WP_Error(
     707                'rest_cannot_edit',
     708                __( 'Sorry, you are not allowed to edit this post.' ),
     709                array( 'status' => rest_authorization_required_code() )
     710            );
    654711        }
    655712
    656713        if ( ! empty( $request['author'] ) && get_current_user_id() !== $request['author'] && ! current_user_can( $post_type->cap->edit_others_posts ) ) {
    657             return new WP_Error( 'rest_cannot_edit_others', __( 'Sorry, you are not allowed to update posts as this user.' ), array( 'status' => rest_authorization_required_code() ) );
     714            return new WP_Error(
     715                'rest_cannot_edit_others',
     716                __( 'Sorry, you are not allowed to update posts as this user.' ),
     717                array( 'status' => rest_authorization_required_code() )
     718            );
    658719        }
    659720
    660721        if ( ! empty( $request['sticky'] ) && ! current_user_can( $post_type->cap->edit_others_posts ) && ! current_user_can( $post_type->cap->publish_posts ) ) {
    661             return new WP_Error( 'rest_cannot_assign_sticky', __( 'Sorry, you are not allowed to make posts sticky.' ), array( 'status' => rest_authorization_required_code() ) );
     722            return new WP_Error(
     723                'rest_cannot_assign_sticky',
     724                __( 'Sorry, you are not allowed to make posts sticky.' ),
     725                array( 'status' => rest_authorization_required_code() )
     726            );
    662727        }
    663728
    664729        if ( ! $this->check_assign_terms_permission( $request ) ) {
    665             return new WP_Error( 'rest_cannot_assign_term', __( 'Sorry, you are not allowed to assign the provided terms.' ), array( 'status' => rest_authorization_required_code() ) );
     730            return new WP_Error(
     731                'rest_cannot_assign_term',
     732                __( 'Sorry, you are not allowed to assign the provided terms.' ),
     733                array( 'status' => rest_authorization_required_code() )
     734            );
    666735        }
    667736
     
    689758        }
    690759
    691         // convert the post object to an array, otherwise wp_update_post will expect non-escaped input.
     760        // Convert the post object to an array, otherwise wp_update_post() will expect non-escaped input.
    692761        $post_id = wp_update_post( wp_slash( (array) $post ), true );
    693762
     
    780849
    781850        if ( $post && ! $this->check_delete_permission( $post ) ) {
    782             return new WP_Error( 'rest_cannot_delete', __( 'Sorry, you are not allowed to delete this post.' ), array( 'status' => rest_authorization_required_code() ) );
     851            return new WP_Error(
     852                'rest_cannot_delete',
     853                __( 'Sorry, you are not allowed to delete this post.' ),
     854                array( 'status' => rest_authorization_required_code() )
     855            );
    783856        }
    784857
     
    824897
    825898        if ( ! $this->check_delete_permission( $post ) ) {
    826             return new WP_Error( 'rest_user_cannot_delete_post', __( 'Sorry, you are not allowed to delete this post.' ), array( 'status' => rest_authorization_required_code() ) );
     899            return new WP_Error(
     900                'rest_user_cannot_delete_post',
     901                __( 'Sorry, you are not allowed to delete this post.' ),
     902                array( 'status' => rest_authorization_required_code() )
     903            );
    827904        }
    828905
     
    843920            // If we don't support trashing for this type, error out.
    844921            if ( ! $supports_trash ) {
    845                 /* translators: %s: force=true */
    846                 return new WP_Error( 'rest_trash_not_supported', sprintf( __( "The post does not support trashing. Set '%s' to delete." ), 'force=true' ), array( 'status' => 501 ) );
     922                return new WP_Error(
     923                    'rest_trash_not_supported',
     924                    /* translators: %s: force=true */
     925                    sprintf( __( "The post does not support trashing. Set '%s' to delete." ), 'force=true' ),
     926                    array( 'status' => 501 )
     927                );
    847928            }
    848929
    849930            // Otherwise, only trash if we haven't already.
    850931            if ( 'trash' === $post->post_status ) {
    851                 return new WP_Error( 'rest_already_trashed', __( 'The post has already been deleted.' ), array( 'status' => 410 ) );
    852             }
    853 
    854             // (Note that internally this falls through to `wp_delete_post` if
    855             // the trash is disabled.)
     932                return new WP_Error(
     933                    'rest_already_trashed',
     934                    __( 'The post has already been deleted.' ),
     935                    array( 'status' => 410 )
     936                );
     937            }
     938
     939            // (Note that internally this falls through to `wp_delete_post()`
     940            // if the trash is disabled.)
    856941            $result   = wp_trash_post( $id );
    857942            $post     = get_post( $id );
     
    860945
    861946        if ( ! $result ) {
    862             return new WP_Error( 'rest_cannot_delete', __( 'The post cannot be deleted.' ), array( 'status' => 500 ) );
     947            return new WP_Error(
     948                'rest_cannot_delete',
     949                __( 'The post cannot be deleted.' ),
     950                array( 'status' => 500 )
     951            );
    863952        }
    864953
     
    10651154
    10661155                if ( ! $user_obj ) {
    1067                     return new WP_Error( 'rest_invalid_author', __( 'Invalid author ID.' ), array( 'status' => 400 ) );
     1156                    return new WP_Error(
     1157                        'rest_invalid_author',
     1158                        __( 'Invalid author ID.' ),
     1159                        array( 'status' => 400 )
     1160                    );
    10681161                }
    10691162            }
     
    10781171            if ( '' !== $request['password'] ) {
    10791172                if ( ! empty( $schema['properties']['sticky'] ) && ! empty( $request['sticky'] ) ) {
    1080                     return new WP_Error( 'rest_invalid_field', __( 'A post can not be sticky and have a password.' ), array( 'status' => 400 ) );
     1173                    return new WP_Error(
     1174                        'rest_invalid_field',
     1175                        __( 'A post can not be sticky and have a password.' ),
     1176                        array( 'status' => 400 )
     1177                    );
    10811178                }
    10821179
    10831180                if ( ! empty( $prepared_post->ID ) && is_sticky( $prepared_post->ID ) ) {
    1084                     return new WP_Error( 'rest_invalid_field', __( 'A sticky post can not be password protected.' ), array( 'status' => 400 ) );
     1181                    return new WP_Error(
     1182                        'rest_invalid_field',
     1183                        __( 'A sticky post can not be password protected.' ),
     1184                        array( 'status' => 400 )
     1185                    );
    10851186                }
    10861187            }
     
    10891190        if ( ! empty( $schema['properties']['sticky'] ) && ! empty( $request['sticky'] ) ) {
    10901191            if ( ! empty( $prepared_post->ID ) && post_password_required( $prepared_post->ID ) ) {
    1091                 return new WP_Error( 'rest_invalid_field', __( 'A password protected post can not be set to sticky.' ), array( 'status' => 400 ) );
     1192                return new WP_Error(
     1193                    'rest_invalid_field',
     1194                    __( 'A password protected post can not be set to sticky.' ),
     1195                    array( 'status' => 400 )
     1196                );
    10921197            }
    10931198        }
     
    10991204            } else {
    11001205                $parent = get_post( (int) $request['parent'] );
     1206
    11011207                if ( empty( $parent ) ) {
    1102                     return new WP_Error( 'rest_post_invalid_id', __( 'Invalid post parent ID.' ), array( 'status' => 400 ) );
     1208                    return new WP_Error(
     1209                        'rest_post_invalid_id',
     1210                        __( 'Invalid post parent ID.' ),
     1211                        array( 'status' => 400 )
     1212                    );
    11031213                }
     1214
    11041215                $prepared_post->post_parent = (int) $parent->ID;
    11051216            }
     
    11581269            case 'private':
    11591270                if ( ! current_user_can( $post_type->cap->publish_posts ) ) {
    1160                     return new WP_Error( 'rest_cannot_publish', __( 'Sorry, you are not allowed to create private posts in this post type.' ), array( 'status' => rest_authorization_required_code() ) );
     1271                    return new WP_Error(
     1272                        'rest_cannot_publish',
     1273                        __( 'Sorry, you are not allowed to create private posts in this post type.' ),
     1274                        array( 'status' => rest_authorization_required_code() )
     1275                    );
    11611276                }
    11621277                break;
     
    11641279            case 'future':
    11651280                if ( ! current_user_can( $post_type->cap->publish_posts ) ) {
    1166                     return new WP_Error( 'rest_cannot_publish', __( 'Sorry, you are not allowed to publish posts in this post type.' ), array( 'status' => rest_authorization_required_code() ) );
     1281                    return new WP_Error(
     1282                        'rest_cannot_publish',
     1283                        __( 'Sorry, you are not allowed to publish posts in this post type.' ),
     1284                        array( 'status' => rest_authorization_required_code() )
     1285                    );
    11671286                }
    11681287                break;
     
    11941313                return true;
    11951314            } else {
    1196                 return new WP_Error( 'rest_invalid_featured_media', __( 'Invalid featured media ID.' ), array( 'status' => 400 ) );
     1315                return new WP_Error(
     1316                    'rest_invalid_featured_media',
     1317                    __( 'Invalid featured media ID.' ),
     1318                    array( 'status' => 400 )
     1319                );
    11971320            }
    11981321        } else {
     
    12351358        }
    12361359
    1237         /* translators: 1: Parameter, 2: List of valid values. */
    1238         return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not one of %2$s.' ), 'template', implode( ', ', array_keys( $allowed_templates ) ) ) );
     1360        return new WP_Error(
     1361            'rest_invalid_param',
     1362            /* translators: 1: Parameter, 2: List of valid values. */
     1363            sprintf( __( '%1$s is not one of %2$s.' ), 'template', implode( ', ', array_keys( $allowed_templates ) ) )
     1364        );
    12391365    }
    12401366
     
    14641590
    14651591        if ( rest_is_field_included( 'date_gmt', $fields ) ) {
    1466             // For drafts, `post_date_gmt` may not be set, indicating that the
    1467             // date of the draft should be updated each time it is saved (see
    1468             // #38883).  In this case, shim the value based on the `post_date`
    1469             // field with the site's timezone offset applied.
     1592            /*
     1593             * For drafts, `post_date_gmt` may not be set, indicating that the date
     1594             * of the draft should be updated each time it is saved (see #38883).
     1595             * In this case, shim the value based on the `post_date` field
     1596             * with the site's timezone offset applied.
     1597             */
    14701598            if ( '0000-00-00 00:00:00' === $post->post_date_gmt ) {
    14711599                $post_date_gmt = get_gmt_from_date( $post->post_date );
     
    14891617
    14901618        if ( rest_is_field_included( 'modified_gmt', $fields ) ) {
    1491             // For drafts, `post_modified_gmt` may not be set (see
    1492             // `post_date_gmt` comments above).  In this case, shim the value
    1493             // based on the `post_modified` field with the site's timezone
    1494             // offset applied.
     1619            /*
     1620             * For drafts, `post_modified_gmt` may not be set (see `post_date_gmt` comments
     1621             * above). In this case, shim the value based on the `post_modified` field
     1622             * with the site's timezone offset applied.
     1623             */
    14951624            if ( '0000-00-00 00:00:00' === $post->post_modified_gmt ) {
    14961625                $post_modified_gmt = gmdate( 'Y-m-d H:i:s', strtotime( $post->post_modified ) - ( get_option( 'gmt_offset' ) * 3600 ) );
     
    20792208                        'context'     => array( 'view', 'edit', 'embed' ),
    20802209                        'arg_options' => array(
    2081                             'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database()
    2082                             'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database()
     2210                            'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database().
     2211                            'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database().
    20832212                        ),
    20842213                        'properties'  => array(
     
    21042233                        'context'     => array( 'view', 'edit' ),
    21052234                        'arg_options' => array(
    2106                             'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database()
    2107                             'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database()
     2235                            'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database().
     2236                            'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database().
    21082237                        ),
    21092238                        'properties'  => array(
     
    21492278                        'context'     => array( 'view', 'edit', 'embed' ),
    21502279                        'arg_options' => array(
    2151                             'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database()
    2152                             'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database()
     2280                            'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database().
     2281                            'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database().
    21532282                        ),
    21542283                        'properties'  => array(
     
    22422371
    22432372        $taxonomies = wp_list_filter( get_object_taxonomies( $this->post_type, 'objects' ), array( 'show_in_rest' => true ) );
     2373
    22442374        foreach ( $taxonomies as $taxonomy ) {
    22452375            $base = ! empty( $taxonomy->rest_base ) ? $taxonomy->rest_base : $taxonomy->name;
     
    22782408
    22792409        $this->schema = $schema;
     2410
    22802411        return $this->add_additional_fields_schema( $this->schema );
    22812412    }
     
    26232754        $statuses = wp_parse_slug_list( $statuses );
    26242755
    2625         // The default status is different in WP_REST_Attachments_Controller
     2756        // The default status is different in WP_REST_Attachments_Controller.
    26262757        $attributes     = $request->get_attributes();
    26272758        $default_status = $attributes['args']['status']['default'];
     
    26402771                }
    26412772            } else {
    2642                 return new WP_Error( 'rest_forbidden_status', __( 'Status is forbidden.' ), array( 'status' => rest_authorization_required_code() ) );
     2773                return new WP_Error(
     2774                    'rest_forbidden_status',
     2775                    __( 'Status is forbidden.' ),
     2776                    array( 'status' => rest_authorization_required_code() )
     2777                );
    26432778            }
    26442779        }
Note: See TracChangeset for help on using the changeset viewer.