<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><style type="text/css"><!--
#msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; }
#msg ul, pre { overflow: auto; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<title>[12761] trunk/wp-includes/meta.php: phpdoc for metadata API.</title>
</head>
<body>
<div id="msg">
<dl>
<dt>Revision</dt> <dd><a href="http://trac.wordpress.org/changeset/12761">12761</a></dd>
<dt>Author</dt> <dd>ryan</dd>
<dt>Date</dt> <dd>2010-01-19 17:08:04 +0000 (Tue, 19 Jan 2010)</dd>
</dl>
<h3>Log Message</h3>
<pre>phpdoc for metadata API. Props wnorris. fixes <a href="http://trac.wordpress.org/ticket/11943">#11943</a></pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkwpincludesmetaphp">trunk/wp-includes/meta.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwpincludesmetaphp"></a>
<div class="modfile"><h4>Modified: trunk/wp-includes/meta.php (12760 => 12761)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-includes/meta.php 2010-01-19 17:01:39 UTC (rev 12760)
+++ trunk/wp-includes/meta.php 2010-01-19 17:08:04 UTC (rev 12761)
</span><span class="lines">@@ -1,14 +1,33 @@
</span><span class="cx"> <?php
</span><span class="cx"> /**
</span><del>- * Meta API
</del><ins>+ * Metadata API
</ins><span class="cx"> *
</span><del>- * Functions for retrieving and manipulating metadata
</del><ins>+ * Functions for retrieving and manipulating metadata of various WordPress object types. Metadata
+ * for an object is a represented by a simple key-value pair. Objects may contain multiple
+ * metadata entries that share the same key and differ only in their value.
</ins><span class="cx"> *
</span><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Meta
</span><span class="cx"> * @since 2.9.0
</span><span class="cx"> */
</span><span class="cx">
</span><ins>+/**
+ * Add metadata for the specified object.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'added_{$meta_type}_meta' with meta_id of added metadata entry,
+ * object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Metadata value
+ * @param bool $unique Optional, default is false. Whether the specified metadata key should be
+ * unique for the object. If true, and the object already has a value for the specified
+ * metadata key, no change will be made
+ * @return bool True on successful update, false on failure.
+ */
</ins><span class="cx"> function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
</span><span class="cx"> if ( !$meta_type || !$meta_key )
</span><span class="cx"> return false;
</span><span class="lines">@@ -43,6 +62,25 @@
</span><span class="cx"> return true;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Update metadata for the specified object. If no value already exists for the specified object
+ * ID and metadata key, the metadata will be added.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'update_{$meta_type}_meta' before updating metadata with meta_id of
+ * metadata entry to update, object ID, meta key, and meta value
+ * @uses do_action() Calls 'updated_{$meta_type}_meta' after updating metadata with meta_id of
+ * updated metadata entry, object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Metadata value
+ * @param string $prev_value Optional. If specified, only update existing metadata entries with
+ * the specified value. Otherwise, update all entries.
+ * @return bool True on successful update, false on failure.
+ */
</ins><span class="cx"> function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
</span><span class="cx"> if ( !$meta_type || !$meta_key )
</span><span class="cx"> return false;
</span><span class="lines">@@ -81,6 +119,24 @@
</span><span class="cx"> return true;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Delete metadata for the specified object.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ * @uses do_action() Calls 'deleted_{$meta_type}_meta' after deleting with meta_id of
+ * deleted metadata entries, object ID, meta key, and meta value
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Metadata key
+ * @param string $meta_value Optional. Metadata value. If specified, only delete metadata entries
+ * with this value. Otherwise, delete all entries with the specified meta_key.
+ * @param bool $delete_all Optional, default is false. If true, delete matching metadata entries
+ * for all objects, ignoring the specified object_id. Otherwise, only delete matching
+ * metadata entries for the specified object_id.
+ * @return bool True on successful delete, false on failure.
+ */
</ins><span class="cx"> function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
</span><span class="cx"> if ( !$meta_type || !$meta_key || (!$delete_all && ! (int)$object_id) )
</span><span class="cx"> return false;
</span><span class="lines">@@ -122,6 +178,19 @@
</span><span class="cx"> return true;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Retrieve metadata for the specified object.
+ *
+ * @since 2.9.0
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int $object_id ID of the object metadata is for
+ * @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
+ * the specified object.
+ * @param bool $single Optional, default is false. If true, return only the first value of the
+ * specified meta_key. This parameter has no effect if meta_key is not specified.
+ * @return string|array Single metadata value, or array of values
+ */
</ins><span class="cx"> function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
</span><span class="cx"> if ( !$meta_type )
</span><span class="cx"> return false;
</span><span class="lines">@@ -150,6 +219,16 @@
</span><span class="cx"> return array();
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Update the metadata cache for the specified objects.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ *
+ * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
+ * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
+ * @return mixed Metadata cache for the specified objects, or false on failure.
+ */
</ins><span class="cx"> function update_meta_cache($meta_type, $object_ids) {
</span><span class="cx"> if ( empty( $meta_type ) || empty( $object_ids ) )
</span><span class="cx"> return false;
</span><span class="lines">@@ -212,6 +291,15 @@
</span><span class="cx"> return $cache;
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+/**
+ * Retrieve the name of the metadata table for the specified object type.
+ *
+ * @since 2.9.0
+ * @uses $wpdb WordPress database object for queries.
+ *
+ * @param string $meta_type Type of object to get metadata table for (e.g., comment, post, or user)
+ * @return mixed Metadata table name, or false if no metadata table exists
+ */
</ins><span class="cx"> function _get_meta_table($type) {
</span><span class="cx"> global $wpdb;
</span><span class="cx">
</span></span></pre>
</div>
</div>
</body>
</html>