WordPress.org

Make WordPress Core

Ticket #11943: meta.diff

File meta.diff, 5.7 KB (added by wnorris, 6 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