WordPress.org

Make WordPress Core

Changeset 12761


Ignore:
Timestamp:
01/19/2010 05:08:04 PM (10 years ago)
Author:
ryan
Message:

phpdoc for metadata API. Props wnorris. fixes #11943

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/meta.php

    r12605 r12761  
    11<?php
    22/**
    3  * Meta API
    4  *
    5  * Functions for retrieving and manipulating metadata
     3 * Metadata API
     4 *
     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
     
    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 )
     
    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 )
     
    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) )
     
    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 )
     
    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 ) )
     
    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;
Note: See TracChangeset for help on using the changeset viewer.