wp-includes/meta.php

   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  *
  19  * @global wpdb $wpdb WordPress database abstraction object.
  20  *
  21  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
  22  * @param int $object_id ID of the object metadata is for
  23  * @param string $meta_key Metadata key
  24  * @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
  25  * @param bool $unique Optional, default is false. Whether the specified metadata key should be
  26  *              unique for the object. If true, and the object already has a value for the specified
  27  *              metadata key, no change will be made
  28  * @return int|bool 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 metadata entries
 301  *              with this value. Otherwise, delete all entries with the specified meta_key.
 302  * @param bool $delete_all Optional, default is false. If true, delete matching metadata entries
 303  *              for all objects, ignoring the specified object_id. Otherwise, only delete matching
 304  *              metadata entries for the specified object_id.
 305  * @return bool True on successful delete, false on failure.
 306  */
 307 function delete_metadata($meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false) {
 308         global $wpdb;
 309
 310         if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
 311                 return false;
 312         }
 313
 314         $object_id = absint( $object_id );
 315         if ( ! $object_id && ! $delete_all ) {
 316                 return false;
 317         }
 318
 319         $table = _get_meta_table( $meta_type );
 320         if ( ! $table ) {
 321                 return false;
 322         }
 323
 324         $type_column = sanitize_key($meta_type . '_id');
 325         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 326         // expected_slashed ($meta_key)
 327         $meta_key = wp_unslash($meta_key);
 328         $meta_value = wp_unslash($meta_value);
 329
 330         /**
 331          * Filter whether to delete metadata of a specific type.
 332          *
 333          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 334          * object type (comment, post, or user). Returning a non-null value
 335          * will effectively short-circuit the function.
 336          *
 337          * @since 3.1.0
 338          *
 339          * @param null|bool $delete     Whether to allow metadata deletion of the given type.
 340          * @param int       $object_id  Object ID.
 341          * @param string    $meta_key   Meta key.
 342          * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
 343          * @param bool      $delete_all Whether to delete the matching metadata entries
 344          *                              for all objects, ignoring the specified $object_id.
 345          *                              Default false.
 346          */
 347         $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
 348         if ( null !== $check )
 349                 return (bool) $check;
 350
 351         $_meta_value = $meta_value;
 352         $meta_value = maybe_serialize( $meta_value );
 353
 354         $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
 355
 356         if ( !$delete_all )
 357                 $query .= $wpdb->prepare(" AND $type_column = %d", $object_id );
 358
 359         if ( $meta_value )
 360                 $query .= $wpdb->prepare(" AND meta_value = %s", $meta_value );
 361
 362         $meta_ids = $wpdb->get_col( $query );
 363         if ( !count( $meta_ids ) )
 364                 return false;
 365
 366         if ( $delete_all )
 367                 $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
 368
 369         /**
 370          * Fires immediately before deleting metadata of a specific type.
 371          *
 372          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 373          * object type (comment, post, or user).
 374          *
 375          * @since 3.1.0
 376          *
 377          * @param array  $meta_ids   An array of metadata entry IDs to delete.
 378          * @param int    $object_id  Object ID.
 379          * @param string $meta_key   Meta key.
 380          * @param mixed  $meta_value Meta value.
 381          */
 382         do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 383
 384         // Old-style action.
 385         if ( 'post' == $meta_type ) {
 386                 /**
 387                  * Fires immediately before deleting metadata for a post.
 388                  *
 389                  * @since 2.9.0
 390                  *
 391                  * @param array $meta_ids An array of post metadata entry IDs to delete.
 392                  */
 393                 do_action( 'delete_postmeta', $meta_ids );
 394         }
 395
 396         $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . " )";
 397
 398         $count = $wpdb->query($query);
 399
 400         if ( !$count )
 401                 return false;
 402
 403         if ( $delete_all ) {
 404                 foreach ( (array) $object_ids as $o_id ) {
 405                         wp_cache_delete($o_id, $meta_type . '_meta');
 406                 }
 407         } else {
 408                 wp_cache_delete($object_id, $meta_type . '_meta');
 409         }
 410
 411         /**
 412          * Fires immediately after deleting metadata of a specific type.
 413          *
 414          * The dynamic portion of the hook name, `$meta_type`, refers to the meta
 415          * object type (comment, post, or user).
 416          *
 417          * @since 2.9.0
 418          *
 419          * @param array  $meta_ids   An array of deleted metadata entry IDs.
 420          * @param int    $object_id  Object ID.
 421          * @param string $meta_key   Meta key.
 422          * @param mixed  $meta_value Meta value.
 423          */
 424         do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 425
 426         // Old-style action.
 427         if ( 'post' == $meta_type ) {
 428                 /**
 429                  * Fires immediately after deleting metadata for a post.
 430                  *
 431                  * @since 2.9.0
 432                  *
 433                  * @param array $meta_ids An array of deleted post metadata entry IDs.
 434                  */
 435                 do_action( 'deleted_postmeta', $meta_ids );
 436         }
 437
 438         return true;
 439 }
 440
 441 /**
 442  * Retrieve metadata for the specified object.
 443  *
 444  * @since 2.9.0
 445  *
 446  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 447  * @param int $object_id ID of the object metadata is for
 448  * @param string $meta_key Optional. Metadata key. If not specified, retrieve all metadata for
 449  *              the specified object.
 450  * @param bool $single Optional, default is false. If true, return only the first value of the
 451  *              specified meta_key. This parameter has no effect if meta_key is not specified.
 452  * @return string|array Single metadata value, or array of values
 453  */
 454 function get_metadata($meta_type, $object_id, $meta_key = '', $single = false) {
 455         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 456                 return false;
 457         }
 458
 459         $object_id = absint( $object_id );
 460         if ( ! $object_id ) {
 461                 return false;
 462         }
 463
 464         /**
 465          * Filter whether to retrieve metadata of a specific type.
 466          *
 467          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 468          * object type (comment, post, or user). Returning a non-null value
 469          * will effectively short-circuit the function.
 470          *
 471          * @since 3.1.0
 472          *
 473          * @param null|array|string $value     The value get_metadata() should
 474          *                                     return - a single metadata value,
 475          *                                     or an array of values.
 476          * @param int               $object_id Object ID.
 477          * @param string            $meta_key  Meta key.
 478          * @param string|array      $single    Meta value, or an array of values.
 479          */
 480         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
 481         if ( null !== $check ) {
 482                 if ( $single && is_array( $check ) )
 483                         return $check[0];
 484                 else
 485                         return $check;
 486         }
 487
 488         $meta_cache = wp_cache_get($object_id, $meta_type . '_meta');
 489
 490         if ( !$meta_cache ) {
 491                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 492                 $meta_cache = $meta_cache[$object_id];
 493         }
 494
 495         if ( ! $meta_key ) {
 496                 return $meta_cache;
 497         }
 498
 499         if ( isset($meta_cache[$meta_key]) ) {
 500                 if ( $single )
 501                         return maybe_unserialize( $meta_cache[$meta_key][0] );
 502                 else
 503                         return array_map('maybe_unserialize', $meta_cache[$meta_key]);
 504         }
 505
 506         if ($single)
 507                 return '';
 508         else
 509                 return array();
 510 }
 511
 512 /**
 513  * Determine if a meta key is set for a given object
 514  *
 515  * @since 3.3.0
 516  *
 517  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 518  * @param int $object_id ID of the object metadata is for
 519  * @param string $meta_key Metadata key.
 520  * @return boolean true of the key is set, false if not.
 521  */
 522 function metadata_exists( $meta_type, $object_id, $meta_key ) {
 523         if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 524                 return false;
 525         }
 526
 527         $object_id = absint( $object_id );
 528         if ( ! $object_id ) {
 529                 return false;
 530         }
 531
 532         /** This filter is documented in wp-includes/meta.php */
 533         $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
 534         if ( null !== $check )
 535                 return (bool) $check;
 536
 537         $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
 538
 539         if ( !$meta_cache ) {
 540                 $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 541                 $meta_cache = $meta_cache[$object_id];
 542         }
 543
 544         if ( isset( $meta_cache[ $meta_key ] ) )
 545                 return true;
 546
 547         return false;
 548 }
 549
 550 /**
 551  * Get meta data by meta ID
 552  *
 553  * @since 3.3.0
 554  *
 555  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 556  * @param int $meta_id ID for a specific meta row
 557  * @return object Meta object or false.
 558  */
 559 function get_metadata_by_mid( $meta_type, $meta_id ) {
 560         global $wpdb;
 561
 562         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 563                 return false;
 564         }
 565
 566         $meta_id = absint( $meta_id );
 567         if ( ! $meta_id ) {
 568                 return false;
 569         }
 570
 571         $table = _get_meta_table( $meta_type );
 572         if ( ! $table ) {
 573                 return false;
 574         }
 575
 576         $id_column = ( 'user' == $meta_type ) ? 'umeta_id' : 'meta_id';
 577
 578         $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
 579
 580         if ( empty( $meta ) )
 581                 return false;
 582
 583         if ( isset( $meta->meta_value ) )
 584                 $meta->meta_value = maybe_unserialize( $meta->meta_value );
 585
 586         return $meta;
 587 }
 588
 589 /**
 590  * Update meta data by meta ID
 591  *
 592  * @since 3.3.0
 593  *
 594  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 595  * @param int $meta_id ID for a specific meta row
 596  * @param string $meta_value Metadata value
 597  * @param string $meta_key Optional, you can provide a meta key to update it
 598  * @return bool True on successful update, false on failure.
 599  */
 600 function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
 601         global $wpdb;
 602
 603         // Make sure everything is valid.
 604         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 605                 return false;
 606         }
 607
 608         $meta_id = absint( $meta_id );
 609         if ( ! $meta_id ) {
 610                 return false;
 611         }
 612
 613         $table = _get_meta_table( $meta_type );
 614         if ( ! $table ) {
 615                 return false;
 616         }
 617
 618         $column = sanitize_key($meta_type . '_id');
 619         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 620
 621         // Fetch the meta and go on if it's found.
 622         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
 623                 $original_key = $meta->meta_key;
 624                 $object_id = $meta->{$column};
 625
 626                 // If a new meta_key (last parameter) was specified, change the meta key,
 627                 // otherwise use the original key in the update statement.
 628                 if ( false === $meta_key ) {
 629                         $meta_key = $original_key;
 630                 } elseif ( ! is_string( $meta_key ) ) {
 631                         return false;
 632                 }
 633
 634                 // Sanitize the meta
 635                 $_meta_value = $meta_value;
 636                 $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type );
 637                 $meta_value = maybe_serialize( $meta_value );
 638
 639                 // Format the data query arguments.
 640                 $data = array(
 641                         'meta_key' => $meta_key,
 642                         'meta_value' => $meta_value
 643                 );
 644
 645                 // Format the where query arguments.
 646                 $where = array();
 647                 $where[$id_column] = $meta_id;
 648
 649                 /** This action is documented in wp-includes/meta.php */
 650                 do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 651
 652                 if ( 'post' == $meta_type ) {
 653                         /** This action is documented in wp-includes/meta.php */
 654                         do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 655                 }
 656
 657                 // Run the update query, all fields in $data are %s, $where is a %d.
 658                 $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
 659                 if ( ! $result )
 660                         return false;
 661
 662                 // Clear the caches.
 663                 wp_cache_delete($object_id, $meta_type . '_meta');
 664
 665                 /** This action is documented in wp-includes/meta.php */
 666                 do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 667
 668                 if ( 'post' == $meta_type ) {
 669                         /** This action is documented in wp-includes/meta.php */
 670                         do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 671                 }
 672
 673                 return true;
 674         }
 675
 676         // And if the meta was not found.
 677         return false;
 678 }
 679
 680 /**
 681  * Delete meta data by meta ID
 682  *
 683  * @since 3.3.0
 684  *
 685  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 686  * @param int $meta_id ID for a specific meta row
 687  * @return bool True on successful delete, false on failure.
 688  */
 689 function delete_metadata_by_mid( $meta_type, $meta_id ) {
 690         global $wpdb;
 691
 692         // Make sure everything is valid.
 693         if ( ! $meta_type || ! is_numeric( $meta_id ) ) {
 694                 return false;
 695         }
 696
 697         $meta_id = absint( $meta_id );
 698         if ( ! $meta_id ) {
 699                 return false;
 700         }
 701
 702         $table = _get_meta_table( $meta_type );
 703         if ( ! $table ) {
 704                 return false;
 705         }
 706
 707         // object and id columns
 708         $column = sanitize_key($meta_type . '_id');
 709         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 710
 711         // Fetch the meta and go on if it's found.
 712         if ( $meta = get_metadata_by_mid( $meta_type, $meta_id ) ) {
 713                 $object_id = $meta->{$column};
 714
 715                 /** This action is documented in wp-includes/meta.php */
 716                 do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 717
 718                 // Old-style action.
 719                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 720                         /**
 721                          * Fires immediately before deleting post or comment metadata of a specific type.
 722                          *
 723                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 724                          * object type (post or comment).
 725                          *
 726                          * @since 3.4.0
 727                          *
 728                          * @param int $meta_id ID of the metadata entry to delete.
 729                          */
 730                         do_action( "delete_{$meta_type}meta", $meta_id );
 731                 }
 732
 733                 // Run the query, will return true if deleted, false otherwise
 734                 $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
 735
 736                 // Clear the caches.
 737                 wp_cache_delete($object_id, $meta_type . '_meta');
 738
 739                 /** This action is documented in wp-includes/meta.php */
 740                 do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 741
 742                 // Old-style action.
 743                 if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 744                         /**
 745                          * Fires immediately after deleting post or comment metadata of a specific type.
 746                          *
 747                          * The dynamic portion of the hook, `$meta_type`, refers to the meta
 748                          * object type (post or comment).
 749                          *
 750                          * @since 3.4.0
 751                          *
 752                          * @param int $meta_ids Deleted metadata entry ID.
 753                          */
 754                         do_action( "deleted_{$meta_type}meta", $meta_id );
 755                 }
 756
 757                 return $result;
 758
 759         }
 760
 761         // Meta id was not found.
 762         return false;
 763 }
 764
 765 /**
 766  * Update the metadata cache for the specified objects.
 767  *
 768  * @since 2.9.0
 769  *
 770  * @global wpdb $wpdb WordPress database abstraction object.
 771  *
 772  * @param string $meta_type Type of object metadata is for (e.g., comment, post, or user)
 773  * @param int|array $object_ids array or comma delimited list of object IDs to update cache for
 774  * @return mixed Metadata cache for the specified objects, or false on failure.
 775  */
 776 function update_meta_cache($meta_type, $object_ids) {
 777         global $wpdb;
 778
 779         if ( ! $meta_type || ! $object_ids ) {
 780                 return false;
 781         }
 782
 783         $table = _get_meta_table( $meta_type );
 784         if ( ! $table ) {
 785                 return false;
 786         }
 787
 788         $column = sanitize_key($meta_type . '_id');
 789
 790         if ( !is_array($object_ids) ) {
 791                 $object_ids = preg_replace('|[^0-9,]|', '', $object_ids);
 792                 $object_ids = explode(',', $object_ids);
 793         }
 794
 795         $object_ids = array_map('intval', $object_ids);
 796
 797         $cache_key = $meta_type . '_meta';
 798         $ids = array();
 799         $cache = array();
 800         foreach ( $object_ids as $id ) {
 801                 $cached_object = wp_cache_get( $id, $cache_key );
 802                 if ( false === $cached_object )
 803                         $ids[] = $id;
 804                 else
 805                         $cache[$id] = $cached_object;
 806         }
 807
 808         if ( empty( $ids ) )
 809                 return $cache;
 810
 811         // Get meta info
 812         $id_list = join( ',', $ids );
 813         $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 814         $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 );
 815
 816         if ( !empty($meta_list) ) {
 817                 foreach ( $meta_list as $metarow) {
 818                         $mpid = intval($metarow[$column]);
 819                         $mkey = $metarow['meta_key'];
 820                         $mval = $metarow['meta_value'];
 821
 822                         // Force subkeys to be array type:
 823                         if ( !isset($cache[$mpid]) || !is_array($cache[$mpid]) )
 824                                 $cache[$mpid] = array();
 825                         if ( !isset($cache[$mpid][$mkey]) || !is_array($cache[$mpid][$mkey]) )
 826                                 $cache[$mpid][$mkey] = array();
 827
 828                         // Add a value to the current pid/key:
 829                         $cache[$mpid][$mkey][] = $mval;
 830                 }
 831         }
 832
 833         foreach ( $ids as $id ) {
 834                 if ( ! isset($cache[$id]) )
 835                         $cache[$id] = array();
 836                 wp_cache_add( $id, $cache[$id], $cache_key );
 837         }
 838
 839         return $cache;
 840 }
 841
 842 /**
 843  * Given a meta query, generates SQL clauses to be appended to a main query.
 844  *
 845  * @since 3.2.0
 846  *
 847  * @see WP_Meta_Query
 848  *
 849  * @param array $meta_query         A meta query.
 850  * @param string $type              Type of meta.
 851  * @param string $primary_table     Primary database table name.
 852  * @param string $primary_id_column Primary ID column name.
 853  * @param object $context           Optional. The main query object
 854  * @return array Associative array of `JOIN` and `WHERE` SQL.
 855  */
 856 function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
 857         $meta_query_obj = new WP_Meta_Query( $meta_query );
 858         return $meta_query_obj->get_sql( $type, $primary_table, $primary_id_column, $context );
 859 }
 860
 861 /**
 862  * Class for generating SQL clauses that filter a primary query according to metadata keys and values.
 863  *
 864  * `WP_Meta_Query` is a helper that allows primary query classes, such as {@see WP_Query} and {@see WP_User_Query},
 865  * to filter their results by object metadata, by generating `JOIN` and `WHERE` subclauses to be attached
 866  * to the primary SQL query string.
 867  *
 868  * @since 3.2.0
 869  */
 870 class WP_Meta_Query {
 871         /**
 872          * Array of metadata queries.
 873          *
 874          * See {@see WP_Meta_Query::__construct()} for information on meta query arguments.
 875          *
 876          * @since 3.2.0
 877          * @access public
 878          * @var array
 879          */
 880         public $queries = array();
 881
 882         /**
 883          * The relation between the queries. Can be one of 'AND' or 'OR'.
 884          *
 885          * @since 3.2.0
 886          * @access public
 887          * @var string
 888          */
 889         public $relation;
 890
 891         /**
 892          * Database table to query for the metadata.
 893          *
 894          * @since 4.1.0
 895          * @access public
 896          * @var string
 897          */
 898         public $meta_table;
 899
 900         /**
 901          * Column in meta_table that represents the ID of the object the metadata belongs to.
 902          *
 903          * @since 4.1.0
 904          * @access public
 905          * @var string
 906          */
 907         public $meta_id_column;
 908
 909         /**
 910          * Database table that where the metadata's objects are stored (eg $wpdb->users).
 911          *
 912          * @since 4.1.0
 913          * @access public
 914          * @var string
 915          */
 916         public $primary_table;
 917
 918         /**
 919          * Column in primary_table that represents the ID of the object.
 920          *
 921          * @since 4.1.0
 922          * @access public
 923          * @var string
 924          */
 925         public $primary_id_column;
 926
 927         /**
 928          * A flat list of table aliases used in JOIN clauses.
 929          *
 930          * @since 4.1.0
 931          * @access protected
 932          * @var array
 933          */
 934         protected $table_aliases = array();
 935
 936         /**
 937          * Constructor.
 938          *
 939          * @since 3.2.0
 940          * @access public
 941          *
 942          * @param array $meta_query {
 943          *     Array of meta query clauses.
 944          *
 945          *     @type string $relation Optional. The MySQL keyword used to join
 946          *                            the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'.
 947          *     @type array {
 948          *         Optional. An array of first-order clause parameters, or another fully-formed meta query.
 949          *
 950          *         @type string $key     Meta key to filter by.
 951          *         @type string $value   Meta value to filter by.
 952          *         @type string $compare MySQL operator used for comparing the $value. Accepts '=',
 953          *                               '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
 954          *                               'BETWEEN', 'NOT BETWEEN', 'REGEXP', 'NOT REGEXP', or 'RLIKE'.
 955          *                               Default is 'IN' when `$value` is an array, '=' otherwise.
 956          *         @type string $type    MySQL data type that the meta_value column will be CAST to for
 957          *                               comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE',
 958          *                               'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'.
 959          *                               Default is 'CHAR'.
 960          *     }
 961          * }
 962          */
 963         public function __construct( $meta_query = false ) {
 964                 if ( !$meta_query )
 965                         return;
 966
 967                 if ( isset( $meta_query['relation'] ) && strtoupper( $meta_query['relation'] ) == 'OR' ) {
 968                         $this->relation = 'OR';
 969                 } else {
 970                         $this->relation = 'AND';
 971                 }
 972
 973                 $this->queries = $this->sanitize_query( $meta_query );
 974         }
 975
 976         /**
 977          * Ensure the 'meta_query' argument passed to the class constructor is well-formed.
 978          *
 979          * Eliminates empty items and ensures that a 'relation' is set.
 980          *
 981          * @since 4.1.0
 982          * @access public
 983          *
 984          * @param array $queries Array of query clauses.
 985          * @return array Sanitized array of query clauses.
 986          */
 987         public function sanitize_query( $queries ) {
 988                 $clean_queries = array();
 989
 990                 if ( ! is_array( $queries ) ) {
 991                         return $clean_queries;
 992                 }
 993
 994                 foreach ( $queries as $key => $query ) {
 995                         if ( 'relation' === $key ) {
 996                                 $relation = $query;
 997
 998                         } else if ( ! is_array( $query ) ) {
 999                                 continue;
1000
1001                         // First-order clause.
1002                         } else if ( $this->is_first_order_clause( $query ) ) {
1003                                 if ( isset( $query['value'] ) && array() === $query['value'] ) {
1004                                         unset( $query['value'] );
1005                                 }
1006
1007                                 $clean_queries[] = $query;
1008
1009                         // Otherwise, it's a nested query, so we recurse.
1010                         } else {
1011                                 $cleaned_query = $this->sanitize_query( $query );
1012
1013                                 if ( ! empty( $cleaned_query ) ) {
1014                                         $clean_queries[] = $cleaned_query;
1015                                 }
1016                         }
1017                 }
1018
1019                 if ( empty( $clean_queries ) ) {
1020                         return $clean_queries;
1021                 }
1022
1023                 // Sanitize the 'relation' key provided in the query.
1024                 if ( isset( $relation ) && 'OR' === strtoupper( $relation ) ) {
1025                         $clean_queries['relation'] = 'OR';
1026
1027                 /*
1028                  * If there is only a single clause, call the relation 'OR'.
1029                  * This value will not actually be used to join clauses, but it
1030                  * simplifies the logic around combining key-only queries.
1031                  */
1032                 } else if ( 1 === count( $clean_queries ) ) {
1033                         $clean_queries['relation'] = 'OR';
1034
1035                 // Default to AND.
1036                 } else {
1037                         $clean_queries['relation'] = 'AND';
1038                 }
1039
1040                 return $clean_queries;
1041         }
1042
1043         /**
1044          * Determine whether a query clause is first-order.
1045          *
1046          * A first-order meta query clause is one that has either a 'key' or
1047          * a 'value' array key.
1048          *
1049          * @since 4.1.0
1050          * @access protected
1051          *
1052          * @param array $query Meta query arguments.
1053          * @return bool Whether the query clause is a first-order clause.
1054          */
1055         protected function is_first_order_clause( $query ) {
1056                 return isset( $query['key'] ) || isset( $query['value'] );
1057         }
1058
1059         /**
1060          * Constructs a meta query based on 'meta_*' query vars
1061          *
1062          * @since 3.2.0
1063          * @access public
1064          *
1065          * @param array $qv The query variables
1066          */
1067         public function parse_query_vars( $qv ) {
1068                 $meta_query = array();
1069
1070                 /*
1071                  * For orderby=meta_value to work correctly, simple query needs to be
1072                  * first (so that its table join is against an unaliased meta table) and
1073                  * needs to be its own clause (so it doesn't interfere with the logic of
1074                  * the rest of the meta_query).
1075                  */
1076                 $primary_meta_query = array();
1077                 foreach ( array( 'key', 'compare', 'type' ) as $key ) {
1078                         if ( ! empty( $qv[ "meta_$key" ] ) ) {
1079                                 $primary_meta_query[ $key ] = $qv[ "meta_$key" ];
1080                         }
1081                 }
1082
1083                 // WP_Query sets 'meta_value' = '' by default.
1084                 if ( isset( $qv['meta_value'] ) && '' !== $qv['meta_value'] && ( ! is_array( $qv['meta_value'] ) || $qv['meta_value'] ) ) {
1085                         $primary_meta_query['value'] = $qv['meta_value'];
1086                 }
1087
1088                 $existing_meta_query = isset( $qv['meta_query'] ) && is_array( $qv['meta_query'] ) ? $qv['meta_query'] : array();
1089
1090                 if ( ! empty( $primary_meta_query ) && ! empty( $existing_meta_query ) ) {
1091                         $meta_query = array(
1092                                 'relation' => 'AND',
1093                                 $primary_meta_query,
1094                                 $existing_meta_query,
1095                         );
1096                 } else if ( ! empty( $primary_meta_query ) ) {
1097                         $meta_query = array(
1098                                 $primary_meta_query,
1099                         );
1100                 } else if ( ! empty( $existing_meta_query ) ) {
1101                         $meta_query = $existing_meta_query;
1102                 }
1103
1104                 $this->__construct( $meta_query );
1105         }
1106
1107         /**
1108          * Return the appropriate alias for the given meta type if applicable.
1109          *
1110          * @since 3.7.0
1111          * @access public
1112          *
1113          * @param string $type MySQL type to cast meta_value.
1114          * @return string MySQL type.
1115          */
1116         public function get_cast_for_type( $type = '' ) {
1117                 if ( empty( $type ) )
1118                         return 'CHAR';
1119
1120                 $meta_type = strtoupper( $type );
1121
1122                 if ( ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $meta_type ) )
1123                         return 'CHAR';
1124
1125                 if ( 'NUMERIC' == $meta_type )
1126                         $meta_type = 'SIGNED';
1127
1128                 return $meta_type;
1129         }
1130
1131         /**
1132          * Generates SQL clauses to be appended to a main query.
1133          *
1134          * @since 3.2.0
1135          * @access public
1136          *
1137          * @param string $type              Type of meta, eg 'user', 'post'.
1138          * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
1139          * @param string $primary_id_column ID column for the filtered object in $primary_table.
1140          * @param object $context           Optional. The main query object.
1141          * @return array {
1142          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1143          *
1144          *     @type string $join  SQL fragment to append to the main JOIN clause.
1145          *     @type string $where SQL fragment to append to the main WHERE clause.
1146          * }
1147          */
1148         public function get_sql( $type, $primary_table, $primary_id_column, $context = null ) {
1149                 global $wpdb;
1150
1151                 if ( ! $meta_table = _get_meta_table( $type ) ) {
1152                         return false;
1153                 }
1154
1155                 $this->meta_table     = $meta_table;
1156                 $this->meta_id_column = sanitize_key( $type . '_id' );
1157
1158                 $this->primary_table     = $primary_table;
1159                 $this->primary_id_column = $primary_id_column;
1160
1161                 $sql = $this->get_sql_clauses();
1162
1163                 /*
1164                  * If any JOINs are LEFT JOINs (as in the case of NOT EXISTS), then all JOINs should
1165                  * be LEFT. Otherwise posts with no metadata will be excluded from results.
1166                  */
1167                 if ( false !== strpos( $sql['join'], 'LEFT JOIN' ) ) {
1168                         $sql['join'] = str_replace( 'INNER JOIN', 'LEFT JOIN', $sql['join'] );
1169                 }
1170
1171                 /**
1172                  * Filter the meta query's generated SQL.
1173                  *
1174                  * @since 3.1.0
1175                  *
1176                  * @param array $args {
1177                  *     An array of meta query SQL arguments.
1178                  *
1179                  *     @type array  $clauses           Array containing the query's JOIN and WHERE clauses.
1180                  *     @type array  $queries           Array of meta queries.
1181                  *     @type string $type              Type of meta.
1182                  *     @type string $primary_table     Primary table.
1183                  *     @type string $primary_id_column Primary column ID.
1184                  *     @type object $context           The main query object.
1185                  * }
1186                  */
1187                 return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
1188         }
1189
1190         /**
1191          * Generate SQL clauses to be appended to a main query.
1192          *
1193          * Called by the public {@see WP_Meta_Query::get_sql()}, this method
1194          * is abstracted out to maintain parity with the other Query classes.
1195          *
1196          * @since 4.1.0
1197          * @access protected
1198          *
1199          * @return array {
1200          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1201          *
1202          *     @type string $join  SQL fragment to append to the main JOIN clause.
1203          *     @type string $where SQL fragment to append to the main WHERE clause.
1204          * }
1205          */
1206         protected function get_sql_clauses() {
1207                 /*
1208                  * $queries are passed by reference to get_sql_for_query() for recursion.
1209                  * To keep $this->queries unaltered, pass a copy.
1210                  */
1211                 $queries = $this->queries;
1212                 $sql = $this->get_sql_for_query( $queries );
1213
1214                 if ( ! empty( $sql['where'] ) ) {
1215                         $sql['where'] = ' AND ' . $sql['where'];
1216                 }
1217
1218                 return $sql;
1219         }
1220
1221         /**
1222          * Generate SQL clauses for a single query array.
1223          *
1224          * If nested subqueries are found, this method recurses the tree to
1225          * produce the properly nested SQL.
1226          *
1227          * @since 4.1.0
1228          * @access protected
1229          *
1230          * @param array $query Query to parse, passed by reference.
1231          * @param int   $depth Optional. Number of tree levels deep we currently are.
1232          *                     Used to calculate indentation. Default 0.
1233          * @return array {
1234          *     Array containing JOIN and WHERE SQL clauses to append to a single query array.
1235          *
1236          *     @type string $join  SQL fragment to append to the main JOIN clause.
1237          *     @type string $where SQL fragment to append to the main WHERE clause.
1238          * }
1239          */
1240         protected function get_sql_for_query( &$query, $depth = 0 ) {
1241                 $sql_chunks = array(
1242                         'join'  => array(),
1243                         'where' => array(),
1244                 );
1245
1246                 $sql = array(
1247                         'join'  => '',
1248                         'where' => '',
1249                 );
1250
1251                 $indent = '';
1252                 for ( $i = 0; $i < $depth; $i++ ) {
1253                         $indent .= "  ";
1254                 }
1255
1256                 foreach ( $query as $key => &$clause ) {
1257                         if ( 'relation' === $key ) {
1258                                 $relation = $query['relation'];
1259                         } else if ( is_array( $clause ) ) {
1260
1261                                 // This is a first-order clause.
1262                                 if ( $this->is_first_order_clause( $clause ) ) {
1263                                         $clause_sql = $this->get_sql_for_clause( $clause, $query );
1264
1265                                         $where_count = count( $clause_sql['where'] );
1266                                         if ( ! $where_count ) {
1267                                                 $sql_chunks['where'][] = '';
1268                                         } else if ( 1 === $where_count ) {
1269                                                 $sql_chunks['where'][] = $clause_sql['where'][0];
1270                                         } else {
1271                                                 $sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )';
1272                                         }
1273
1274                                         $sql_chunks['join'] = array_merge( $sql_chunks['join'], $clause_sql['join'] );
1275                                 // This is a subquery, so we recurse.
1276                                 } else {
1277                                         $clause_sql = $this->get_sql_for_query( $clause, $depth + 1 );
1278
1279                                         $sql_chunks['where'][] = $clause_sql['where'];
1280                                         $sql_chunks['join'][]  = $clause_sql['join'];
1281                                 }
1282                         }
1283                 }
1284
1285                 // Filter to remove empties.
1286                 $sql_chunks['join']  = array_filter( $sql_chunks['join'] );
1287                 $sql_chunks['where'] = array_filter( $sql_chunks['where'] );
1288
1289                 if ( empty( $relation ) ) {
1290                         $relation = 'AND';
1291                 }
1292
1293                 // Filter duplicate JOIN clauses and combine into a single string.
1294                 if ( ! empty( $sql_chunks['join'] ) ) {
1295                         $sql['join'] = implode( ' ', array_unique( $sql_chunks['join'] ) );
1296                 }
1297
1298                 // Generate a single WHERE clause with proper brackets and indentation.
1299                 if ( ! empty( $sql_chunks['where'] ) ) {
1300                         $sql['where'] = '( ' . "\n  " . $indent . implode( ' ' . "\n  " . $indent . $relation . ' ' . "\n  " . $indent, $sql_chunks['where'] ) . "\n" . $indent . ')';
1301                 }
1302
1303                 return $sql;
1304         }
1305
1306         /**
1307          * Generate SQL JOIN and WHERE clauses for a first-order query clause.
1308          *
1309          * "First-order" means that it's an array with a 'key' or 'value'.
1310          *
1311          * @since 4.1.0
1312          * @access public
1313          *
1314          * @param array $clause       Query clause, passed by reference.
1315          * @param array $parent_query Parent query array.
1316          * @return array {
1317          *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
1318          *
1319          *     @type string $join  SQL fragment to append to the main JOIN clause.
1320          *     @type string $where SQL fragment to append to the main WHERE clause.
1321          * }
1322          */
1323         public function get_sql_for_clause( &$clause, $parent_query ) {
1324                 global $wpdb;
1325
1326                 $sql_chunks = array(
1327                         'where' => array(),
1328                         'join' => array(),
1329                 );
1330
1331                 if ( isset( $clause['compare'] ) ) {
1332                         $clause['compare'] = strtoupper( $clause['compare'] );
1333                 } else {
1334                         $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '=';
1335                 }
1336
1337                 if ( ! in_array( $clause['compare'], array(
1338                         '=', '!=', '>', '>=', '<', '<=',
1339                         'LIKE', 'NOT LIKE',
1340                         'IN', 'NOT IN',
1341                         'BETWEEN', 'NOT BETWEEN',
1342                         'EXISTS', 'NOT EXISTS',
1343                         'REGEXP', 'NOT REGEXP', 'RLIKE'
1344                 ) ) ) {
1345                         $clause['compare'] = '=';
1346                 }
1347
1348                 $meta_compare = $clause['compare'];
1349
1350                 // First build the JOIN clause, if one is required.
1351                 $join = '';
1352
1353                 // We prefer to avoid joins if possible. Look for an existing join compatible with this clause.
1354                 $alias = $this->find_compatible_table_alias( $clause, $parent_query );
1355                 if ( false === $alias ) {
1356                         $i = count( $this->table_aliases );
1357                         $alias = $i ? 'mt' . $i : $this->meta_table;
1358
1359                         // JOIN clauses for NOT EXISTS have their own syntax.
1360                         if ( 'NOT EXISTS' === $meta_compare ) {
1361                                 $join .= " LEFT JOIN $this->meta_table";
1362                                 $join .= $i ? " AS $alias" : '';
1363                                 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key = %s )", $clause['key'] );
1364
1365                         // All other JOIN clauses.
1366                         } else {
1367                                 $join .= " INNER JOIN $this->meta_table";
1368                                 $join .= $i ? " AS $alias" : '';
1369                                 $join .= " ON ( $this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column )";
1370                         }
1371
1372                         $this->table_aliases[] = $alias;
1373                         $sql_chunks['join'][] = $join;
1374                 }
1375
1376                 // Save the alias to this clause, for future siblings to find.
1377                 $clause['alias'] = $alias;
1378
1379                 // Next, build the WHERE clause.
1380
1381                 // meta_key.
1382                 if ( array_key_exists( 'key', $clause ) ) {
1383                         if ( 'NOT EXISTS' === $meta_compare ) {
1384                                 $sql_chunks['where'][] = $alias . '.' . $this->meta_id_column . ' IS NULL';
1385                         } else {
1386                                 $sql_chunks['where'][] = $wpdb->prepare( "$alias.meta_key = %s", trim( $clause['key'] ) );
1387                         }
1388                 }
1389
1390                 // meta_value.
1391                 if ( array_key_exists( 'value', $clause ) ) {
1392                         $meta_value = $clause['value'];
1393                         $meta_type = $this->get_cast_for_type( isset( $clause['type'] ) ? $clause['type'] : '' );
1394
1395                         if ( in_array( $meta_compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ) ) ) {
1396                                 if ( ! is_array( $meta_value ) ) {
1397                                         $meta_value = preg_split( '/[,\s]+/', $meta_value );
1398                                 }
1399                         } else {
1400                                 $meta_value = trim( $meta_value );
1401                         }
1402
1403                         switch ( $meta_compare ) {
1404                                 case 'IN' :
1405                                 case 'NOT IN' :
1406                                         $meta_compare_string = '(' . substr( str_repeat( ',%s', count( $meta_value ) ), 1 ) . ')';
1407                                         $where = $wpdb->prepare( $meta_compare_string, $meta_value );
1408                                         break;
1409
1410                                 case 'BETWEEN' :
1411                                 case 'NOT BETWEEN' :
1412                                         $meta_value = array_slice( $meta_value, 0, 2 );
1413                                         $where = $wpdb->prepare( '%s AND %s', $meta_value );
1414                                         break;
1415
1416                                 case 'LIKE' :
1417                                 case 'NOT LIKE' :
1418                                         $meta_value = '%' . $wpdb->esc_like( $meta_value ) . '%';
1419                                         $where = $wpdb->prepare( '%s', $meta_value );
1420                                         break;
1421
1422                                 // EXISTS with a value is interpreted as '='.
1423                                 case 'EXISTS' :
1424                                         $meta_compare = '=';
1425                                         $where = $wpdb->prepare( '%s', $meta_value );
1426                                         break;
1427
1428                                 // 'value' is ignored for NOT EXISTS.
1429                                 case 'NOT EXISTS' :
1430                                         $where = '';
1431                                         break;
1432
1433                                 default :
1434                                         $where = $wpdb->prepare( '%s', $meta_value );
1435                                         break;
1436
1437                         }
1438
1439                         if ( $where ) {
1440                                 $sql_chunks['where'][] = "CAST($alias.meta_value AS {$meta_type}) {$meta_compare} {$where}";
1441                         }
1442                 }
1443
1444                 /*
1445                  * Multiple WHERE clauses (for meta_key and meta_value) should
1446                  * be joined in parentheses.
1447                  */
1448                 if ( 1 < count( $sql_chunks['where'] ) ) {
1449                         $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' );
1450                 }
1451
1452                 return $sql_chunks;
1453         }
1454
1455         /**
1456          * Identify an existing table alias that is compatible with the current
1457          * query clause.
1458          *
1459          * We avoid unnecessary table joins by allowing each clause to look for
1460          * an existing table alias that is compatible with the query that it
1461          * needs to perform.
1462          *
1463          * An existing alias is compatible if (a) it is a sibling of `$clause`
1464          * (ie, it's under the scope of the same relation), and (b) the combination
1465          * of operator and relation between the clauses allows for a shared table join.
1466          * In the case of {@see WP_Meta_Query}, this only applies to 'IN' clauses that
1467          * are connected by the relation 'OR'.
1468          *
1469          * @since 4.1.0
1470          * @access protected
1471          *
1472          * @param  array       $clause       Query clause.
1473          * @param  array       $parent_query Parent query of $clause.
1474          * @return string|bool Table alias if found, otherwise false.
1475          */
1476         protected function find_compatible_table_alias( $clause, $parent_query ) {
1477                 $alias = false;
1478
1479                 foreach ( $parent_query as $sibling ) {
1480                         // If the sibling has no alias yet, there's nothing to check.
1481                         if ( empty( $sibling['alias'] ) ) {
1482                                 continue;
1483                         }
1484
1485                         // We're only interested in siblings that are first-order clauses.
1486                         if ( ! is_array( $sibling ) || ! $this->is_first_order_clause( $sibling ) ) {
1487                                 continue;
1488                         }
1489
1490                         $compatible_compares = array();
1491
1492                         // Clauses connected by OR can share joins as long as they have "positive" operators.
1493                         if ( 'OR' === $parent_query['relation'] ) {
1494                                 $compatible_compares = array( '=', 'IN', 'BETWEEN', 'LIKE', 'REGEXP', 'RLIKE', '>', '>=', '<', '<=' );
1495
1496                         // Clauses joined by AND with "negative" operators share a join only if they also share a key.
1497                         } else if ( isset( $sibling['key'] ) && isset( $clause['key'] ) && $sibling['key'] === $clause['key'] ) {
1498                                 $compatible_compares = array( '!=', 'NOT IN', 'NOT LIKE' );
1499                         }
1500
1501                         $clause_compare  = strtoupper( $clause['compare'] );
1502                         $sibling_compare = strtoupper( $sibling['compare'] );
1503                         if ( in_array( $clause_compare, $compatible_compares ) && in_array( $sibling_compare, $compatible_compares ) ) {
1504                                 $alias = $sibling['alias'];
1505                                 break;
1506                         }
1507                 }
1508
1509                 /**
1510                  * Filter the table alias identified as compatible with the current clause.
1511                  *
1512                  * @since 4.1.0
1513                  *
1514                  * @param string|bool $alias        Table alias, or false if none was found.
1515                  * @param array       $clause       First-order query clause.
1516                  * @param array       $parent_query Parent of $clause.
1517                  * @param object      $this         WP_Meta_Query object.
1518                  */
1519                 return apply_filters( 'meta_query_find_compatible_table_alias', $alias, $clause, $parent_query, $this ) ;
1520         }
1521 }
1522
1523 /**
1524  * Retrieve the name of the metadata table for the specified object type.
1525  *
1526  * @since 2.9.0
1527  *
1528  * @global wpdb $wpdb WordPress database abstraction object.
1529  *
1530  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
1531  * @return mixed Metadata table name, or false if no metadata table exists
1532  */
1533 function _get_meta_table($type) {
1534         global $wpdb;
1535
1536         $table_name = $type . 'meta';
1537
1538         if ( empty($wpdb->$table_name) )
1539                 return false;
1540
1541         return $wpdb->$table_name;
1542 }
1543
1544 /**
1545  * Determine whether a meta key is protected.
1546  *
1547  * @since 3.1.3
1548  *
1549  * @param string      $meta_key Meta key
1550  * @param string|null $meta_type
1551  * @return bool True if the key is protected, false otherwise.
1552  */
1553 function is_protected_meta( $meta_key, $meta_type = null ) {
1554         $protected = ( '_' == $meta_key[0] );
1555
1556         /**
1557          * Filter whether a meta key is protected.
1558          *
1559          * @since 3.2.0
1560          *
1561          * @param bool   $protected Whether the key is protected. Default false.
1562          * @param string $meta_key  Meta key.
1563          * @param string $meta_type Meta type.
1564          */
1565         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
1566 }
1567
1568 /**
1569  * Sanitize meta value.
1570  *
1571  * @since 3.1.3
1572  *
1573  * @param string $meta_key Meta key
1574  * @param mixed $meta_value Meta value to sanitize
1575  * @param string $meta_type Type of meta
1576  * @return mixed Sanitized $meta_value
1577  */
1578 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
1579
1580         /**
1581          * Filter the sanitization of a specific meta key of a specific meta type.
1582          *
1583          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
1584          * refer to the metadata object type (comment, post, or user) and the meta
1585          * key value,
1586          * respectively.
1587          *
1588          * @since 3.3.0
1589          *
1590          * @param mixed  $meta_value Meta value to sanitize.
1591          * @param string $meta_key   Meta key.
1592          * @param string $meta_type  Meta type.
1593          */
1594         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
1595 }
1596
1597 /**
1598  * Register meta key
1599  *
1600  * @since 3.3.0
1601  *
1602  * @param string $meta_type Type of meta
1603  * @param string $meta_key Meta key
1604  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
1605  * @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.
1606  */
1607 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
1608         if ( is_callable( $sanitize_callback ) )
1609                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
1610
1611         if ( empty( $auth_callback ) ) {
1612                 if ( is_protected_meta( $meta_key, $meta_type ) )
1613                         $auth_callback = '__return_false';
1614                 else
1615                         $auth_callback = '__return_true';
1616         }
1617
1618         if ( is_callable( $auth_callback ) )
1619                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
1620 }