WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
10/30/2016 06:54:49 AM (8 years ago)
Author:
DrewAPicture
Message:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Comments_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r38864 r39015  
    11<?php
    2 
    32/**
    4  * Access comments
     3 * REST API: WP_REST_Comments_Controller class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core controller used to access comments via the REST API.
     12 *
     13 * @since 4.7.0
     14 *
     15 * @see WP_REST_Controller
    516 */
    617class WP_REST_Comments_Controller extends WP_REST_Controller {
    … …  
    920     * Instance of a comment meta fields object.
    1021     *
     22     * @since 4.7.0
    1123     * @access protected
    1224     * @var WP_REST_Comment_Meta_Fields
    … …  
    1426    protected $meta;
    1527
     28    /**
     29     * Constructor.
     30     *
     31     * @since 4.7.0
     32     * @access public
     33     */
    1634    public function __construct() {
    1735        $this->namespace = 'wp/v2';
    … …  
    2240
    2341    /**
    24      * Register the routes for the objects of the controller.
     42     * Registers the routes for the objects of the controller.
     43     *
     44     * @since 4.7.0
     45     * @access public
    2546     */
    2647    public function register_routes() {
    … …  
    7394
    7495    /**
    75      * Check if a given request has access to read comments
    76      *
    77      * @param  WP_REST_Request $request Full details about the request.
    78      * @return WP_Error|boolean
     96     * Checks if a given request has access to read comments.
     97     *
     98     * @since 4.7.0
     99     * @access public
     100     *
     101     * @param WP_REST_Request $request Full details about the request.
     102     * @return WP_Error|bool True if the request has read access, error object otherwise.
    79103     */
    80104    public function get_items_permissions_check( $request ) {
    … …  
    83107            foreach ( (array) $request['post'] as $post_id ) {
    84108                $post = $this->get_post( $post_id );
     109
    85110                if ( ! empty( $post_id ) && $post && ! $this->check_read_post_permission( $post ) ) {
    86111                    return new WP_Error( 'rest_cannot_read_post', __( 'Sorry, you cannot read the post for this comment.' ), array( 'status' => rest_authorization_required_code() ) );
    … …  
    98123            $protected_params = array( 'author', 'author_exclude', 'karma', 'author_email', 'type', 'status' );
    99124            $forbidden_params = array();
     125
    100126            foreach ( $protected_params as $param ) {
    101127                if ( 'status' === $param ) {
    … …  
    111137                }
    112138            }
     139
    113140            if ( ! empty( $forbidden_params ) ) {
    114141                return new WP_Error( 'rest_forbidden_param', sprintf( __( 'Query parameter not permitted: %s' ), implode( ', ', $forbidden_params ) ), array( 'status' => rest_authorization_required_code() ) );
    … …  
    120147
    121148    /**
    122      * Get a list of comments.
    123      *
    124      * @param  WP_REST_Request $request Full details about the request.
    125      * @return WP_Error|WP_REST_Response
     149     * Retrieves a list of comment items.
     150     *
     151     * @since 4.7.0
     152     * @access public
     153     *
     154     * @param WP_REST_Request $request Full details about the request.
     155     * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
    126156     */
    127157    public function get_items( $request ) {
    … …  
    130160        $registered = $this->get_collection_params();
    131161
    132         // This array defines mappings between public API query parameters whose
    133         // values are accepted as-passed, and their internal WP_Query parameter
    134         // name equivalents (some are the same). Only values which are also
    135         // present in $registered will be set.
     162        /*
     163         * This array defines mappings between public API query parameters whose
     164         * values are accepted as-passed, and their internal WP_Query parameter
     165         * name equivalents (some are the same). Only values which are also
     166         * present in $registered will be set.
     167         */
    136168        $parameter_mappings = array(
    137169            'author'         => 'author__in',
    … …  
    154186        $prepared_args = array();
    155187
    156         // For each known parameter which is both registered and present in the request,
    157         // set the parameter's value on the query $prepared_args.
     188        /*
     189         * For each known parameter which is both registered and present in the request,
     190         * set the parameter's value on the query $prepared_args.
     191         */
    158192        foreach ( $parameter_mappings as $api_param => $wp_param ) {
    159193            if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
    … …  
    176210
    177211        $prepared_args['date_query'] = array();
     212
    178213        // Set before into date query. Date query must be specified as an array of an array.
    179214        if ( isset( $registered['before'], $request['before'] ) ) {
    … …  
    191226
    192227        /**
    193          * Filter arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
    194          *
    195          * @see https://developer.wordpress.org/reference/classes/wp_comment_query/
     228         * Filters arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
     229         *
     230         * @since 4.7.0
     231         *
     232         * @link https://developer.wordpress.org/reference/classes/wp_comment_query/
    196233         *
    197234         * @param array           $prepared_args Array of arguments for WP_Comment_Query.
    … …  
    204241
    205242        $comments = array();
     243
    206244        foreach ( $query_result as $comment ) {
    207245            if ( ! $this->check_read_permission( $comment ) ) {
    … …  
    214252
    215253        $total_comments = (int) $query->found_comments;
    216         $max_pages = (int) $query->max_num_pages;
     254        $max_pages      = (int) $query->max_num_pages;
     255
    217256        if ( $total_comments < 1 ) {
    218             // Out-of-bounds, run the query again without LIMIT for total count
     257            // Out-of-bounds, run the query again without LIMIT for total count.
    219258            unset( $prepared_args['number'], $prepared_args['offset'] );
     259
    220260            $query = new WP_Comment_Query;
    221261            $prepared_args['count'] = true;
    … …  
    230270
    231271        $base = add_query_arg( $request->get_query_params(), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) );
     272
    232273        if ( $request['page'] > 1 ) {
    233274            $prev_page = $request['page'] - 1;
     275
    234276            if ( $prev_page > $max_pages ) {
    235277                $prev_page = $max_pages;
    236278            }
     279
    237280            $prev_link = add_query_arg( 'page', $prev_page, $base );
    238281            $response->link_header( 'prev', $prev_link );
    239282        }
     283
    240284        if ( $max_pages > $request['page'] ) {
    241285            $next_page = $request['page'] + 1;
    242286            $next_link = add_query_arg( 'page', $next_page, $base );
     287
    243288            $response->link_header( 'next', $next_link );
    244289        }
    … …  
    248293
    249294    /**
    250      * Check if a given request has access to read the comment
    251      *
    252      * @param  WP_REST_Request $request Full details about the request.
    253      * @return WP_Error|boolean
     295     * Checks if a given request has access to read the comment.
     296     *
     297     * @since 4.7.0
     298     * @access public
     299     *
     300     * @param WP_REST_Request $request Full details about the request.
     301     * @return WP_Error|bool True if the request has read access for the item, error object otherwise.
    254302     */
    255303    public function get_item_permissions_check( $request ) {
    … …  
    280328
    281329    /**
    282      * Get a comment.
    283      *
    284      * @param  WP_REST_Request $request Full details about the request.
    285      * @return WP_Error|WP_REST_Response
     330     * Retrieves a comment.
     331     *
     332     * @since 4.7.0
     333     * @access public
     334     *
     335     * @param WP_REST_Request $request Full details about the request.
     336     * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
    286337     */
    287338    public function get_item( $request ) {
    … …  
    307358
    308359    /**
    309      * Check if a given request has access to create a comment
    310      *
    311      * @param  WP_REST_Request $request Full details about the request.
    312      * @return WP_Error|boolean
     360     * Checks if a given request has access to create a comment.
     361     *
     362     * @since 4.7.0
     363     * @access public
     364     *
     365     * @param WP_REST_Request $request Full details about the request.
     366     * @return WP_Error|bool True if the request has access to create items, error object otherwise.
    313367     */
    314368    public function create_item_permissions_check( $request ) {
    … …  
    322376            return new WP_Error( 'rest_comment_invalid_author', __( 'Comment author invalid.' ), array( 'status' => rest_authorization_required_code() ) );
    323377        }
     378
    324379        if ( isset( $request['karma'] ) && $request['karma'] > 0 && ! current_user_can( 'moderate_comments' ) ) {
    325380            return new WP_Error( 'rest_comment_invalid_karma', __( 'Sorry, you cannot set karma for comments.' ), array( 'status' => rest_authorization_required_code() ) );
    326381        }
     382
    327383        if ( isset( $request['status'] ) && ! current_user_can( 'moderate_comments' ) ) {
    328384            return new WP_Error( 'rest_comment_invalid_status', __( 'Sorry, you cannot set status for comments.' ), array( 'status' => rest_authorization_required_code() ) );
    … …  
    355411
    356412    /**
    357      * Create a comment.
    358      *
    359      * @param  WP_REST_Request $request Full details about the request.
    360      * @return WP_Error|WP_REST_Response
     413     * Creates a comment.
     414     *
     415     * @since 4.7.0
     416     * @access public
     417     *
     418     * @param WP_REST_Request $request Full details about the request.
     419     * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
    361420     */
    362421    public function create_item( $request ) {
    … …  
    366425
    367426        $prepared_comment = $this->prepare_item_for_database( $request );
     427
    368428        if ( is_wp_error( $prepared_comment ) ) {
    369429            return $prepared_comment;
    370430        }
    371431
    372         /**
     432        /*
    373433         * Do not allow a comment to be created with an empty string for
    374          * comment_content.
    375          * See `wp_handle_comment_submission()`.
     434         * comment_content. See wp_handle_comment_submission().
    376435         */
    377436        if ( '' === $prepared_comment['comment_content'] ) {
    … …  
    379438        }
    380439
    381         // Setting remaining values before wp_insert_comment so we can
    382         // use wp_allow_comment().
     440        // Setting remaining values before wp_insert_comment so we can use wp_allow_comment().
    383441        if ( ! isset( $prepared_comment['comment_date_gmt'] ) ) {
    384442            $prepared_comment['comment_date_gmt'] = current_time( 'mysql', true );
    385443        }
    386444
    387         // Set author data if the user's logged in
     445        // Set author data if the user's logged in.
    388446        $missing_author = empty( $prepared_comment['user_id'] )
    389447            && empty( $prepared_comment['comment_author'] )
    … …  
    393451        if ( is_user_logged_in() && $missing_author ) {
    394452            $user = wp_get_current_user();
     453
    395454            $prepared_comment['user_id'] = $user->ID;
    396455            $prepared_comment['comment_author'] = $user->display_name;
    … …  
    399458        }
    400459
    401         // Honor the discussion setting that requires a name and email address
    402         // of the comment author.
     460        // Honor the discussion setting that requires a name and email address of the comment author.
    403461        if ( get_option( 'require_name_email' ) ) {
    404462            if ( ! isset( $prepared_comment['comment_author'] ) && ! isset( $prepared_comment['comment_author_email'] ) ) {
    405463                return new WP_Error( 'rest_comment_author_data_required', __( 'Creating a comment requires valid author name and email values.' ), array( 'status' => 400 ) );
    406464            }
     465
    407466            if ( ! isset( $prepared_comment['comment_author'] ) ) {
    408467                return new WP_Error( 'rest_comment_author_required', __( 'Creating a comment requires a valid author name.' ), array( 'status' => 400 ) );
    409468            }
     469
    410470            if ( ! isset( $prepared_comment['comment_author_email'] ) ) {
    411471                return new WP_Error( 'rest_comment_author_email_required', __( 'Creating a comment requires a valid author email.' ), array( 'status' => 400 ) );
    … …  
    416476            $prepared_comment['comment_author_email'] = '';
    417477        }
     478
    418479        if ( ! isset( $prepared_comment['comment_author_url'] ) ) {
    419480            $prepared_comment['comment_author_url'] = '';
    … …  
    427488
    428489        if ( is_wp_error( $prepared_comment['comment_approved'] ) ) {
    429             $error_code = $prepared_comment['comment_approved']->get_error_code();
     490            $error_code    = $prepared_comment['comment_approved']->get_error_code();
    430491            $error_message = $prepared_comment['comment_approved']->get_error_message();
    431492
    … …  
    442503
    443504        /**
    444          * Filter a comment before it is inserted via the REST API.
    445          *
    446          * Allows modification of the comment right before it is inserted via `wp_insert_comment`.
    447          *
    448          * @param array           $prepared_comment The prepared comment data for `wp_insert_comment`.
     505         * Filters a comment before it is inserted via the REST API.
     506         *
     507         * Allows modification of the comment right before it is inserted via wp_insert_comment().
     508         *
     509         * @since 4.7.0
     510         *
     511         * @param array           $prepared_comment The prepared comment data for wp_insert_comment().
    449512         * @param WP_REST_Request $request          Request used to insert the comment.
    450513         */
    … …  
    452515
    453516        $comment_id = wp_insert_comment( $prepared_comment );
     517
    454518        if ( ! $comment_id ) {
    455519            return new WP_Error( 'rest_comment_failed_create', __( 'Creating comment failed.' ), array( 'status' => 500 ) );
    … …  
    458522        if ( isset( $request['status'] ) ) {
    459523            $comment = get_comment( $comment_id );
     524
    460525            $this->handle_status_param( $request['status'], $comment );
    461526        }
    462527
    463528        $schema = $this->get_item_schema();
     529
    464530        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    465531            $meta_update = $this->meta->update_value( $request['meta'], $comment_id );
     532
    466533            if ( is_wp_error( $meta_update ) ) {
    467534                return $meta_update;
    … …  
    470537
    471538        $comment = get_comment( $comment_id );
     539
    472540        $fields_update = $this->update_additional_fields_for_object( $comment, $request );
     541
    473542        if ( is_wp_error( $fields_update ) ) {
    474543            return $fields_update;
    … …  
    476545
    477546        $context = current_user_can( 'moderate_comments' ) ? 'edit' : 'view';
     547
    478548        $request->set_param( 'context', $context );
     549
    479550        $response = $this->prepare_item_for_response( $comment, $request );
    480551        $response = rest_ensure_response( $response );
     552
    481553        $response->set_status( 201 );
    482554        $response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $comment_id ) ) );
    … …  
    485557         * Fires after a comment is created or updated via the REST API.
    486558         *
     559         * @since 4.7.0
     560         *
    487561         * @param array           $comment  Comment as it exists in the database.
    488562         * @param WP_REST_Request $request  The request sent to the API.
    489          * @param boolean         $creating True when creating a comment, false when updating.
     563         * @param bool            $creating True when creating a comment, false when updating.
    490564         */
    491565        do_action( 'rest_insert_comment', $comment, $request, true );
    … …  
    495569
    496570    /**
    497      * Check if a given request has access to update a comment
    498      *
    499      * @param  WP_REST_Request $request Full details about the request.
    500      * @return WP_Error|boolean
     571     * Checks if a given REST request has access to update a comment.
     572     *
     573     * @since 4.7.0
     574     * @access public
     575     *
     576     * @param WP_REST_Request $request Full details about the request.
     577     * @return WP_Error|bool True if the request has access to update the item, error object otherwise.
    501578     */
    502579    public function update_item_permissions_check( $request ) {
    … …  
    514591
    515592    /**
    516      * Edit a comment
    517      *
    518      * @param  WP_REST_Request $request Full details about the request.
    519      * @return WP_Error|WP_REST_Response
     593     * Updates a comment.
     594     *
     595     * @since 4.7.0
     596     * @access public
     597     *
     598     * @param WP_REST_Request $request Full details about the request.
     599     * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
    520600     */
    521601    public function update_item( $request ) {
    … …  
    523603
    524604        $comment = get_comment( $id );
     605
    525606        if ( empty( $comment ) ) {
    526607            return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
    … …  
    532613
    533614        $prepared_args = $this->prepare_item_for_database( $request );
     615
    534616        if ( is_wp_error( $prepared_args ) ) {
    535617            return $prepared_args;
    … …  
    539621            // Only the comment status is being changed.
    540622            $change = $this->handle_status_param( $request['status'], $comment );
     623
    541624            if ( ! $change ) {
    542625                return new WP_Error( 'rest_comment_failed_edit', __( 'Updating comment status failed.' ), array( 'status' => 500 ) );
    … …  
    550633
    551634            $updated = wp_update_comment( $prepared_args );
     635
    552636            if ( 0 === $updated ) {
    553637                return new WP_Error( 'rest_comment_failed_edit', __( 'Updating comment failed.' ), array( 'status' => 500 ) );
    … …  
    560644
    561645        $schema = $this->get_item_schema();
     646
    562647        if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
    563648            $meta_update = $this->meta->update_value( $request['meta'], $id );
     649
    564650            if ( is_wp_error( $meta_update ) ) {
    565651                return $meta_update;
    … …  
    568654
    569655        $comment = get_comment( $id );
     656
    570657        $fields_update = $this->update_additional_fields_for_object( $comment, $request );
     658
    571659        if ( is_wp_error( $fields_update ) ) {
    572660            return $fields_update;
    … …  
    574662
    575663        $request->set_param( 'context', 'edit' );
     664
    576665        $response = $this->prepare_item_for_response( $comment, $request );
    577666
    … …  
    583672
    584673    /**
    585      * Check if a given request has access to delete a comment
    586      *
    587      * @param  WP_REST_Request $request Full details about the request.
    588      * @return WP_Error|boolean
     674     * Checks if a given request has access to delete a comment.
     675     *
     676     * @since 4.7.0
     677     * @access public
     678     *
     679     * @param WP_REST_Request $request Full details about the request.
     680     * @return WP_Error|bool True if the request has access to delete the item, error object otherwise.
    589681     */
    590682    public function delete_item_permissions_check( $request ) {
    591         $id = (int) $request['id'];
     683        $id      = (int) $request['id'];
    592684        $comment = get_comment( $id );
     685
    593686        if ( ! $comment ) {
    594687            return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
    595688        }
     689
    596690        if ( ! $this->check_edit_permission( $comment ) ) {
    597691            return new WP_Error( 'rest_cannot_delete', __( 'Sorry, you can not delete this comment.' ), array( 'status' => rest_authorization_required_code() ) );
    … …  
    601695
    602696    /**
    603      * Delete a comment.
    604      *
    605      * @param  WP_REST_Request $request Full details about the request.
    606      * @return WP_Error|WP_REST_Response
     697     * Deletes a comment.
     698     *
     699     * @since 4.7.0
     700     * @access public
     701     *
     702     * @param WP_REST_Request $request Full details about the request.
     703     * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
    607704     */
    608705    public function delete_item( $request ) {
    609         $id = (int) $request['id'];
     706        $id    = (int) $request['id'];
    610707        $force = isset( $request['force'] ) ? (bool) $request['force'] : false;
    611708
    612709        $comment = get_comment( $id );
     710
    613711        if ( empty( $comment ) ) {
    614712            return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
    … …  
    616714
    617715        /**
    618          * Filter whether a comment is trashable.
     716         * Filters whether a comment can be trashed.
    619717         *
    620718         * Return false to disable trash support for the post.
    621719         *
    622          * @param boolean $supports_trash Whether the post type support trashing.
     720         * @since 4.7.0
     721         *
     722         * @param bool    $supports_trash Whether the post type support trashing.
    623723         * @param WP_Post $comment        The comment object being considered for trashing support.
    624724         */
    … …  
    626726
    627727        $request->set_param( 'context', 'edit' );
     728
    628729        $response = $this->prepare_item_for_response( $comment, $request );
    629730
    … …  
    631732            $result = wp_delete_comment( $comment->comment_ID, true );
    632733        } else {
    633             // If we don't support trashing for this type, error out
     734            // If this type doesn't support trashing, error out.
    634735            if ( ! $supports_trash ) {
    635736                return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing.' ), array( 'status' => 501 ) );
    … …  
    650751         * Fires after a comment is deleted via the REST API.
    651752         *
    652          * @param object           $comment  The deleted comment data.
     753         * @since 4.7.0
     754         *
     755         * @param WP_Comment       $comment  The deleted comment data.
    653756         * @param WP_REST_Response $response The response returned from the API.
    654757         * @param WP_REST_Request  $request  The request sent to the API.
    … …  
    660763
    661764    /**
    662      * Prepare a single comment output for response.
    663      *
    664      * @param  object          $comment Comment object.
    665      * @param  WP_REST_Request $request Request object.
    666      * @return WP_REST_Response $response
     765     * Prepares a single comment output for response.
     766     *
     767     * @since 4.7.0
     768     * @access public
     769     *
     770     * @param WP_Comment      $comment Comment object.
     771     * @param WP_REST_Request $request Request object.
     772     * @return WP_REST_Response Response object.
    667773     */
    668774    public function prepare_item_for_response( $comment, $request ) {
    … …  
    680786            'date_gmt'           => mysql_to_rfc3339( $comment->comment_date_gmt ),
    681787            'content'            => array(
     788                /** This filter is documented in wp-includes/comment-template.php */
    682789                'rendered' => apply_filters( 'comment_text', $comment->comment_content, $comment ),
    683790                'raw'      => $comment->comment_content,
    … …  
    700807
    701808        $context = ! empty( $request['context'] ) ? $request['context'] : 'view';
    702         $data = $this->add_additional_fields_to_object( $data, $request );
    703         $data = $this->filter_response_by_context( $data, $context );
    704 
    705         // Wrap the data in a response object
     809        $data    = $this->add_additional_fields_to_object( $data, $request );
     810        $data    = $this->filter_response_by_context( $data, $context );
     811
     812        // Wrap the data in a response object.
    706813        $response = rest_ensure_response( $data );
    707814
    … …  
    709816
    710817        /**
    711          * Filter a comment returned from the API.
     818         * Filters a comment returned from the API.
    712819         *
    713820         * Allows modification of the comment right before it is returned.
    714821         *
    715          * @param WP_REST_Response  $response   The response object.
    716          * @param object            $comment    The original comment object.
    717          * @param WP_REST_Request   $request    Request used to generate the response.
     822         * @since 4.7.0
     823         *
     824         * @param WP_REST_Response  $response The response object.
     825         * @param WP_Comment        $comment  The original comment object.
     826         * @param WP_REST_Request   $request  Request used to generate the response.
    718827         */
    719828        return apply_filters( 'rest_prepare_comment', $response, $comment, $request );
    … …  
    721830
    722831    /**
    723      * Prepare links for the request.
    724      *
    725      * @param object $comment Comment object.
     832     * Prepares links for the request.
     833     *
     834     * @since 4.7.0
     835     * @access protected
     836     *
     837     * @param WP_Comment $comment Comment object.
    726838     * @return array Links for the given comment.
    727839     */
    … …  
    745857        if ( 0 !== (int) $comment->comment_post_ID ) {
    746858            $post = $this->get_post( $comment->comment_post_ID );
     859
    747860            if ( ! empty( $post->ID ) ) {
    748861                $obj = get_post_type_object( $post->post_type );
    … …  
    765878
    766879        // Only grab one comment to verify the comment has children.
    767         $comment_children = $comment->get_children( array( 'number' => 1, 'count' => true ) );
     880        $comment_children = $comment->get_children( array(
     881            'number' => 1,
     882            'count'  => true
     883        ) );
     884
    768885        if ( ! empty( $comment_children ) ) {
    769             $args = array( 'parent' => $comment->comment_ID );
     886            $args = array(
     887                'parent' => $comment->comment_ID
     888            );
     889
    770890            $rest_url = add_query_arg( $args, rest_url( $this->namespace . '/' . $this->rest_base ) );
    771891
    … …  
    779899
    780900    /**
    781      * Prepend internal property prefix to query parameters to match our response fields.
    782      *
    783      * @param  string $query_param
    784      * @return string $normalized
     901     * Prepends internal property prefix to query parameters to match our response fields.
     902     *
     903     * @since 4.7.0
     904     * @access protected
     905     *
     906     * @param string $query_param Query parameter.
     907     * @return string The normalized query parameter.
    785908     */
    786909    protected function normalize_query_param( $query_param ) {
    … …  
    809932
    810933    /**
    811      * Check comment_approved to set comment status for single comment output.
    812      *
    813      * @param  string|int $comment_approved
    814      * @return string     $status
     934     * Checks comment_approved to set comment status for single comment output.
     935     *
     936     * @since 4.7.0
     937     * @access protected
     938     *
     939     * @param string|int $comment_approved comment status.
     940     * @return string Comment status.
    815941     */
    816942    protected function prepare_status_response( $comment_approved ) {
    … …  
    838964
    839965    /**
    840      * Prepare a single comment to be inserted into the database.
    841      *
    842      * @param  WP_REST_Request $request Request object.
    843      * @return array|WP_Error  $prepared_comment
     966     * Prepares a single comment to be inserted into the database.
     967     *
     968     * @since 4.7.0
     969     * @access protected
     970     *
     971     * @param WP_REST_Request $request Request object.
     972     * @return array|WP_Error Prepared comment, otherwise WP_Error object.
    844973     */
    845974    protected function prepare_item_for_database( $request ) {
    846975        $prepared_comment = array();
    847976
    848         /**
     977        /*
    849978         * Allow the comment_content to be set via the 'content' or
    850979         * the 'content.raw' properties of the Request object.
    … …  
    866995        if ( isset( $request['author'] ) ) {
    867996            $user = new WP_User( $request['author'] );
     997
    868998            if ( $user->exists() ) {
    869999                $prepared_comment['user_id'] = $user->ID;
    … …  
    9191049        }
    9201050
    921         // Require 'comment_content' unless only the 'comment_status' is being
    922         // updated.
     1051        // Require 'comment_content' unless only the 'comment_status' is being updated.
    9231052        if ( ! empty( $prepared_comment ) && ! isset( $prepared_comment['comment_content'] ) ) {
    9241053            return new WP_Error( 'rest_comment_content_required', __( 'Missing comment content.' ), array( 'status' => 400 ) );
    9251054        }
    9261055
     1056        /**
     1057         * Filters a comment after it is prepared for the database.
     1058         *
     1059         * Allows modification of the comment right after it is prepared for the database.
     1060         *
     1061         * @since 4.7.0
     1062         *
     1063         * @param array           $prepared_comment The prepared comment data for `wp_insert_comment`.
     1064         * @param WP_REST_Request $request          The current request.
     1065         */
    9271066        return apply_filters( 'rest_preprocess_comment', $prepared_comment, $request );
    9281067    }
    9291068
    9301069    /**
    931      * Get the Comment's schema, conforming to JSON Schema
     1070     * Retrieves the comment's schema, conforming to JSON Schema.
     1071     *
     1072     * @since 4.7.0
     1073     * @access public
    9321074     *
    9331075     * @return array
    … …  
    10921234
    10931235    /**
    1094      * Get the query params for collections
    1095      *
    1096      * @return array
     1236     * Retrieves the query params for collections.
     1237     *
     1238     * @since 4.7.0
     1239     * @access public
     1240     *
     1241     * @return array Comments collection parameters.
    10971242     */
    10981243    public function get_collection_params() {
    … …  
    11071252            'validate_callback' => 'rest_validate_request_arg',
    11081253        );
     1254
    11091255        $query_params['author'] = array(
    11101256            'description'       => __( 'Limit result set to comments assigned to specific user ids. Requires authorization.' ),
    … …  
    11121258            'type'              => 'array',
    11131259        );
     1260
    11141261        $query_params['author_exclude'] = array(
    11151262            'description'       => __( 'Ensure result set excludes comments assigned to specific user ids. Requires authorization.' ),
    … …  
    11171264            'type'              => 'array',
    11181265        );
     1266
    11191267        $query_params['author_email'] = array(
    11201268            'default'           => null,
    … …  
    11241272            'type'              => 'string',
    11251273        );
     1274
    11261275        $query_params['before'] = array(
    11271276            'description'       => __( 'Limit response to resources published before a given ISO8601 compliant date.' ),
    … …  
    11301279            'validate_callback' => 'rest_validate_request_arg',
    11311280        );
     1281
    11321282        $query_params['exclude'] = array(
    11331283            'description'        => __( 'Ensure result set excludes specific ids.' ),
    … …  
    11361286            'sanitize_callback'  => 'wp_parse_id_list',
    11371287        );
     1288
    11381289        $query_params['include'] = array(
    11391290            'description'        => __( 'Limit result set to specific ids.' ),
    … …  
    11421293            'sanitize_callback'  => 'wp_parse_id_list',
    11431294        );
     1295
    11441296        $query_params['karma'] = array(
    11451297            'default'           => null,
    … …  
    11491301            'validate_callback'  => 'rest_validate_request_arg',
    11501302        );
     1303
    11511304        $query_params['offset'] = array(
    11521305            'description'        => __( 'Offset the result set by a specific number of comments.' ),
    … …  
    11551308            'validate_callback'  => 'rest_validate_request_arg',
    11561309        );
     1310
    11571311        $query_params['order']      = array(
    11581312            'description'           => __( 'Order sort attribute ascending or descending.' ),
    … …  
    11661320            ),
    11671321        );
     1322
    11681323        $query_params['orderby']    = array(
    11691324            'description'           => __( 'Sort collection by object attribute.' ),
    … …  
    11821337            ),
    11831338        );
     1339
    11841340        $query_params['parent'] = array(
    11851341            'default'           => array(),
    … …  
    11881344            'type'              => 'array',
    11891345        );
     1346
    11901347        $query_params['parent_exclude'] = array(
    11911348            'default'           => array(),
    … …  
    11941351            'type'              => 'array',
    11951352        );
     1353
    11961354        $query_params['post']   = array(
    11971355            'default'           => array(),
    … …  
    12001358            'sanitize_callback' => 'wp_parse_id_list',
    12011359        );
     1360
    12021361        $query_params['status'] = array(
    12031362            'default'           => 'approve',
    … …  
    12071366            'validate_callback' => 'rest_validate_request_arg',
    12081367        );
     1368
    12091369        $query_params['type'] = array(
    12101370            'default'           => 'comment',
    … …  
    12141374            'validate_callback' => 'rest_validate_request_arg',
    12151375        );
     1376
    12161377        return $query_params;
    12171378    }
    12181379
    12191380    /**
    1220      * Set the comment_status of a given comment object when creating or updating a comment.
    1221      *
    1222      * @param string|int $new_status
    1223      * @param object     $comment
    1224      * @return boolean   $changed
     1381     * Sets the comment_status of a given comment object when creating or updating a comment.
     1382     *
     1383     * @since 4.7.0
     1384     * @access protected
     1385     *
     1386     * @param string|int $new_status New comment status.
     1387     * @param WP_Comment $comment    Comment data.
     1388     * @return bool Whether the status was changed.
    12251389     */
    12261390    protected function handle_status_param( $new_status, $comment ) {
    … …  
    12621426
    12631427    /**
    1264      * Check if we can read a post.
     1428     * Checks if the post can be read.
    12651429     *
    12661430     * Correctly handles posts with the inherit status.
    12671431     *
    1268      * @param  WP_Post $post Post Object.
    1269      * @return boolean Can we read it?
     1432     * @since 4.7.0
     1433     * @access protected
     1434     *
     1435     * @param WP_Post $post Post Object.
     1436     * @return bool Whether post can be read.
    12701437     */
    12711438    protected function check_read_post_permission( $post ) {
    … …  
    12761443
    12771444    /**
    1278      * Check if we can read a comment.
    1279      *
    1280      * @param  object  $comment Comment object.
    1281      * @return boolean Can we read it?
     1445     * Checks if the comment can be read.
     1446     *
     1447     * @since 4.7.0
     1448     * @access protected
     1449     *
     1450     * @param WP_Comment $comment Comment object.
     1451     * @return bool Whether the comment can be read.
    12821452     */
    12831453    protected function check_read_permission( $comment ) {
    … …  
    13071477
    13081478    /**
    1309      * Check if we can edit or delete a comment.
    1310      *
    1311      * @param  object  $comment Comment object.
    1312      * @return boolean Can we edit or delete it?
     1479     * Checks if a comment can be edited or deleted.
     1480     *
     1481     * @since 4.7.0
     1482     * @access protected
     1483     *
     1484     * @param object $comment Comment object.
     1485     * @return bool Whether the comment can be edited or deleted.
    13131486     */
    13141487    protected function check_edit_permission( $comment ) {
Note: See TracChangeset for help on using the changeset viewer.