WordPress.org
Get WordPress

Make WordPress Core

Ticket #25826: 25826.4.diff

File 25826.4.diff, 15.8 KB (added by DrewAPicture, 10 years ago)

Final pass.

  • src/wp-includes/meta.php

     
    1616 *
    1717 * @since 2.9.0
    1818 * @uses $wpdb WordPress database object for queries.
    19  * @uses do_action() Calls 'added_{$meta_type}_meta' with meta_id of added metadata entry,
    20  *              object ID, meta key, and meta value
    2119 *
    2220 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
    2321 * @param int $object_id ID of the object metadata is for
    … …  
    4745        $meta_value = wp_unslash($meta_value);
    4846        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
    4947
     48        /**
     49         * Filter whether to add metadata of a specific type.
     50         *
     51         * The dynamic portion of the hook, $meta_type, refers to the meta
     52         * object type (comment, post, or user). Returning a non-null value
     53         * will effectively short-circuit the function.
     54         *
     55         * @since 3.1.0
     56         *
     57         * @param null|bool $check      Whether to allow adding metadata for the given type.
     58         * @param int       $object_id  Object ID.
     59         * @param string    $meta_key   Meta key.
     60         * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
     61         * @param bool      $unique     Whether the specified meta key should be unique
     62         *                              for the object. Optional. Default false.
     63         */
    5064        $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
    5165        if ( null !== $check )
    5266                return $check;
    … …  
    5973        $_meta_value = $meta_value;
    6074        $meta_value = maybe_serialize( $meta_value );
    6175
     76        /**
     77         * Fires immediately before meta of a specific type is added.
     78         *
     79         * The dynamic portion of the hook, $meta_type, refers to the meta
     80         * object type (comment, post, or user).
     81         *
     82         * @since 3.1.0
     83         *
     84         * @param int    $object_id  Object ID.
     85         * @param string $meta_key   Meta key.
     86         * @param mixed  $meta_value Meta value.
     87         */
    6288        do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
    6389
    6490        $result = $wpdb->insert( $table, array(
    … …  
    74100
    75101        wp_cache_delete($object_id, $meta_type . '_meta');
    76102
     103        /**
     104         * Fires immediately after meta of a specific type is added.
     105         *
     106         * The dynamic portion of the hook, $meta_type, refers to the meta
     107         * object type (comment, post, or user).
     108         *
     109         * @since 2.9.0
     110         *
     111         * @param int    $mid        The meta ID after successful update.
     112         * @param int    $object_id  Object ID.
     113         * @param string $meta_key   Meta key.
     114         * @param mixed  $meta_value Meta value.
     115         */
    77116        do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
    78117
    79118        return $mid;
    … …  
    85124 *
    86125 * @since 2.9.0
    87126 * @uses $wpdb WordPress database object for queries.
    88  * @uses do_action() Calls 'update_{$meta_type}_meta' before updating metadata with meta_id of
    89  *              metadata entry to update, object ID, meta key, and meta value
    90  * @uses do_action() Calls 'updated_{$meta_type}_meta' after updating metadata with meta_id of
    91  *              updated metadata entry, object ID, meta key, and meta value
    92127 *
    93128 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
    94129 * @param int $object_id ID of the object metadata is for
    … …  
    119154        $meta_value = wp_unslash($meta_value);
    120155        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
    121156
     157        /**
     158         * Filter whether to update metadata of a specific type.
     159         *
     160         * The dynamic portion of the hook, $meta_type, refers to the meta
     161         * object type (comment, post, or user). Returning a non-null value
     162         * will effectively short-circuit the function.
     163         *
     164         * @since 3.1.0
     165         *
     166         * @param null|bool $check      Whether to allow updating metadata for the given type.
     167         * @param int       $object_id  Object ID.
     168         * @param string    $meta_key   Meta key.
     169         * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
     170         * @param mixed     $prev_value Optional. If specified, only update existing
     171         *                              metadata entries with the specified value.
     172         *                              Otherwise, update all entries.
     173         */
    122174        $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
    123175        if ( null !== $check )
    124176                return (bool) $check;
    … …  
    146198                $where['meta_value'] = $prev_value;
    147199        }
    148200
     201        /**
     202         * Fires immediately before updating metadata of a specific type.
     203         *
     204         * The dynamic portion of the hook, $meta_type, refers to the meta
     205         * object type (comment, post, or user).
     206         *
     207         * @since 2.9.0
     208         *
     209         * @param int    $meta_id    ID of the metadata entry to update.
     210         * @param int    $object_id  Object ID.
     211         * @param string $meta_key   Meta key.
     212         * @param mixed  $meta_value Meta value.
     213         */
    149214        do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    150215
    151216        if ( 'post' == $meta_type )
     217                /**
     218                 * Fires immediately before updating a post's metadata.
     219                 *
     220                 * @since 2.9.0
     221                 *
     222                 * @param int    $meta_id    ID of metadata entry to update.
     223                 * @param int    $object_id  Object ID.
     224                 * @param string $meta_key   Meta key.
     225                 * @param mixed  $meta_value Meta value.
     226                 */
    152227                do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
    153228
    154229        $result = $wpdb->update( $table, $data, $where );
    … …  
    157232
    158233        wp_cache_delete($object_id, $meta_type . '_meta');
    159234
     235        /**
     236         * Fires immediately after updating metadata of a specific type.
     237         *
     238         * The dynamic portion of the hook, $meta_type, refers to the meta
     239         * object type (comment, post, or user).
     240         *
     241         * @since 2.9.0
     242         *
     243         * @param int    $meta_id    ID of updated metadata entry.
     244         * @param int    $object_id  Object ID.
     245         * @param string $meta_key   Meta key.
     246         * @param mixed  $meta_value Meta value.
     247         */
    160248        do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    161249
    162         if ( 'post' == $meta_type )
     250        if ( 'post' == $meta_type ) {
     251                /**
     252                 * Fires immediately after updating a post's metadata.
     253                 *
     254                 * @since 2.9.0
     255                 *
     256                 * @param int    $meta_id    ID of updated metadata entry.
     257                 * @param int    $object_id  Object ID.
     258                 * @param string $meta_key   Meta key.
     259                 * @param mixed  $meta_value Meta value.
     260                 */
    163261                do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
     262        }
    164263
    165264        return true;
    166265}
    … …  
    170269 *
    171270 * @since 2.9.0
    172271 * @uses $wpdb WordPress database object for queries.
    173  * @uses do_action() Calls 'deleted_{$meta_type}_meta' after deleting with meta_id of
    174  *              deleted metadata entries, object ID, meta key, and meta value
    175272 *
    176273 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
    177274 * @param int $object_id ID of the object metadata is for
    … …  
    201298        $meta_key = wp_unslash($meta_key);
    202299        $meta_value = wp_unslash($meta_value);
    203300
     301        /**
     302         * Filter whether to delete metadata of a specific type.
     303         *
     304         * The dynamic portion of the hook, $meta_type, refers to the meta
     305         * object type (comment, post, or user). Returning a non-null value
     306         * will effectively short-circuit the function.
     307         *
     308         * @since 3.1.0
     309         *
     310         * @param null|bool $delete     Whether to allow metadata deletion of the given type.
     311         * @param int       $object_id  Object ID.
     312         * @param string    $meta_key   Meta key.
     313         * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
     314         * @param bool      $delete_all Whether to delete the matching metadata entries
     315         *                              for all objects, ignoring the specified $object_id.
     316         *                              Default false.
     317         */
    204318        $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
    205319        if ( null !== $check )
    206320                return (bool) $check;
    … …  
    223337        if ( $delete_all )
    224338                $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
    225339
     340        /**
     341         * Fires immediately before deleting metadata of a specific type.
     342         *
     343         * The dynamic portion of the hook, $meta_type, refers to the meta
     344         * object type (comment, post, or user).
     345         *
     346         * @since 3.1.0
     347         *
     348         * @param array  $meta_ids   An array of metadata entry IDs to delete.
     349         * @param int    $object_id  Object ID.
     350         * @param string $meta_key   Meta key.
     351         * @param mixed  $meta_value Meta value.
     352         */
    226353        do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
    227354
    228355        // Old-style action.
    229         if ( 'post' == $meta_type )
     356        if ( 'post' == $meta_type ) {
     357                /**
     358                 * Fires immediately before deleting metadata for a post.
     359                 *
     360                 * @since 2.9.0
     361                 *
     362                 * @param array $meta_ids An array of post metadata entry IDs to delete.
     363                 */
    230364                do_action( 'delete_postmeta', $meta_ids );
     365        }
    231366
    232367        $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
    233368
    … …  
    244379                wp_cache_delete($object_id, $meta_type . '_meta');
    245380        }
    246381
     382        /**
     383         * Fires immediatley after deleting metadata of a specific type.
     384         *
     385         * The dynamic portion of the hook, $meta_type, refers to the meta
     386         * object type (comment, post, or user).
     387         *
     388         * @since 2.9.0
     389         *
     390         * @param array  $meta_ids   An array of deleted metadata entry IDs.
     391         * @param int    $object_id  Object ID.
     392         * @param string $meta_key   Meta key.
     393         * @param mixed  $meta_value Meta value.
     394         */
    247395        do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
    248396
    249397        // Old-style action.
    250         if ( 'post' == $meta_type )
     398        if ( 'post' == $meta_type ) {
     399                /**
     400                 * Fires immediately after deleting metadata for a post.
     401                 *
     402                 * @since 2.9.0
     403                 *
     404                 * @param array $meta_ids An array of deleted post metadata entry IDs.
     405                 */
    251406                do_action( 'deleted_postmeta', $meta_ids );
     407        }
    252408
    253409        return true;
    254410}
    … …  
    273429        if ( !$object_id = absint($object_id) )
    274430                return false;
    275431
     432        /**
     433         * Filter whether to retrieve metadata of a specific type.
     434         *
     435         * The dynamic portion of the hook, $meta_type, refers to the meta
     436         * object type (comment, post, or user). Returning a non-null value
     437         * will effectively short-circuit the function.
     438         *
     439         * @since 3.1.0
     440         *
     441         * @param null|array|string $value     The value get_metadata() should
     442         *                                     return - a single metadata value,
     443         *                                     or an array of values.
     444         * @param int               $object_id Object ID.
     445         * @param string            $meta_key  Meta key.
     446         * @param string|array      $single    Meta value, or an array of values.
     447         */
    276448        $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
    277449        if ( null !== $check ) {
    278450                if ( $single && is_array( $check ) )
    … …  
    321493        if ( ! $object_id = absint( $object_id ) )
    322494                return false;
    323495
     496        /** This filter is documented in wp-includes/meta.php */
    324497        $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
    325498        if ( null !== $check )
    326499                return (bool) $check;
    … …  
    431604                $where = array();
    432605                $where[$id_column] = $meta_id;
    433606
     607                /** This action is documented in wp-includes/meta.php */
    434608                do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    435609
    436                 if ( 'post' == $meta_type )
     610                if ( 'post' == $meta_type ) {
     611                        /** This action is documented in wp-includes/meta.php */
    437612                        do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
     613                }
    438614
    439615                // Run the update query, all fields in $data are %s, $where is a %d.
    440616                $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
    … …  
    444620                // Clear the caches.
    445621                wp_cache_delete($object_id, $meta_type . '_meta');
    446622
     623                /** This action is documented in wp-includes/meta.php */
    447624                do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    448625
    449                 if ( 'post' == $meta_type )
     626                if ( 'post' == $meta_type ) {
     627                        /** This action is documented in wp-includes/meta.php */
    450628                        do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
     629                }
    451630
    452631                return true;
    453632        }
    … …  
    489668        if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
    490669                $object_id = $meta->{$column};
    491670
     671                /** This action is documented in wp-includes/meta.php */
    492672                do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
    493673
    494674                // Old-style action.
    495                 if ( 'post' == $meta_type || 'comment' == $meta_type )
     675                if ( 'post' == $meta_type || 'comment' == $meta_type ) {
     676                        /**
     677                         * Fires immediately before deleting post or comment metadata of a specific type.
     678                         *
     679                         * The dynamic portion of the hook, $meta_type, refers to the meta
     680                         * object type (post or comment).
     681                         *
     682                         * @since 3.4.0
     683                         *
     684                         * @param int $meta_id ID of the metadata entry to delete.
     685                         */
    496686                        do_action( "delete_{$meta_type}meta", $meta_id );
     687                }
    497688
    498689                // Run the query, will return true if deleted, false otherwise
    499690                $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
    … …  
    501692                // Clear the caches.
    502693                wp_cache_delete($object_id, $meta_type . '_meta');
    503694
     695                /** This action is documented in wp-includes/meta.php */
    504696                do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
    505697
    506698                // Old-style action.
    507                 if ( 'post' == $meta_type || 'comment' == $meta_type )
     699                if ( 'post' == $meta_type || 'comment' == $meta_type ) {
     700                        /**
     701                         * Fires immediately after deleting post or comment metadata of a specific type.
     702                         *
     703                         * The dynamic portion of the hook, $meta_type, refers to the meta
     704                         * object type (post or comment).
     705                         *
     706                         * @since 3.4.0
     707                         *
     708                         * @param int $meta_ids Deleted metadata entry ID.
     709                         */
    508710                        do_action( "deleted_{$meta_type}meta", $meta_id );
     711                }
    509712
    510713                return $result;
    511714
    … …  
    8621065                if ( ! empty( $join ) )
    8631066                        $join = ' ' . $join;
    8641067
     1068                /**
     1069                 * Filter the meta query's generated SQL.
     1070                 *
     1071                 * @since 3.1.0
     1072                 *
     1073                 * @param array $args {
     1074                 *     An array of arguments.
     1075                 *
     1076                 *     @type array  $clauses           Array containing the query's JOIN and WHERE clauses.
     1077                 *     @type array  $queries           Array of meta queries.
     1078                 *     @type string $type              Type of meta.
     1079                 *     @type string $primary_table     Primary table.
     1080                 *     @type string $primary_id_column Primary column ID.
     1081                 *     @type object $context           The main query object.
     1082                 * }
     1083                 */
    8651084                return apply_filters_ref_array( 'get_meta_sql', array( compact( 'join', 'where' ), $this->queries, $type, $primary_table, $primary_id_column, $context ) );
    8661085        }
    8671086}
    … …  
    8871106}
    8881107
    8891108/**
    890  * Determine whether a meta key is protected
     1109 * Determine whether a meta key is protected.
    8911110 *
    8921111 * @since 3.1.3
    8931112 *
    … …  
    8971116function is_protected_meta( $meta_key, $meta_type = null ) {
    8981117        $protected = ( '_' == $meta_key[0] );
    8991118
     1119        /**
     1120         * Filter whether a meta key is protected.
     1121         *
     1122         * @since 3.2.0
     1123         *
     1124         * @param bool   $protected Whether the key is protected. Default false.
     1125         * @param string $meta_key  Meta key.
     1126         * @param string $meta_type Meta type.
     1127         */
    9001128        return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
    9011129}
    9021130
    9031131/**
    904  * Sanitize meta value
     1132 * Sanitize meta value.
    9051133 *
    9061134 * @since 3.1.3
    9071135 *
    … …  
    9111139 * @return mixed Sanitized $meta_value
    9121140 */
    9131141function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
     1142
     1143        /**
     1144         * Filter the sanitization of a specific meta key of a specific meta type.
     1145         *
     1146         * The dynamic portions of the hook name, $meta_type and $meta_key, refer to the
     1147         * metadata object type (comment, post, or user) and the meta key value,
     1148         * respectively.
     1149         *
     1150         * @since 3.3.0
     1151         *
     1152         * @param mixed  $meta_value Meta value to sanitize.
     1153         * @param string $meta_key   Meta key.
     1154         * @param string $meta_type  Meta type.
     1155         */
    9141156        return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
    9151157}
    9161158