WordPress.org
Get WordPress

Make WordPress Core

Changeset 39022


Ignore:
Timestamp:
10/30/2016 04:32:05 PM (8 years ago)
Author:
DrewAPicture
Message:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/rest-api/fields/class-wp-rest-meta-fields.php

    r38832 r39022  
    11<?php
    2 
    32/**
    4  * Manage meta values for an object.
     3 * REST API: WP_REST_Meta_Fields class
     4 *
     5 * @package WordPress
     6 * @subpackage REST_API
     7 * @since 4.7.0
     8 */
     9
     10/**
     11 * Core class to manage meta values for an object via the REST API.
     12 *
     13 * @since 4.7.0
    514 */
    615abstract class WP_REST_Meta_Fields {
    716
    817    /**
    9      * Get the object type for meta.
     18     * Retrieves the object meta type.
     19     *
     20     * @since 4.7.0
     21     * @access protected
    1022     *
    1123     * @return string One of 'post', 'comment', 'term', 'user', or anything
    … …  
    1527
    1628    /**
    17      * Get the object type for `register_rest_field`.
    18      *
    19      * @return string Custom post type, 'taxonomy', 'comment', or `user`.
     29     * Retrieves the object type for register_rest_field().
     30     *
     31     * @since 4.7.0
     32     * @access protected
     33     *
     34     * @return string The REST field type, such as post type name, taxonomy name, 'comment', or `user`.
    2035     */
    2136    abstract protected function get_rest_field_type();
    2237
    2338    /**
    24      * Register the meta field.
     39     * Registers the meta field.
     40     *
     41     * @since 4.7.0
     42     * @access public
     43     *
     44     * @see register_rest_field()
    2545     */
    2646    public function register_field() {
    2747        register_rest_field( $this->get_rest_field_type(), 'meta', array(
    28             'get_callback' => array( $this, 'get_value' ),
     48            'get_callback'    => array( $this, 'get_value' ),
    2949            'update_callback' => array( $this, 'update_value' ),
    30             'schema' => $this->get_field_schema(),
     50            'schema'          => $this->get_field_schema(),
    3151        ));
    3252    }
    3353
    3454    /**
    35      * Get the `meta` field value.
     55     * Retrieves the meta field value.
     56     *
     57     * @since 4.7.0
     58     * @access public
    3659     *
    3760     * @param int             $object_id Object ID to fetch meta for.
    3861     * @param WP_REST_Request $request   Full details about the request.
    39      * @return WP_Error|object
     62     * @return WP_Error|object Object containing the meta values by name, otherwise WP_Error object.
    4063     */
    4164    public function get_value( $object_id, $request ) {
    … …  
    6689
    6790    /**
    68      * Prepare value for response.
    69      *
    70      * This is required because some native types cannot be stored correctly in
    71      * the database, such as booleans. We need to cast back to the relevant
     91     * Prepares a meta value for a response.
     92     *
     93     * This is required because some native types cannot be stored correctly
     94     * in the database, such as booleans. We need to cast back to the relevant
    7295     * type before passing back to JSON.
    7396     *
    74      * @param mixed           $value   Value to prepare.
     97     * @since 4.7.0
     98     * @access protected
     99     *
     100     * @param mixed           $value   Meta value to prepare.
    75101     * @param WP_REST_Request $request Current request object.
    76102     * @param array           $args    Options for the field.
    … …  
    86112
    87113    /**
    88      * Update meta values.
    89      *
    90      * @param WP_REST_Request $request    Full details about the request.
    91      * @param int             $object_id  Object ID to fetch meta for.
    92      * @return WP_Error|null Error if one occurs, null on success.
     114     * Updates meta values.
     115     *
     116     * @since 4.7.0
     117     * @access public
     118     *
     119     * @param WP_REST_Request $request   Full details about the request.
     120     * @param int             $object_id Object ID to fetch meta for.
     121     * @return WP_Error|null WP_Error if one occurs, null on success.
    93122     */
    94123    public function update_value( $request, $object_id ) {
    … …  
    100129            }
    101130
    102             // A null value means reset the field, which is essentially deleting it
    103             // from the database and then relying on the default value.
     131            /*
     132             * A null value means reset the field, which is essentially deleting it
     133             * from the database and then relying on the default value.
     134             */
    104135            if ( is_null( $request[ $name ] ) ) {
    105136                $result = $this->delete_meta_value( $object_id, $name );
    … …  
    119150
    120151    /**
    121      * Delete meta value for an object.
     152     * Deletes a meta value for an object.
     153     *
     154     * @since 4.7.0
     155     * @access protected
    122156     *
    123157     * @param int    $object_id Object ID the field belongs to.
    124158     * @param string $name      Key for the field.
    125      * @return bool|WP_Error True if meta field is deleted, error otherwise.
     159     * @return bool|WP_Error True if meta field is deleted, WP_Error otherwise.
    126160     */
    127161    protected function delete_meta_value( $object_id, $name ) {
    … …  
    146180
    147181    /**
    148      * Update multiple meta values for an object.
     182     * Updates multiple meta values for an object.
    149183     *
    150184     * Alters the list of values in the database to match the list of provided values.
     185     *
     186     * @since 4.7.0
     187     * @access protected
    151188     *
    152189     * @param int    $object_id Object ID to update.
    153190     * @param string $name      Key for the custom field.
    154191     * @param array  $values    List of values to update to.
    155      * @return bool|WP_Error True if meta fields are updated, error otherwise.
     192     * @return bool|WP_Error True if meta fields are updated, WP_Error otherwise.
    156193     */
    157194    protected function update_multi_meta_value( $object_id, $name, $values ) {
    … …  
    167204
    168205        $to_remove = $current;
    169         $to_add = $values;
     206        $to_add    = $values;
     207
    170208        foreach ( $to_add as $add_key => $value ) {
    171209            $remove_keys = array_keys( $to_remove, $value, true );
     210
    172211            if ( empty( $remove_keys ) ) {
    173212                continue;
    … …  
    180219
    181220            $remove_key = $remove_keys[0];
     221
    182222            unset( $to_remove[ $remove_key ] );
    183223            unset( $to_add[ $add_key ] );
    184224        }
    185225
    186         // `delete_metadata` removes _all_ instances of the value, so only call
    187         // once.
     226        // `delete_metadata` removes _all_ instances of the value, so only call once.
    188227        $to_remove = array_unique( $to_remove );
     228
    189229        foreach ( $to_remove as $value ) {
    190230            if ( ! delete_metadata( $this->get_meta_type(), $object_id, wp_slash( $name ), wp_slash( $value ) ) ) {
    … …  
    196236            }
    197237        }
     238
    198239        foreach ( $to_add as $value ) {
    199240            if ( ! add_metadata( $this->get_meta_type(), $object_id, wp_slash( $name ), wp_slash( $value ) ) ) {
    … …  
    210251
    211252    /**
    212      * Update meta value for an object.
     253     * Updates a meta value for an object.
     254     *
     255     * @since 4.7.0
     256     * @access protected
    213257     *
    214258     * @param int    $object_id Object ID to update.
    215259     * @param string $name      Key for the custom field.
    216260     * @param mixed  $value     Updated value.
    217      * @return bool|WP_Error True if meta field is updated, error otherwise.
     261     * @return bool|WP_Error True if the meta field was updated, WP_Error otherwise.
    218262     */
    219263    protected function update_meta_value( $object_id, $name, $value ) {
    … …  
    232276        // Do the exact same check for a duplicate value as in update_metadata() to avoid update_metadata() returning false.
    233277        $old_value = get_metadata( $meta_type, $object_id, $meta_key );
     278
    234279        if ( 1 === count( $old_value ) ) {
    235280            if ( $old_value[0] === $meta_value ) {
    … …  
    250295
    251296    /**
    252      * Get all the registered meta fields.
    253      *
    254      * @return array
     297     * Retrieves all the registered meta fields.
     298     *
     299     * @since 4.7.0
     300     * @access protected
     301     *
     302     * @return array Registered fields.
    255303     */
    256304    protected function get_registered_fields() {
    … …  
    263311
    264312            $rest_args = array();
     313
    265314            if ( is_array( $args['show_in_rest'] ) ) {
    266315                $rest_args = $args['show_in_rest'];
    … …  
    273322                'prepare_callback' => array( $this, 'prepare_value' ),
    274323            );
     324
    275325            $default_schema = array(
    276326                'type'        => null,
    … …  
    278328                'default'     => isset( $args['default'] ) ? $args['default'] : null,
    279329            );
     330
    280331            $rest_args = array_merge( $default_args, $rest_args );
    281332            $rest_args['schema'] = array_merge( $default_schema, $rest_args['schema'] );
    … …  
    298349
    299350            $registered[ $rest_args['name'] ] = $rest_args;
    300         } // End foreach().
     351        }
    301352
    302353        return $registered;
    … …  
    304355
    305356    /**
    306      * Get the object's `meta` schema, conforming to JSON Schema.
    307      *
    308      * @return array
     357     * Retrieves the object's meta schema, conforming to JSON Schema.
     358     *
     359     * @since 4.7.0
     360     * @access protected
     361     *
     362     * @return array Field schema data.
    309363     */
    310364    public function get_field_schema() {
    … …  
    326380
    327381    /**
    328      * Prepare a meta value for output.
     382     * Prepares a meta value for output.
    329383     *
    330384     * Default preparation for meta fields. Override by passing the
    331385     * `prepare_callback` in your `show_in_rest` options.
     386     *
     387     * @since 4.7.0
     388     * @access public
    332389     *
    333390     * @param mixed           $value   Meta value from the database.
    334391     * @param WP_REST_Request $request Request object.
    335392     * @param array           $args    REST-specific options for the meta key.
    336      * @return mixed Value prepared for output.
     393     * @return mixed Value prepared for output. If a non-JsonSerializable object, null.
    337394     */
    338395    public static function prepare_value( $value, $request, $args ) {
Note: See TracChangeset for help on using the changeset viewer.