wp-includes/meta.php

   1 <?php
   2 /**
   3  * Core 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  */
  12
  13 /**
  14  * Add metadata for the specified object.
  15  *
  16  * @since 2.9.0
  17  *
  18  * @global wpdb $wpdb WordPress database abstraction object.
  19  *
  20  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
  21  * @param int    $object_id  ID of the object metadata is for
  22  * @param string $meta_key   Metadata key
  23  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
  24  * @param bool   $unique     Optional, default is false.
  25  *                           Whether the specified metadata key should be unique for the object.
  26  *                           If true, and the object already has a value for the specified metadata key,
  27  *                           no change will be made.
  28  * @return int|false The meta ID on success, false on failure.
  29  */
  30 function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) {
  31         global $wpdb;
  32
  33         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
  34                 return false;
  35         }
  36
  37         $object_id = absint( $object_id );
  38         if ( ! $object_id ) {
  39                 return false;
  40         }
  41
  42         $table = _get_meta_table( $meta_type );
  43         if ( ! $table ) {
  44                 return false;
  45         }
  46
  47         $column = sanitize_key($meta_type . '_id');
  48
  49         // expected_slashed ($meta_key)
  50         $meta_key = wp_unslash($meta_key);
  51         $meta_value = wp_unslash($meta_value);
  52         $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
  53
  54         /**
  55          * Filter whether to add metadata of a specific type.
  56          *
  57          * The dynamic portion of the hook, `$meta_type`, refers to the meta
  58          * object type (comment, post, or user). Returning a non-null value
  59          * will effectively short-circuit the function.
  60          *
  61          * @since 3.1.0
  62          *
  63          * @param null|bool $check      Whether to allow adding metadata for the given type.
  64          * @param int       $object_id  Object ID.
  65          * @param string    $meta_key   Meta key.
  66          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
  67          * @param bool      $unique     Whether the specified meta key should be unique
  68          *                              for the object. Optional. Default false.
  69          */
  70         $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
  71         if ( null !== $check )
  72                 return $check;
  73
  74         if ( $unique && $wpdb->get_var( $wpdb->prepare(
  75                 "SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
  76                 $meta_key, $object_id ) ) )
  77                 return false;
  78
  79         $_meta_value = $meta_value;
  80         $meta_value = maybe_serialize( $meta_value );
  81
  82         /**
  83          * Fires immediately before meta of a specific type is added.
  84          *
  85          * The dynamic portion of the hook, `$meta_type`, refers to the meta
  86          * object type (comment, post, or user).
  87          *
  88          * @since 3.1.0
  89          *
  90          * @param int    $object_id  Object ID.
  91          * @param string $meta_key   Meta key.
  92          * @param mixed  $meta_value Meta value.
  93          */
  94         do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
  95
  96         $result = $wpdb->insert( $table, array(
  97                 $column => $object_id,
  98                 'meta_key' => $meta_key,
  99                 'meta_value' => $meta_value
 100         ) );
 101
 102         if ( ! $result )
 103                 return false;
 104
 105         $mid = (int) $wpdb->insert_id;
 106
 107         wp_cache_delete($object_id, $meta_type . '_meta');
 108
 109         /**
 110          * Fires immediately after meta of a specific type is added.
 111          *
 112          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 113          * object type (comment, post, or user).
 114          *
 115          * @since 2.9.0
 116          *
 117          * @param int    $mid        The meta ID after successful update.
 118          * @param int    $object_id  Object ID.
 119          * @param string $meta_key   Meta key.
 120          * @param mixed  $meta_value Meta value.
 121          */
 122         do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
 123
 124         return $mid;
 125 }
 126
 127 /**
 128  * Update metadata for the specified object. If no value already exists for the specified object
 129  * ID and metadata key, the metadata will be added.
 130  *
 131  * @since 2.9.0
 132  *
 133  * @global wpdb $wpdb WordPress database abstraction object.
 134  *
 135  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
 136  * @param int    $object_id  ID of the object metadata is for
 137  * @param string $meta_key   Metadata key
 138  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
 139  * @param mixed  $prev_value Optional. If specified, only update existing metadata entries with
 140  *                                   the specified value. Otherwise, update all entries.
 141  * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
 142  */
 143 function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') {
 144         global $wpdb;
 145
 146         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
 147                 return false;
 148         }
 149
 150         $object_id = absint( $object_id );
 151         if ( ! $object_id ) {
 152                 return false;
 153         }
 154
 155         $table = _get_meta_table( $meta_type );
 156         if ( ! $table ) {
 157                 return false;
 158         }
 159
 160         $column = sanitize_key($meta_type . '_id');
 161         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 162
 163         // expected_slashed ($meta_key)
 164         $meta_key = wp_unslash($meta_key);
 165         $passed_value = $meta_value;
 166         $meta_value = wp_unslash($meta_value);
 167         $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
 168
 169         /**
 170          * Filter whether to update metadata of a specific type.
 171          *
 172          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 173          * object type (comment, post, or user). Returning a non-null value
 174          * will effectively short-circuit the function.
 175          *
 176          * @since 3.1.0
 177          *
 178          * @param null|bool $check      Whether to allow updating metadata for the given type.
 179          * @param int       $object_id  Object ID.
 180          * @param string    $meta_key   Meta key.
 181          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
 182          * @param mixed     $prev_value Optional. If specified, only update existing
 183          *                              metadata entries with the specified value.
 184          *                              Otherwise, update all entries.
 185          */
 186         $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
 187         if ( null !== $check )
 188                 return (bool) $check;
 189
 190         // Compare existing value to new value if no prev value given and the key exists only once.
 191         if ( empty($prev_value) ) {
 192                 $old_value = get_metadata($meta_type, $object_id, $meta_key);
 193                 if ( count($old_value) == 1 ) {
 194                         if ( $old_value[0] === $meta_value )
 195                                 return false;
 196                 }
 197         }
 198
 199         $meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) );
 200         if ( empty( $meta_ids ) ) {
 201                 return add_metadata($meta_type, $object_id, $meta_key, $passed_value);
 202         }
 203
 204         $_meta_value = $meta_value;
 205         $meta_value = maybe_serialize( $meta_value );
 206
 207         $data  = compact( 'meta_value' );
 208         $where = array( $column => $object_id, 'meta_key' => $meta_key );
 209
 210         if ( !empty( $prev_value ) ) {
 211                 $prev_value = maybe_serialize($prev_value);
 212                 $where['meta_value'] = $prev_value;
 213         }
 214
 215         foreach ( $meta_ids as $meta_id ) {
 216                 /**
 217                  * Fires immediately before updating metadata of a specific type.
 218                  *
 219                  * The dynamic portion of the hook, `$meta_type`, refers to the meta
 220                  * object type (comment, post, or user).
 221                  *
 222                  * @since 2.9.0
 223                  *
 224                  * @param int    $meta_id    ID of the metadata entry to update.
 225                  * @param int    $object_id  Object ID.
 226                  * @param string $meta_key   Meta key.
 227                  * @param mixed  $meta_value Meta value.
 228                  */
 229                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 230         }
 231
 232         if ( 'post' == $meta_type ) {
 233                 foreach ( $meta_ids as $meta_id ) {
 234                         /**
 235                          * Fires immediately before updating a post's metadata.
 236                          *
 237                          * @since 2.9.0
 238                          *
 239                          * @param int    $meta_id    ID of metadata entry to update.
 240                          * @param int    $object_id  Object ID.
 241                          * @param string $meta_key   Meta key.
 242                          * @param mixed  $meta_value Meta value.
 243                          */
 244                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 245                 }
 246         }
 247
 248         $result = $wpdb->update( $table, $data, $where );
 249         if ( ! $result )
 250                 return false;
 251
 252         wp_cache_delete($object_id, $meta_type . '_meta');
 253
 254         foreach ( $meta_ids as $meta_id ) {
 255                 /**
 256                  * Fires immediately after updating metadata of a specific type.
 257                  *
 258                  * The dynamic portion of the hook, `$meta_type`, refers to the meta
 259                  * object type (comment, post, or user).
 260                  *
 261                  * @since 2.9.0
 262                  *
 263                  * @param int    $meta_id    ID of updated metadata entry.
 264                  * @param int    $object_id  Object ID.
 265                  * @param string $meta_key   Meta key.
 266                  * @param mixed  $meta_value Meta value.
 267                  */
 268                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 269         }
 270
 271         if ( 'post' == $meta_type ) {
 272                 foreach ( $meta_ids as $meta_id ) {
 273                         /**
 274                          * Fires immediately after updating a post's metadata.
 275                          *
 276                          * @since 2.9.0
 277                          *
 278                          * @param int    $meta_id    ID of updated metadata entry.
 279                          * @param int    $object_id  Object ID.
 280                          * @param string $meta_key   Meta key.
 281                          * @param mixed  $meta_value Meta value.
 282                          */
 283                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 284                 }
 285         }
 286
 287         return true;
 288 }
 289
 290 /**
 291  * Delete metadata for the specified object.
 292  *
 293  * @since 2.9.0
 294  *
 295  * @global wpdb $wpdb WordPress database abstraction object.
 296  *
 297  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
 298  * @param int    $object_id  ID of the object metadata is for
 299  * @param string $meta_key   Metadata key
 300  * @param mixed  $meta_value Optional. Metadata value. Must be serializable if non-scalar. If specified, only delete
 301  *                           metadata entries with this value. Otherwise, delete all entries with the specified meta_key.
 302  *                           Pass `null, `false`, or an empty string to skip this check. (For backward compatibility,
 303  *                           it is not possible to pass an empty string to delete those entries with an empty string
 304  *                           for a value.)
 305  * @param bool   $delete_all Optional, default is false. If true, delete matching metadata entries for all objects,
 306  *                           ignoring the specified object_id. Otherwise, only delete matching metadata entries for
 307  *                           the specified object_id.
 308  * @return bool True on successful delete, false on failure.
 309  */
 310 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
 311         global $wpdb;
 312
 313         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
 314                 return false;
 315         }
 316
 317         $object_id = absint( $object_id );
 318         if ( ! $object_id && ! $delete_all ) {
 319                 return false;
 320         }
 321
 322         $table = _get_meta_table( $meta_type );
 323         if ( ! $table ) {
 324                 return false;
 325         }
 326
 327         $type_column = sanitize_key($meta_type . '_id');
 328         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 329         // expected_slashed ($meta_key)
 330         $meta_key = wp_unslash($meta_key);
 331         $meta_value = wp_unslash($meta_value);
 332
 333         /**
 334          * Filter whether to delete metadata of a specific type.
 335          *
 336          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 337          * object type (comment, post, or user). Returning a non-null value
 338          * will effectively short-circuit the function.
 339          *
 340          * @since 3.1.0
 341          *
 342          * @param null|bool $delete     Whether to allow metadata deletion of the given type.
 343          * @param int       $object_id  Object ID.
 344          * @param string    $meta_key   Meta key.
 345          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
 346          * @param bool      $delete_all Whether to delete the matching metadata entries
 347          *                              for all objects, ignoring the specified $object_id.
 348          *                              Default false.
 349          */
 350         $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
 351         if ( null !== $check )
 352                 return (bool) $check;
 353
 354         $_meta_value = $meta_value;
 355         $meta_value = maybe_serialize( $meta_value );
 356
 357         $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
 358
 359         if ( !$delete_all )
 360                 $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
 361
 362         if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value )
 363                 $query .= $wpdb->prepare(" AND meta_value = %s", $meta_value );
 364
 365         $meta_ids = $wpdb->get_col( $query );
 366         if ( !count( $meta_ids ) )
 367                 return false;
 368
 369         if ( $delete_all )
 370                 $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
 371
 372         /**
 373          * Fires immediately before deleting metadata of a specific type.
 374          *
 375          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 376          * object type (comment, post, or user).
 377          *
 378          * @since 3.1.0
 379          *
 380          * @param array  $meta_ids   An array of metadata entry IDs to delete.
 381          * @param int    $object_id  Object ID.
 382          * @param string $meta_key   Meta key.
 383          * @param mixed  $meta_value Meta value.
 384          */
 385         do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 386
 387         // Old-style action.
 388         if ( 'post' == $meta_type ) {
 389                 /**
 390                  * Fires immediately before deleting metadata for a post.
 391                  *
 392                  * @since 2.9.0
 393                  *
 394                  * @param array $meta_ids An array of post metadata entry IDs to delete.
 395                  */
 396                 do_action( 'delete_postmeta', $meta_ids );
 397         }
 398
 399         $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
 400
 401         $count = $wpdb->query($query);
 402
 403         if ( !$count )
 404                 return false;
 405
 406         if ( $delete_all ) {
 407                 foreach ( (array) $object_ids as $o_id ) {
 408                         wp_cache_delete($o_id, $meta_type . '_meta');
 409                 }
 410         } else {
 411                 wp_cache_delete($object_id, $meta_type . '_meta');
 412         }
 413
 414         /**
 415          * Fires immediately after deleting metadata of a specific type.
 416          *
 417          * The dynamic portion of the hook name, `$meta_type`, refers to the meta
 418          * object type (comment, post, or user).
 419          *
 420          * @since 2.9.0
 421          *
 422          * @param array  $meta_ids   An array of deleted metadata entry IDs.
 423          * @param int    $object_id  Object ID.
 424          * @param string $meta_key   Meta key.
 425          * @param mixed  $meta_value Meta value.
 426          */
 427         do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 428
 429         // Old-style action.
 430         if ( 'post' == $meta_type ) {
 431                 /**
 432                  * Fires immediately after deleting metadata for a post.
 433                  *
 434                  * @since 2.9.0
 435                  *
 436                  * @param array $meta_ids An array of deleted post metadata entry IDs.
 437                  */
 438                 do_action( 'deleted_postmeta', $meta_ids );
 439         }
 440
 441         return true;
 442 }
 443
 444 /**
 445  * Retrieve metadata for the specified object.
 446  *
 447  * @since 2.9.0
 448  *
 449  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 450  * @param int    $object_id ID of the object metadata is for
 451  * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
 452  *                                  the specified object.
 453  * @param bool   $single    Optional, default is false.
 454  *                          If true, return only the first value of the specified meta_key.
 455  *                          This parameter has no effect if meta_key is not specified.
 456  * @return mixed Single metadata value, or array of values
 457  */
 458 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
 459         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 460                 return false;
 461         }
 462
 463         $object_id = absint( $object_id );
 464         if ( ! $object_id ) {
 465                 return false;
 466         }
 467
 468         /**
 469          * Filter whether to retrieve metadata of a specific type.
 470          *
 471          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 472          * object type (comment, post, or user). Returning a non-null value
 473          * will effectively short-circuit the function.
 474          *
 475          * @since 3.1.0
 476          *
 477          * @param null|array|string $value     The value get_metadata() should return - a single metadata value,
 478          *                                     or an array of values.
 479          * @param int               $object_id Object ID.
 480          * @param string            $meta_key  Meta key.
 481          * @param bool              $single    Whether to return only the first value of the specified $meta_key.
 482          */
 483         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
 484         if ( null !== $check ) {
 485                 if ( $single && is_array( $check ) )
 486                         return $check[0];
 487                 else
 488                         return $check;
 489         }
 490
 491         $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
 492
 493         if ( !$meta_cache ) {
 494                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 495                 $meta_cache = $meta_cache[$object_id];
 496         }
 497
 498         if ( ! $meta_key ) {
 499                 return $meta_cache;
 500         }
 501
 502         if ( isset($meta_cache[$meta_key]) ) {
 503                 if ( $single )
 504                         return maybe_unserialize( $meta_cache[$meta_key][0] );
 505                 else
 506                         return array_map('maybe_unserialize', $meta_cache[$meta_key]);
 507         }
 508
 509         if ($single)
 510                 return '';
 511         else
 512                 return array();
 513 }
 514
 515 /**
 516  * Determine if a meta key is set for a given object
 517  *
 518  * @since 3.3.0
 519  *
 520  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 521  * @param int    $object_id ID of the object metadata is for
 522  * @param string $meta_key  Metadata key.
 523  * @return bool True of the key is set, false if not.
 524  */
 525 function metadata_exists( $meta_type, $object_id, $meta_key ) {
 526         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 527                 return false;
 528         }
 529
 530         $object_id = absint( $object_id );
 531         if ( ! $object_id ) {
 532                 return false;
 533         }
 534
 535         /** This filter is documented in wp-includes/meta.php */
 536         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
 537         if ( null !== $check )
 538                 return (bool) $check;
 539
 540         $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
 541
 542         if ( !$meta_cache ) {
 543                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 544                 $meta_cache = $meta_cache[$object_id];
 545         }
 546
 547         if ( isset( $meta_cache[ $meta_key ] ) )
 548                 return true;
 549
 550         return false;
 551 }
 552
 553 /**
 554  * Get meta data by meta ID
 555  *
 556  * @since 3.3.0
 557  *
 558  * @global wpdb $wpdb WordPress database abstraction object.
 559  *
 560  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 561  * @param int    $meta_id   ID for a specific meta row
 562  * @return object|false Meta object or false.
 563  */
 564 function get_metadata_by_mid( $meta_type, $meta_id ) {
 565         global $wpdb;
 566
 567         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 568                 return false;
 569         }
 570
 571         $meta_id = absint( $meta_id );
 572         if ( ! $meta_id ) {
 573                 return false;
 574         }
 575
 576         $table = _get_meta_table( $meta_type );
 577         if ( ! $table ) {
 578                 return false;
 579         }
 580
 581         $id_column = ( 'user' == $meta_type ) ? 'umeta_id' : 'meta_id';
 582
 583         $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
 584
 585         if ( empty( $meta ) )
 586                 return false;
 587
 588         if ( isset( $meta->meta_value ) )
 589                 $meta->meta_value = maybe_unserialize( $meta->meta_value );
 590
 591         return $meta;
 592 }
 593
 594 /**
 595  * Update meta data by meta ID
 596  *
 597  * @since 3.3.0
 598  *
 599  * @global wpdb $wpdb WordPress database abstraction object.
 600  *
 601  * @param string $meta_type  Type of object metadata is for (e.g., comment, post, or user)
 602  * @param int    $meta_id    ID for a specific meta row
 603  * @param string $meta_value Metadata value
 604  * @param string $meta_key   Optional, you can provide a meta key to update it
 605  * @return bool True on successful update, false on failure.
 606  */
 607 function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
 608         global $wpdb;
 609
 610         // Make sure everything is valid.
 611         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 612                 return false;
 613         }
 614
 615         $meta_id = absint( $meta_id );
 616         if ( ! $meta_id ) {
 617                 return false;
 618         }
 619
 620         $table = _get_meta_table( $meta_type );
 621         if ( ! $table ) {
 622                 return false;
 623         }
 624
 625         $column = sanitize_key($meta_type . '_id');
 626         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 627
 628         // Fetch the meta and go on if it's found.
 629         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
 630                 $original_key = $meta->meta_key;
 631                 $object_id = $meta->{$column};
 632
 633                 // If a new meta_key (last parameter) was specified, change the meta key,
 634                 // otherwise use the original key in the update statement.
 635                 if ( false === $meta_key ) {
 636                         $meta_key = $original_key;
 637                 } elseif ( ! is_string( $meta_key ) ) {
 638                         return false;
 639                 }
 640
 641                 // Sanitize the meta
 642                 $_meta_value = $meta_value;
 643                 $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
 644                 $meta_value = maybe_serialize( $meta_value );
 645
 646                 // Format the data query arguments.
 647                 $data = array(
 648                         'meta_key' => $meta_key,
 649                         'meta_value' => $meta_value
 650                 );
 651
 652                 // Format the where query arguments.
 653                 $where = array();
 654                 $where[$id_column] = $meta_id;
 655
 656                 /** This action is documented in wp-includes/meta.php */
 657                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 658
 659                 if ( 'post' == $meta_type ) {
 660                         /** This action is documented in wp-includes/meta.php */
 661                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 662                 }
 663
 664                 // Run the update query, all fields in $data are %s, $where is a %d.
 665                 $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
 666                 if ( ! $result )
 667                         return false;
 668
 669                 // Clear the caches.
 670                 wp_cache_delete($object_id, $meta_type . '_meta');
 671
 672                 /** This action is documented in wp-includes/meta.php */
 673                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 674
 675                 if ( 'post' == $meta_type ) {
 676                         /** This action is documented in wp-includes/meta.php */
 677                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 678                 }
 679
 680                 return true;
 681         }
 682
 683         // And if the meta was not found.
 684         return false;
 685 }
 686
 687 /**
 688  * Delete meta data by meta ID
 689  *
 690  * @since 3.3.0
 691  *
 692  * @global wpdb $wpdb WordPress database abstraction object.
 693  *
 694  * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 695  * @param int    $meta_id   ID for a specific meta row
 696  * @return bool True on successful delete, false on failure.
 697  */
 698 function delete_metadata_by_mid( $meta_type, $meta_id ) {
 699         global $wpdb;
 700
 701         // Make sure everything is valid.
 702         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 703                 return false;
 704         }
 705
 706         $meta_id = absint( $meta_id );
 707         if ( ! $meta_id ) {
 708                 return false;
 709         }
 710
 711         $table = _get_meta_table( $meta_type );
 712         if ( ! $table ) {
 713                 return false;
 714         }
 715
 716         // object and id columns
 717         $column = sanitize_key($meta_type . '_id');
 718         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 719
 720         // Fetch the meta and go on if it's found.
 721         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
 722                 $object_id = $meta->{$column};
 723
 724                 /** This action is documented in wp-includes/meta.php */
 725                 do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 726
 727                 // Old-style action.
 728                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 729                         /**
 730                          * Fires immediately before deleting post or comment metadata of a specific type.
 731                          *
 732                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 733                          * object type (post or comment).
 734                          *
 735                          * @since 3.4.0
 736                          *
 737                          * @param int $meta_id ID of the metadata entry to delete.
 738                          */
 739                         do_action( "delete_{$meta_type}meta", $meta_id );
 740                 }
 741
 742                 // Run the query, will return true if deleted, false otherwise
 743                 $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
 744
 745                 // Clear the caches.
 746                 wp_cache_delete($object_id, $meta_type . '_meta');
 747
 748                 /** This action is documented in wp-includes/meta.php */
 749                 do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 750
 751                 // Old-style action.
 752                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 753                         /**
 754                          * Fires immediately after deleting post or comment metadata of a specific type.
 755                          *
 756                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 757                          * object type (post or comment).
 758                          *
 759                          * @since 3.4.0
 760                          *
 761                          * @param int $meta_ids Deleted metadata entry ID.
 762                          */
 763                         do_action( "deleted_{$meta_type}meta", $meta_id );
 764                 }
 765
 766                 return $result;
 767
 768         }
 769
 770         // Meta id was not found.
 771         return false;
 772 }
 773
 774 /**
 775  * Update the metadata cache for the specified objects.
 776  *
 777  * @since 2.9.0
 778  *
 779  * @global wpdb $wpdb WordPress database abstraction object.
 780  *
 781  * @param string    $meta_type  Type of object metadata is for (e.g., comment, post, or user)
 782  * @param int|array $object_ids Array or comma delimited list of object IDs to update cache for
 783  * @return array|false Metadata cache for the specified objects, or false on failure.
 784  */
 785 function update_meta_cache($meta_type, $object_ids) {
 786         global $wpdb;
 787
 788         if ( ! $meta_type || ! $object_ids ) {
 789                 return false;
 790         }
 791
 792         $table = _get_meta_table( $meta_type );
 793         if ( ! $table ) {
 794                 return false;
 795         }
 796
 797         $column = sanitize_key($meta_type . '_id');
 798
 799         if ( !is_array($object_ids) ) {
 800                 $object_ids = preg_replace('|[^0-9,]|', '', $object_ids);
 801                 $object_ids = explode(',', $object_ids);
 802         }
 803
 804         $object_ids = array_map('intval', $object_ids);
 805
 806         $cache_key = $meta_type . '_meta';
 807         $ids = array();
 808         $cache = array();
 809         foreach ( $object_ids as $id ) {
 810                 $cached_object = wp_cache_get( $id, $cache_key );
 811                 if ( false === $cached_object )
 812                         $ids[] = $id;
 813                 else
 814                         $cache[$id] = $cached_object;
 815         }
 816
 817         if ( empty( $ids ) )
 818                 return $cache;
 819
 820         // Get meta info
 821         $id_list = join( ',', $ids );
 822         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 823         $meta_list = $wpdb->get_results( "SELECT $column, meta_key, meta_value FROM $table WHERE $column IN ($id_list) ORDER BY $id_column ASC", ARRAY_A );
 824
 825         if ( !empty($meta_list) ) {
 826                 foreach ( $meta_list as $metarow) {
 827                         $mpid = intval($metarow[$column]);
 828                         $mkey = $metarow['meta_key'];
 829                         $mval = $metarow['meta_value'];
 830
 831                         // Force subkeys to be array type:
 832                         if ( !isset($cache[$mpid]) || !is_array($cache[$mpid]) )
 833                                 $cache[$mpid] = array();
 834                         if ( !isset($cache[$mpid][$mkey]) || !is_array($cache[$mpid][$mkey]) )
 835                                 $cache[$mpid][$mkey] = array();
 836
 837                         // Add a value to the current pid/key:
 838                         $cache[$mpid][$mkey][] = $mval;
 839                 }
 840         }
 841
 842         foreach ( $ids as $id ) {
 843                 if ( ! isset($cache[$id]) )
 844                         $cache[$id] = array();
 845                 wp_cache_add( $id, $cache[$id], $cache_key );
 846         }
 847
 848         return $cache;
 849 }
 850
 851 /**
 852  * Given a meta query, generates SQL clauses to be appended to a main query.
 853  *
 854  * @since 3.2.0
 855  *
 856  * @see WP_Meta_Query
 857  *
 858  * @param array $meta_query         A meta query.
 859  * @param string $type              Type of meta.
 860  * @param string $primary_table     Primary database table name.
 861  * @param string $primary_id_column Primary ID column name.
 862  * @param object $context           Optional. The main query object
 863  * @return array Associative array of `JOIN` and `WHERE` SQL.
 864  */
 865 function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
 866         $meta_query_obj = new WP_Meta_Query( $meta_query );
 867         return $meta_query_obj->get_sql( $type, $primary_table, $primary_id_column, $context );
 868 }
 869
 870 /**
 871  * Retrieve the name of the metadata table for the specified object type.
 872  *
 873  * @since 2.9.0
 874  *
 875  * @global wpdb $wpdb WordPress database abstraction object.
 876  *
 877  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
 878  * @return string|false Metadata table name, or false if no metadata table exists
 879  */
 880 function _get_meta_table($type) {
 881         global $wpdb;
 882
 883         $table_name = $type . 'meta';
 884
 885         if ( empty($wpdb->$table_name) )
 886                 return false;
 887
 888         return $wpdb->$table_name;
 889 }
 890
 891 /**
 892  * Determine whether a meta key is protected.
 893  *
 894  * @since 3.1.3
 895  *
 896  * @param string      $meta_key Meta key
 897  * @param string|null $meta_type
 898  * @return bool True if the key is protected, false otherwise.
 899  */
 900 function is_protected_meta( $meta_key, $meta_type = null ) {
 901         $protected = ( '_' == $meta_key[0] );
 902
 903         /**
 904          * Filter whether a meta key is protected.
 905          *
 906          * @since 3.2.0
 907          *
 908          * @param bool   $protected Whether the key is protected. Default false.
 909          * @param string $meta_key  Meta key.
 910          * @param string $meta_type Meta type.
 911          */
 912         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
 913 }
 914
 915 /**
 916  * Sanitize meta value.
 917  *
 918  * @since 3.1.3
 919  *
 920  * @param string $meta_key   Meta key
 921  * @param mixed  $meta_value Meta value to sanitize
 922  * @param string $meta_type  Type of meta
 923  * @return mixed Sanitized $meta_value
 924  */
 925 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
 926
 927         /**
 928          * Filter the sanitization of a specific meta key of a specific meta type.
 929          *
 930          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
 931          * refer to the metadata object type (comment, post, or user) and the meta
 932          * key value,
 933          * respectively.
 934          *
 935          * @since 3.3.0
 936          *
 937          * @param mixed  $meta_value Meta value to sanitize.
 938          * @param string $meta_key   Meta key.
 939          * @param string $meta_type  Meta type.
 940          */
 941         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
 942 }
 943
 944 /**
 945  * Register meta key
 946  *
 947  * @since 3.3.0
 948  *
 949  * @param string       $meta_type         Type of meta
 950  * @param string       $meta_key          Meta key
 951  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
 952  * @param string|array $auth_callback     Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.
 953  */
 954 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
 955         if ( is_callable( $sanitize_callback ) )
 956                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
 957
 958         if ( empty( $auth_callback ) ) {
 959                 if ( is_protected_meta( $meta_key, $meta_type ) )
 960                         $auth_callback = '__return_false';
 961                 else
 962                         $auth_callback = '__return_true';
 963         }
 964
 965         if ( is_callable( $auth_callback ) )
 966                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
 967 }