WordPress.org

Make WordPress Core

Ticket #11943: meta.diff

File meta.diff, 5.7 KB (added by wnorris, 8 years ago)
  • wp-includes/meta.php

     
    11<?php
    22/**
    3  * Meta API
     3 * Metadata API
    44 *
    5  * Functions for retrieving and manipulating metadata
     5 * Functions for retrieving and manipulating metadata of various WordPress object types.  Metadata
     6 * for an object is a represented by a simple key-value pair.  Objects may contain multiple
     7 * metadata entries that share the same key and differ only in their value.
    68 *
    79 * @package WordPress
    810 * @subpackage Meta
    911 * @since 2.9.0
    1012 */
    1113
     14/**
     15 * Add metadata for the specified object.
     16 *
     17 * @since 2.9.0
     18 * @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
     21 *
     22 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
     23 * @param int $object_id ID of the object metadata is for
     24 * @param string $meta_key Metadata key
     25 * @param string $meta_value Metadata value
     26 * @param bool $unique Optional, default is false.  Whether the specified metadata key should be
     27 *              unique for the object.  If true, and the object already has a value for the specified
     28 *              metadata key, no change will be made
     29 * @return bool True on successful update, false on failure.
     30 */
    1231function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
    1332        if ( !$meta_type || !$meta_key )
    1433                return false;
     
    4362        return true;
    4463}
    4564
     65/**
     66 * Update metadata for the specified object.  If no value already exists for the specified object
     67 * ID and metadata key, the metadata will be added.
     68 *
     69 * @since 2.9.0
     70 * @uses $wpdb WordPress database object for queries.
     71 * @uses do_action() Calls 'update_{$meta_type}_meta' before updating metadata with meta_id of
     72 *              metadata entry to update, object ID, meta key, and meta value
     73 * @uses do_action() Calls 'updated_{$meta_type}_meta' after updating metadata with meta_id of
     74 *              updated metadata entry, object ID, meta key, and meta value
     75 *
     76 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
     77 * @param int $object_id ID of the object metadata is for
     78 * @param string $meta_key Metadata key
     79 * @param string $meta_value Metadata value
     80 * @param string $prev_value Optional.  If specified, only update existing metadata entries with
     81 *              the specified value.  Otherwise, update all entries.
     82 * @return bool True on successful update, false on failure.
     83 */
    4684function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
    4785        if ( !$meta_type || !$meta_key )
    4886                return false;
     
    81119        return true;
    82120}
    83121
     122/**
     123 * Delete metadata for the specified object.
     124 *
     125 * @since 2.9.0
     126 * @uses $wpdb WordPress database object for queries.
     127 * @uses do_action() Calls 'deleted_{$meta_type}_meta' after deleting with meta_id of
     128 *              deleted metadata entries, object ID, meta key, and meta value
     129 *
     130 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
     131 * @param int $object_id ID of the object metadata is for
     132 * @param string $meta_key Metadata key
     133 * @param string $meta_value Optional. Metadata value.  If specified, only delete metadata entries
     134 *              with this value.  Otherwise, delete all entries with the specified meta_key.
     135 * @param bool $delete_all Optional, default is false.  If true, delete matching metadata entries
     136 *              for all objects, ignoring the specified object_id.  Otherwise, only delete matching
     137 *              metadata entries for the specified object_id.
     138 * @return bool True on successful delete, false on failure.
     139 */
    84140function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
    85141        if ( !$meta_type || !$meta_key || (!$delete_all && ! (int)$object_id) )
    86142                return false;
     
    122178        return true;
    123179}
    124180
     181/**
     182 * Retrieve metadata for the specified object.
     183 *
     184 * @since 2.9.0
     185 *
     186 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
     187 * @param int $object_id ID of the object metadata is for
     188 * @param string $meta_key Optional.  Metadata key.  If not specified, retrieve all metadata for
     189 *              the specified object.
     190 * @param bool $single Optional, default is false.  If true, return only the first value of the
     191 *              specified meta_key.  This parameter has no effect if meta_key is not specified.
     192 * @return string|array Single metadata value, or array of values
     193 */
    125194function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
    126195        if ( !$meta_type )
    127196                return false;
     
    150219                return array();
    151220}
    152221
     222/**
     223 * Update the metadata cache for the specified objects.
     224 *
     225 * @since 2.9.0
     226 * @uses $wpdb WordPress database object for queries.
     227 *
     228 * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
     229 * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
     230 * @return mixed Metadata cache for the specified objects, or false on failure.
     231 */
    153232function update_meta_cache($meta_type, $object_ids) {
    154233        if ( empty( $meta_type ) || empty( $object_ids ) )
    155234                return false;
     
    212291        return $cache;
    213292}
    214293
     294/**
     295 * Retrieve the name of the metadata table for the specified object type.
     296 *
     297 * @since 2.9.0
     298 * @uses $wpdb WordPress database object for queries.
     299 *
     300 * @param string $meta_type Type of object to get metadata table for (e.g., comment, post, or user)
     301 * @return mixed Metadata table name, or false if no metadata table exists
     302 */
    215303function _get_meta_table($type) {
    216304        global $wpdb;
    217305