[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   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.
   8   *
   9   * @package WordPress
  10   * @subpackage Meta
  11   * @since 2.9.0
  12   */
  13  
  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   */
  31  function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
  32      if ( !$meta_type || !$meta_key )
  33          return false;
  34  
  35      if ( !$object_id = absint($object_id) )
  36          return false;
  37  
  38      if ( ! $table = _get_meta_table($meta_type) )
  39          return false;
  40  
  41      global $wpdb;
  42  
  43      $column = esc_sql($meta_type . '_id');
  44  
  45      // expected_slashed ($meta_key)
  46      $meta_key = stripslashes($meta_key);
  47  
  48      if ( $unique && $wpdb->get_var( $wpdb->prepare(
  49          "SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
  50          $meta_key, $object_id ) ) )
  51          return false;
  52  
  53      $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
  54  
  55      $wpdb->insert( $table, array(
  56          $column => $object_id,
  57          'meta_key' => $meta_key,
  58          'meta_value' => $meta_value
  59      ) );
  60  
  61      wp_cache_delete($object_id, $meta_type . '_meta');
  62  
  63      do_action( "added_{$meta_type}_meta", $wpdb->insert_id, $object_id, $meta_key, $meta_value );
  64  
  65      return true;
  66  }
  67  
  68  /**
  69   * Update metadata for the specified object.  If no value already exists for the specified object
  70   * ID and metadata key, the metadata will be added.
  71   *
  72   * @since 2.9.0
  73   * @uses $wpdb WordPress database object for queries.
  74   * @uses do_action() Calls 'update_{$meta_type}_meta' before updating metadata with meta_id of
  75   *         metadata entry to update, object ID, meta key, and meta value
  76   * @uses do_action() Calls 'updated_{$meta_type}_meta' after updating metadata with meta_id of
  77   *         updated metadata entry, object ID, meta key, and meta value
  78   *
  79   * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
  80   * @param int $object_id ID of the object metadata is for
  81   * @param string $meta_key Metadata key
  82   * @param string $meta_value Metadata value
  83   * @param string $prev_value Optional.  If specified, only update existing metadata entries with
  84   *         the specified value.  Otherwise, update all entries.
  85   * @return bool True on successful update, false on failure.
  86   */
  87  function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
  88      if ( !$meta_type || !$meta_key )
  89          return false;
  90  
  91      if ( !$object_id = absint($object_id) )
  92          return false;
  93  
  94      if ( ! $table = _get_meta_table($meta_type) )
  95          return false;
  96  
  97      global $wpdb;
  98  
  99      $column = esc_sql($meta_type . '_id');
 100      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 101  
 102      // expected_slashed ($meta_key)
 103      $meta_key = stripslashes($meta_key);
 104  
 105      if ( ! $meta_id = $wpdb->get_var( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) ) )
 106          return add_metadata($meta_type, $object_id, $meta_key, $meta_value);
 107  
 108      $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
 109  
 110      $data  = compact( 'meta_value' );
 111      $where = array( $column => $object_id, 'meta_key' => $meta_key );
 112  
 113      if ( !empty( $prev_value ) ) {
 114          $prev_value = maybe_serialize($prev_value);
 115          $where['meta_value'] = $prev_value;
 116      }
 117  
 118      do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $meta_value );
 119  
 120      $wpdb->update( $table, $data, $where );
 121      wp_cache_delete($object_id, $meta_type . '_meta');
 122  
 123      do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $meta_value );
 124  
 125      return true;
 126  }
 127  
 128  /**
 129   * Delete metadata for the specified object.
 130   *
 131   * @since 2.9.0
 132   * @uses $wpdb WordPress database object for queries.
 133   * @uses do_action() Calls 'deleted_{$meta_type}_meta' after deleting with meta_id of
 134   *         deleted metadata entries, object ID, meta key, and meta value
 135   *
 136   * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 137   * @param int $object_id ID of the object metadata is for
 138   * @param string $meta_key Metadata key
 139   * @param string $meta_value Optional. Metadata value.  If specified, only delete metadata entries
 140   *         with this value.  Otherwise, delete all entries with the specified meta_key.
 141   * @param bool $delete_all Optional, default is false.  If true, delete matching metadata entries
 142   *         for all objects, ignoring the specified object_id.  Otherwise, only delete matching
 143   *         metadata entries for the specified object_id.
 144   * @return bool True on successful delete, false on failure.
 145   */
 146  function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
 147      if ( !$meta_type || !$meta_key )
 148          return false;
 149  
 150      if ( (!$object_id = absint($object_id)) && !$delete_all )
 151          return false;
 152  
 153      if ( ! $table = _get_meta_table($meta_type) )
 154          return false;
 155  
 156      global $wpdb;
 157  
 158      $type_column = esc_sql($meta_type . '_id');
 159      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 160      // expected_slashed ($meta_key)
 161      $meta_key = stripslashes($meta_key);
 162      $meta_value = maybe_serialize( stripslashes_deep($meta_value) );
 163  
 164      $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
 165  
 166      if ( !$delete_all )
 167          $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
 168  
 169      if ( $meta_value )
 170          $query .= $wpdb->prepare(" AND meta_value = %s", $meta_value );
 171  
 172      $meta_ids = $wpdb->get_col( $query );
 173      if ( !count( $meta_ids ) )
 174          return false;
 175  
 176      $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
 177  
 178      $count = $wpdb->query($query);
 179  
 180      if ( !$count )
 181          return false;
 182  
 183      wp_cache_delete($object_id, $meta_type . '_meta');
 184  
 185      do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $meta_value );
 186  
 187      return true;
 188  }
 189  
 190  /**
 191   * Retrieve metadata for the specified object.
 192   *
 193   * @since 2.9.0
 194   *
 195   * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 196   * @param int $object_id ID of the object metadata is for
 197   * @param string $meta_key Optional.  Metadata key.  If not specified, retrieve all metadata for
 198   *         the specified object.
 199   * @param bool $single Optional, default is false.  If true, return only the first value of the
 200   *         specified meta_key.  This parameter has no effect if meta_key is not specified.
 201   * @return string|array Single metadata value, or array of values
 202   */
 203  function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
 204      if ( !$meta_type )
 205          return false;
 206  
 207      if ( !$object_id = absint($object_id) )
 208          return false;
 209  
 210      $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
 211  
 212      if ( !$meta_cache ) {
 213          update_meta_cache($meta_type, $object_id);
 214          $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
 215      }
 216  
 217      if ( ! $meta_key )
 218          return $meta_cache;
 219  
 220      if ( isset($meta_cache[$meta_key]) ) {
 221          if ( $single )
 222              return maybe_unserialize( $meta_cache[$meta_key][0] );
 223          else
 224              return array_map('maybe_unserialize', $meta_cache[$meta_key]);
 225      }
 226  
 227      if ($single)
 228          return '';
 229      else
 230          return array();
 231  }
 232  
 233  /**
 234   * Update the metadata cache for the specified objects.
 235   *
 236   * @since 2.9.0
 237   * @uses $wpdb WordPress database object for queries.
 238   *
 239   * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 240   * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
 241   * @return mixed Metadata cache for the specified objects, or false on failure.
 242   */
 243  function update_meta_cache($meta_type, $object_ids) {
 244      if ( empty( $meta_type ) || empty( $object_ids ) )
 245          return false;
 246  
 247      if ( ! $table = _get_meta_table($meta_type) )
 248          return false;
 249  
 250      $column = esc_sql($meta_type . '_id');
 251  
 252      global $wpdb;
 253  
 254      if ( !is_array($object_ids) ) {
 255          $object_ids = preg_replace('|[^0-9,]|', '', $object_ids);
 256          $object_ids = explode(',', $object_ids);
 257      }
 258  
 259      $object_ids = array_map('intval', $object_ids);
 260  
 261      $cache_key = $meta_type . '_meta';
 262      $ids = array();
 263      foreach ( $object_ids as $id ) {
 264          if ( false === wp_cache_get($id, $cache_key) )
 265              $ids[] = $id;
 266      }
 267  
 268      if ( empty( $ids ) )
 269          return false;
 270  
 271      // Get meta info
 272      $id_list = join(',', $ids);
 273      $cache = array();
 274      $meta_list = $wpdb->get_results( $wpdb->prepare("SELECT $column, meta_key, meta_value FROM $table WHERE $column IN ($id_list)",
 275          $meta_type), ARRAY_A );
 276  
 277      if ( !empty($meta_list) ) {
 278          foreach ( $meta_list as $metarow) {
 279              $mpid = intval($metarow[$column]);
 280              $mkey = $metarow['meta_key'];
 281              $mval = $metarow['meta_value'];
 282  
 283              // Force subkeys to be array type:
 284              if ( !isset($cache[$mpid]) || !is_array($cache[$mpid]) )
 285                  $cache[$mpid] = array();
 286              if ( !isset($cache[$mpid][$mkey]) || !is_array($cache[$mpid][$mkey]) )
 287                  $cache[$mpid][$mkey] = array();
 288  
 289              // Add a value to the current pid/key:
 290              $cache[$mpid][$mkey][] = $mval;
 291          }
 292      }
 293  
 294      foreach ( $ids as $id ) {
 295          if ( ! isset($cache[$id]) )
 296              $cache[$id] = array();
 297      }
 298  
 299      foreach ( array_keys($cache) as $object)
 300          wp_cache_set($object, $cache[$object], $cache_key);
 301  
 302      return $cache;
 303  }
 304  
 305  /**
 306   * Retrieve the name of the metadata table for the specified object type.
 307   *
 308   * @since 2.9.0
 309   * @uses $wpdb WordPress database object for queries.
 310   *
 311   * @param string $meta_type Type of object to get metadata table for (e.g., comment, post, or user)
 312   * @return mixed Metadata table name, or false if no metadata table exists
 313   */
 314  function _get_meta_table($type) {
 315      global $wpdb;
 316  
 317      $table_name = $type . 'meta';
 318  
 319      if ( empty($wpdb->$table_name) )
 320          return false;
 321  
 322      return $wpdb->$table_name;
 323  }
 324  ?>