Wordpress 3.0.6-scripts
[autoinstalls/wordpress.git] / wp-includes / meta.php
index ad6690eea08bae763bc7933686aa7e1fe878195c..fe11d0a8539bf71ea646c0d60cecdd1a65249153 100644 (file)
@@ -1,18 +1,40 @@
 <?php
 /**
- * Meta API
+ * Metadata API
  *
- * Functions for retrieving and manipulating metadata
+ * 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.
  *
  * @package WordPress
  * @subpackage Meta
  * @since 2.9.0
  */
 
+/**
+ * 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.
+ */
 function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
        if ( !$meta_type || !$meta_key )
                return false;
 
+       if ( !$object_id = absint($object_id) )
+               return false;
+
        if ( ! $table = _get_meta_table($meta_type) )
                return false;
 
@@ -28,6 +50,7 @@ function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique =
                $meta_key, $object_id ) ) )
                return false;
 
+       $_meta_value = $meta_value;
        $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
 
        $wpdb->insert( $table, array(
@@ -37,29 +60,65 @@ function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique =
        ) );
 
        wp_cache_delete($object_id, $meta_type . '_meta');
+       // users cache stores usermeta that must be cleared.
+       if ( 'user' == $meta_type )
+               clean_user_cache($object_id);
 
-       do_action( "added_{$meta_type}_meta", $wpdb->insert_id, $object_id, $meta_key, $meta_value );
+       do_action( "added_{$meta_type}_meta", $wpdb->insert_id, $object_id, $meta_key, $_meta_value );
 
        return true;
 }
 
+/**
+ * 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.
+ */
 function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
        if ( !$meta_type || !$meta_key )
                return false;
 
+       if ( !$object_id = absint($object_id) )
+               return false;
+
        if ( ! $table = _get_meta_table($meta_type) )
                return false;
 
        global $wpdb;
 
        $column = esc_sql($meta_type . '_id');
+       $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 
        // expected_slashed ($meta_key)
        $meta_key = stripslashes($meta_key);
 
-       if ( ! $meta_id = $wpdb->get_var( $wpdb->prepare( "SELECT meta_id FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) ) )
+       if ( ! $meta_id = $wpdb->get_var( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) ) )
                return add_metadata($meta_type, $object_id, $meta_key, $meta_value);
 
+       // Compare existing value to new value if no prev value given and the key exists only once.
+       if ( empty($prev_value) ) {
+               $old_value = get_metadata($meta_type, $object_id, $meta_key);
+               if ( count($old_value) == 1 ) {
+                       if ( $old_value[0] === $meta_value )
+                               return false;
+               }
+       }
+
+       $_meta_value = $meta_value;
        $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
 
        $data  = compact( 'meta_value' );
@@ -70,18 +129,42 @@ function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_v
                $where['meta_value'] = $prev_value;
        }
 
-       do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $meta_value );
+       do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 
        $wpdb->update( $table, $data, $where );
        wp_cache_delete($object_id, $meta_type . '_meta');
+       // users cache stores usermeta that must be cleared.
+       if ( 'user' == $meta_type )
+               clean_user_cache($object_id);
 
-       do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $meta_value );
+       do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 
        return true;
 }
 
+/**
+ * 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.
+ */
 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
-       if ( !$meta_type || !$meta_key || (!$delete_all && ! (int)$object_id) )
+       if ( !$meta_type || !$meta_key )
+               return false;
+
+       if ( (!$object_id = absint($object_id)) && !$delete_all )
                return false;
 
        if ( ! $table = _get_meta_table($meta_type) )
@@ -90,11 +173,12 @@ function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $d
        global $wpdb;
 
        $type_column = esc_sql($meta_type . '_id');
+       $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
        // expected_slashed ($meta_key)
        $meta_key = stripslashes($meta_key);
        $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
 
-       $query = $wpdb->prepare( "SELECT meta_id FROM $table WHERE meta_key = %s", $meta_key );
+       $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
 
        if ( !$delete_all )
                $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
@@ -106,7 +190,7 @@ function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $d
        if ( !count( $meta_ids ) )
                return false;
 
-       $query = "DELETE FROM $table WHERE meta_id IN( " . implode( ',', $meta_ids ) . " )";
+       $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
 
        $count = $wpdb->query($query);
 
@@ -114,16 +198,35 @@ function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $d
                return false;
 
        wp_cache_delete($object_id, $meta_type . '_meta');
+       // users cache stores usermeta that must be cleared.
+       if ( 'user' == $meta_type )
+               clean_user_cache($object_id);
 
        do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $meta_value );
 
        return true;
 }
 
+/**
+ * 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
+ */
 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
        if ( !$meta_type )
                return false;
 
+       if ( !$object_id = absint($object_id) )
+               return false;
+
        $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
 
        if ( !$meta_cache ) {
@@ -135,11 +238,10 @@ function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
                return $meta_cache;
 
        if ( isset($meta_cache[$meta_key]) ) {
-               if ( $single ) {
+               if ( $single )
                        return maybe_unserialize( $meta_cache[$meta_key][0] );
-               } else {
+               else
                        return array_map('maybe_unserialize', $meta_cache[$meta_key]);
-               }
        }
 
        if ($single)
@@ -148,6 +250,16 @@ function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
                return array();
 }
 
+/**
+ * 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.
+ */
 function update_meta_cache($meta_type, $object_ids) {
        if ( empty( $meta_type ) || empty( $object_ids ) )
                return false;
@@ -210,6 +322,15 @@ function update_meta_cache($meta_type, $object_ids) {
        return $cache;
 }
 
+/**
+ * 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
+ */
 function _get_meta_table($type) {
        global $wpdb;