WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
03/25/2014 08:55:44 AM (11 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/meta.php.

Props raamdev and kpdesign.
Fixes #25826.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/meta.php

    r27689 r27698  
    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)
    … …  
    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 )
    … …  
    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
    … …  
    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
    … …  
    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)
    … …  
    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 )
    … …  
    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
    … …  
    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;
    … …  
    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)
    … …  
    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 )
    … …  
    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 ) . " )";
    … …  
    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;
    … …  
    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 ) {
    … …  
    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 )
    … …  
    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.
    … …  
    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;
    … …  
    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
    … …  
    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;
    … …  
    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    }
    … …  
    8881107
    8891108/**
    890  * Determine whether a meta key is protected
     1109 * Determine whether a meta key is protected.
    8911110 *
    8921111 * @since 3.1.3
    … …  
    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
    … …  
    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}
Note: See TracChangeset for help on using the changeset viewer.