WordPress.org
Get WordPress

Make WordPress Core

Ticket #25826: 25826.3.diff

File 25826.3.diff, 13.4 KB (added by kpdesign, 10 years ago)

Third pass

  • src/wp-includes/meta.php

     
    4747        $meta_value = wp_unslash($meta_value);
    4848        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
    4949
     50        /**
     51         * Filter an object's metadata being added to the database.
     52         *
     53         * The dynamic portion of the hook, $meta_type, refers to the metadata
     54         * object type (comment, post, or user).
     55         *
     56         * @since 3.1.0
     57         *
     58         * @param int|bool $value      The meta ID on success; false on failure.
     59         * @param int      $object_id  Object ID.
     60         * @param string   $meta_key   Metadata key.
     61         * @param mixed    $meta_value Metadata value. Must be serializable if non-scalar.
     62         * @param bool     $unique     Whether the specified metadata key should be unique
     63         *                             for the object. Optional. Default false.
     64         */
    5065        $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
    5166        if ( null !== $check )
    5267                return $check;
    … …  
    5974        $_meta_value = $meta_value;
    6075        $meta_value = maybe_serialize( $meta_value );
    6176
     77        /**
     78         * Fires before adding metadata to the database.
     79         *
     80         * The dynamic portion of the hook, $meta_type, refers to the metadata
     81         * object type (comment, post, or user).
     82         *
     83         * @since 3.1.0
     84         *
     85         * @param int    $object_id  Object ID.
     86         * @param string $meta_key   Metadata key.
     87         * @param mixed  $meta_value Metadata value.
     88         */
    6289        do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
    6390
    6491        $result = $wpdb->insert( $table, array(
    … …  
    74101
    75102        wp_cache_delete($object_id, $meta_type . '_meta');
    76103
     104        /**
     105         * Fires after adding metadata to the database.
     106         *
     107         * The dynamic portion of the hook, $meta_type, refers to the metadata
     108         * object type (comment, post, or user).
     109         *
     110         * @since 2.9.0
     111         *
     112         * @param int    $mid        The meta ID after successful update.
     113         * @param int    $object_id  Object ID.
     114         * @param string $meta_key   Metadata key.
     115         * @param mixed  $meta_value Metadata value.
     116         */
    77117        do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
    78118
    79119        return $mid;
    … …  
    119159        $meta_value = wp_unslash($meta_value);
    120160        $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
    121161
     162        /**
     163         * Filter the object's metadata before it is updated in the database.
     164         *
     165         * The dynamic portion of the hook, $meta_type, refers to the metadata
     166         * object type (comment, post, or user).
     167         *
     168         * @since 3.1.0
     169         *
     170         * @param int|bool $value      The meta ID on successful update; false on failure.
     171         * @param int      $object_id  Object ID.
     172         * @param string   $meta_key   Metadata key.
     173         * @param mixed    $meta_value Metadata value. Must be serializable if non-scalar.
     174         * @param mixed    $prev_value Optional. If specified, only update existing
     175         *                             metadata entries with the specified value.
     176         *                             Otherwise, update all entries.
     177         */
    122178        $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
    123179        if ( null !== $check )
    124180                return (bool) $check;
    … …  
    146202                $where['meta_value'] = $prev_value;
    147203        }
    148204
     205        /**
     206         * Fires before updating an object's metadata in the database.
     207         *
     208         * The dynamic portion of the hook, $meta_type, refers to the metadata
     209         * object type (comment, post, or user).
     210         *
     211         * @since 2.9.0
     212         *
     213         * @param int    $meta_id    ID of the metadata entry to update.
     214         * @param int    $object_id  Object ID.
     215         * @param string $meta_key   Metadata key.
     216         * @param mixed  $meta_value Metadata value.
     217         */
    149218        do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    150219
    151220        if ( 'post' == $meta_type )
     221                /**
     222                 * Fires before updating post metadata in the database.
     223                 *
     224                 * @since 2.9.0
     225                 *
     226                 * @param int    $meta_id    ID of metadata entry to update.
     227                 * @param int    $object_id  Object ID.
     228                 * @param string $meta_key   Metadata key.
     229                 * @param mixed  $meta_value Metadata value.
     230                 */
    152231                do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
    153232
    154233        $result = $wpdb->update( $table, $data, $where );
    … …  
    157236
    158237        wp_cache_delete($object_id, $meta_type . '_meta');
    159238
     239        /**
     240         * Fires after updating an object's metadata in the database.
     241         *
     242         * The dynamic portion of the hook, $meta_type, refers to the metadata
     243         * object type (comment, post, or user).
     244         *
     245         * @since 2.9.0
     246         *
     247         * @param int    $meta_id    ID of updated metadata entry.
     248         * @param int    $object_id  Object ID.
     249         * @param string $meta_key   Metadata key.
     250         * @param mixed  $meta_value Metadata value.
     251         */
    160252        do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    161253
    162254        if ( 'post' == $meta_type )
     255                /**
     256                 * Fires after updating post metadata in the database.
     257                 *
     258                 * @since 2.9.0
     259                 *
     260                 * @param int    $meta_id    ID of updated metadata entry.
     261                 * @param int    $object_id  Object ID.
     262                 * @param string $meta_key   Metadata key.
     263                 * @param mixed  $meta_value Metadata value.
     264                 */
    163265                do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
    164266
    165267        return true;
    … …  
    201303        $meta_key = wp_unslash($meta_key);
    202304        $meta_value = wp_unslash($meta_value);
    203305
     306        /**
     307         * Filter the object's metadata before deleting it from the database.
     308         *
     309         * The dynamic portion of the hook, $meta_type, refers to the metadata
     310         * object type (comment, post, or user).
     311         *
     312         * @since 3.1.0
     313         *
     314         * @param bool   $delete     Whether to delete the metadata.
     315         * @param int    $object_id  Object ID.
     316         * @param string $meta_key   Metadata key.
     317         * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
     318         * @param bool   $delete_all Whether to delete the matching metadata entries
     319         *                           for all objects, ignoring the specified $object_id.
     320         *                           Optional. Default false.
     321         */
    204322        $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
    205323        if ( null !== $check )
    206324                return (bool) $check;
    … …  
    223341        if ( $delete_all )
    224342                $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
    225343
     344        /**
     345         * Fires before deleting an object's metadata from the database.
     346         *
     347         * The dynamic portion of the hook, $meta_type, refers to the metadata
     348         * object type (comment, post, or user).
     349         *
     350         * @since 3.1.0
     351         *
     352         * @param array  $meta_ids   An array of metadata entry IDs to delete.
     353         * @param int    $object_id  Object ID.
     354         * @param string $meta_key   Metadata key.
     355         * @param mixed  $meta_value Metadata value.
     356         */
    226357        do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
    227358
    228359        // Old-style action.
    229360        if ( 'post' == $meta_type )
     361                /**
     362                 * Fires before deleting post metadata from the database.
     363                 *
     364                 * @since 2.9.0
     365                 *
     366                 * @param array $meta_ids An array of post metadata entry IDs to delete.
     367                 */
    230368                do_action( 'delete_postmeta', $meta_ids );
    231369
    232370        $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
    … …  
    244382                wp_cache_delete($object_id, $meta_type . '_meta');
    245383        }
    246384
     385        /**
     386         * Fires after deleting an object's metadata from the database.
     387         *
     388         * The dynamic portion of the hook, $meta_type, refers to the metadata
     389         * object type (comment, post, or user).
     390         *
     391         * @since 2.9.0
     392         *
     393         * @param array  $meta_ids   An array of deleted metadata entry IDs.
     394         * @param int    $object_id  Object ID.
     395         * @param string $meta_key   Metadata key.
     396         * @param mixed  $meta_value Metadata value.
     397         */
    247398        do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
    248399
    249400        // Old-style action.
    250401        if ( 'post' == $meta_type )
     402                /**
     403                 * Fires after deleting post metadata from the database.
     404                 *
     405                 * @since 2.9.0
     406                 *
     407                 * @param array $meta_ids An array of deleted post metadata entry IDs.
     408                 */
    251409                do_action( 'deleted_postmeta', $meta_ids );
    252410
    253411        return true;
    … …  
    273431        if ( !$object_id = absint($object_id) )
    274432                return false;
    275433
     434        /**
     435         * Filter the retrieval of an object's metadata.
     436         *
     437         * The dynamic portion of the hook, $meta_type, refers to the metadata
     438         * object type (comment, post, or user).
     439         *
     440         * @since 3.1.0
     441         *
     442         * @param string|array|null $value     The value get_metadata() should
     443         *                                     return - a single metadata value,
     444         *                                     or an array of values.
     445         * @param int               $object_id Object ID.
     446         * @param string            $meta_key  Metadata key.
     447         * @param string|array      $single    Metadata value, or an array of values.
     448         */
    276449        $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
    277450        if ( null !== $check ) {
    278451                if ( $single && is_array( $check ) )
    … …  
    321494        if ( ! $object_id = absint( $object_id ) )
    322495                return false;
    323496
     497        /** This filter is documented in wp-includes/meta.php */
    324498        $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
    325499        if ( null !== $check )
    326500                return (bool) $check;
    … …  
    431605                $where = array();
    432606                $where[$id_column] = $meta_id;
    433607
     608                /** This action is documented in wp-includes/meta.php */
    434609                do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
    435610
    436611                if ( 'post' == $meta_type )
     612                        /** This action is documented in wp-includes/meta.php */
    437613                        do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
    438614
    439615                // Run the update query, all fields in $data are %s, $where is a %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
    449626                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 );
    451629
    452630                return true;
    … …  
    489667        if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
    490668                $object_id = $meta->{$column};
    491669
     670                /** This action is documented in wp-includes/meta.php */
    492671                do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
    493672
    494673                // Old-style action.
    495674                if ( 'post' == $meta_type || 'comment' == $meta_type )
     675                        /**
     676                         * Fires before deleting post or comment metadata from the database.
     677                         *
     678                         * The dynamic portion of the hook, $meta_type, refers to the metadata
     679                         * object type (post or comment).
     680                         *
     681                         * @since 3.4.0
     682                         *
     683                         * @param int $meta_id ID of the metadata entry to delete.
     684                         */
    496685                        do_action( "delete_{$meta_type}meta", $meta_id );
    497686
    498687                // Run the query, will return true if deleted, false otherwise
    … …  
    501690                // Clear the caches.
    502691                wp_cache_delete($object_id, $meta_type . '_meta');
    503692
     693                /** This action is documented in wp-includes/meta.php */
    504694                do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
    505695
    506696                // Old-style action.
    507697                if ( 'post' == $meta_type || 'comment' == $meta_type )
     698                        /**
     699                         * Fires after deleting post or comment metadata from the database.
     700                         *
     701                         * The dynamic portion of the hook, $meta_type, refers to the metadata
     702                         * object type (post or comment).
     703                         *
     704                         * @since 3.4.0
     705                         *
     706                         * @param int $meta_ids Deleted metadata entry ID.
     707                         */
    508708                        do_action( "deleted_{$meta_type}meta", $meta_id );
    509709
    510710                return $result;
    … …  
    8621062                if ( ! empty( $join ) )
    8631063                        $join = ' ' . $join;
    8641064
     1065                /**
     1066                 * Filter the generated SQL clauses to be appended to a main query.
     1067                 *
     1068                 * @since 3.1.0
     1069                 *
     1070                 * @param array $args {
     1071                 *     An array or arguments.
     1072                 *
     1073                 *     @type type $var Description.
     1074                 *     @type type $var Description.
     1075                 * }
     1076                 * @param string $type              Type of meta.
     1077                 * @param string $primary_table     Primary table.
     1078                 * @param string $primary_id_column Primary column ID.
     1079                 * @param object $context           The main query object.
     1080                 */
    8651081                return apply_filters_ref_array( 'get_meta_sql', array( compact( 'join', 'where' ), $this->queries, $type, $primary_table, $primary_id_column, $context ) );
    8661082        }
    8671083}
    … …  
    8971113function is_protected_meta( $meta_key, $meta_type = null ) {
    8981114        $protected = ( '_' == $meta_key[0] );
    8991115
     1116        /**
     1117         * Filter whether a meta key is protected.
     1118         *
     1119         * @since 3.2.0
     1120         *
     1121         * @param bool   $protected Whether the key is protected.
     1122         * @param string $meta_key  Meta key.
     1123         * @param string $meta_type Meta type.
     1124         */
    9001125        return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
    9011126}
    9021127
    … …  
    9111136 * @return mixed Sanitized $meta_value
    9121137 */
    9131138function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
     1139        /**
     1140         * Filter the sanitization of the meta value.
     1141         *
     1142         * The dynamic portions of the hook, $meta_type and $meta_key, refer to the
     1143         * metadata object type (comment, post, or user) and the meta key value,
     1144         * respectively.
     1145         *
     1146         * @since 3.3.0
     1147         *
     1148         * @param mixed  $meta_value Meta value to sanitize.
     1149         * @param string $meta_key   Meta key.
     1150         * @param string $meta_type  Meta type.
     1151         */
    9141152        return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
    9151153}
    9161154