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 mixed 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          * A flat list of clauses, keyed by clause 'name'.
 938          *
 939          * @since 4.2.0
 940          * @access protected
 941          * @var array
 942          */
 943         protected $clauses = array();
 944
 945         /**
 946          * Constructor.
 947          *
 948          * @since 3.2.0
 949          * @since 4.2.0 Introduced support for naming query clauses by associative array keys.
 950          *
 951          * @access public
 952          *
 953          * @param array $meta_query {
 954          *     Array of meta query clauses. When first-order clauses use strings as their array keys, they may be
 955          *     referenced in the 'orderby' parameter of the parent query.
 956          *
 957          *     @type string $relation Optional. The MySQL keyword used to join
 958          *                            the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'.
 959          *     @type array {
 960          *         Optional. An array of first-order clause parameters, or another fully-formed meta query.
 961          *
 962          *         @type string $key     Meta key to filter by.
 963          *         @type string $value   Meta value to filter by.
 964          *         @type string $compare MySQL operator used for comparing the $value. Accepts '=',
 965          *                               '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
 966          *                               'BETWEEN', 'NOT BETWEEN', 'REGEXP', 'NOT REGEXP', or 'RLIKE'.
 967          *                               Default is 'IN' when `$value` is an array, '=' otherwise.
 968          *         @type string $type    MySQL data type that the meta_value column will be CAST to for
 969          *                               comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE',
 970          *                               'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'.
 971          *                               Default is 'CHAR'.
 972          *     }
 973          * }
 974          */
 975         public function __construct( $meta_query = false ) {
 976                 if ( !$meta_query )
 977                         return;
 978
 979                 if ( isset( $meta_query['relation'] ) && strtoupper( $meta_query['relation'] ) == 'OR' ) {
 980                         $this->relation = 'OR';
 981                 } else {
 982                         $this->relation = 'AND';
 983                 }
 984
 985                 $this->queries = $this->sanitize_query( $meta_query );
 986         }
 987
 988         /**
 989          * Ensure the 'meta_query' argument passed to the class constructor is well-formed.
 990          *
 991          * Eliminates empty items and ensures that a 'relation' is set.
 992          *
 993          * @since 4.1.0
 994          * @access public
 995          *
 996          * @param array $queries Array of query clauses.
 997          * @return array Sanitized array of query clauses.
 998          */
 999         public function sanitize_query( $queries ) {
1000                 $clean_queries = array();
1001
1002                 if ( ! is_array( $queries ) ) {
1003                         return $clean_queries;
1004                 }
1005
1006                 foreach ( $queries as $key => $query ) {
1007                         if ( 'relation' === $key ) {
1008                                 $relation = $query;
1009
1010                         } elseif ( ! is_array( $query ) ) {
1011                                 continue;
1012
1013                         // First-order clause.
1014                         } elseif ( $this->is_first_order_clause( $query ) ) {
1015                                 if ( isset( $query['value'] ) && array() === $query['value'] ) {
1016                                         unset( $query['value'] );
1017                                 }
1018
1019                                 $clean_queries[ $key ] = $query;
1020
1021                         // Otherwise, it's a nested query, so we recurse.
1022                         } else {
1023                                 $cleaned_query = $this->sanitize_query( $query );
1024
1025                                 if ( ! empty( $cleaned_query ) ) {
1026                                         $clean_queries[ $key ] = $cleaned_query;
1027                                 }
1028                         }
1029                 }
1030
1031                 if ( empty( $clean_queries ) ) {
1032                         return $clean_queries;
1033                 }
1034
1035                 // Sanitize the 'relation' key provided in the query.
1036                 if ( isset( $relation ) && 'OR' === strtoupper( $relation ) ) {
1037                         $clean_queries['relation'] = 'OR';
1038
1039                 /*
1040                  * If there is only a single clause, call the relation 'OR'.
1041                  * This value will not actually be used to join clauses, but it
1042                  * simplifies the logic around combining key-only queries.
1043                  */
1044                 } elseif ( 1 === count( $clean_queries ) ) {
1045                         $clean_queries['relation'] = 'OR';
1046
1047                 // Default to AND.
1048                 } else {
1049                         $clean_queries['relation'] = 'AND';
1050                 }
1051
1052                 return $clean_queries;
1053         }
1054
1055         /**
1056          * Determine whether a query clause is first-order.
1057          *
1058          * A first-order meta query clause is one that has either a 'key' or
1059          * a 'value' array key.
1060          *
1061          * @since 4.1.0
1062          * @access protected
1063          *
1064          * @param array $query Meta query arguments.
1065          * @return bool Whether the query clause is a first-order clause.
1066          */
1067         protected function is_first_order_clause( $query ) {
1068                 return isset( $query['key'] ) || isset( $query['value'] );
1069         }
1070
1071         /**
1072          * Constructs a meta query based on 'meta_*' query vars
1073          *
1074          * @since 3.2.0
1075          * @access public
1076          *
1077          * @param array $qv The query variables
1078          */
1079         public function parse_query_vars( $qv ) {
1080                 $meta_query = array();
1081
1082                 /*
1083                  * For orderby=meta_value to work correctly, simple query needs to be
1084                  * first (so that its table join is against an unaliased meta table) and
1085                  * needs to be its own clause (so it doesn't interfere with the logic of
1086                  * the rest of the meta_query).
1087                  */
1088                 $primary_meta_query = array();
1089                 foreach ( array( 'key', 'compare', 'type' ) as $key ) {
1090                         if ( ! empty( $qv[ "meta_$key" ] ) ) {
1091                                 $primary_meta_query[ $key ] = $qv[ "meta_$key" ];
1092                         }
1093                 }
1094
1095                 // WP_Query sets 'meta_value' = '' by default.
1096                 if ( isset( $qv['meta_value'] ) && '' !== $qv['meta_value'] && ( ! is_array( $qv['meta_value'] ) || $qv['meta_value'] ) ) {
1097                         $primary_meta_query['value'] = $qv['meta_value'];
1098                 }
1099
1100                 $existing_meta_query = isset( $qv['meta_query'] ) && is_array( $qv['meta_query'] ) ? $qv['meta_query'] : array();
1101
1102                 if ( ! empty( $primary_meta_query ) && ! empty( $existing_meta_query ) ) {
1103                         $meta_query = array(
1104                                 'relation' => 'AND',
1105                                 $primary_meta_query,
1106                                 $existing_meta_query,
1107                         );
1108                 } elseif ( ! empty( $primary_meta_query ) ) {
1109                         $meta_query = array(
1110                                 $primary_meta_query,
1111                         );
1112                 } elseif ( ! empty( $existing_meta_query ) ) {
1113                         $meta_query = $existing_meta_query;
1114                 }
1115
1116                 $this->__construct( $meta_query );
1117         }
1118
1119         /**
1120          * Return the appropriate alias for the given meta type if applicable.
1121          *
1122          * @since 3.7.0
1123          * @access public
1124          *
1125          * @param string $type MySQL type to cast meta_value.
1126          * @return string MySQL type.
1127          */
1128         public function get_cast_for_type( $type = '' ) {
1129                 if ( empty( $type ) )
1130                         return 'CHAR';
1131
1132                 $meta_type = strtoupper( $type );
1133
1134                 if ( ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $meta_type ) )
1135                         return 'CHAR';
1136
1137                 if ( 'NUMERIC' == $meta_type )
1138                         $meta_type = 'SIGNED';
1139
1140                 return $meta_type;
1141         }
1142
1143         /**
1144          * Generates SQL clauses to be appended to a main query.
1145          *
1146          * @since 3.2.0
1147          * @access public
1148          *
1149          * @param string $type              Type of meta, eg 'user', 'post'.
1150          * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
1151          * @param string $primary_id_column ID column for the filtered object in $primary_table.
1152          * @param object $context           Optional. The main query object.
1153          * @return array {
1154          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1155          *
1156          *     @type string $join  SQL fragment to append to the main JOIN clause.
1157          *     @type string $where SQL fragment to append to the main WHERE clause.
1158          * }
1159          */
1160         public function get_sql( $type, $primary_table, $primary_id_column, $context = null ) {
1161                 if ( ! $meta_table = _get_meta_table( $type ) ) {
1162                         return false;
1163                 }
1164
1165                 $this->meta_table     = $meta_table;
1166                 $this->meta_id_column = sanitize_key( $type . '_id' );
1167
1168                 $this->primary_table     = $primary_table;
1169                 $this->primary_id_column = $primary_id_column;
1170
1171                 $sql = $this->get_sql_clauses();
1172
1173                 /*
1174                  * If any JOINs are LEFT JOINs (as in the case of NOT EXISTS), then all JOINs should
1175                  * be LEFT. Otherwise posts with no metadata will be excluded from results.
1176                  */
1177                 if ( false !== strpos( $sql['join'], 'LEFT JOIN' ) ) {
1178                         $sql['join'] = str_replace( 'INNER JOIN', 'LEFT JOIN', $sql['join'] );
1179                 }
1180
1181                 /**
1182                  * Filter the meta query's generated SQL.
1183                  *
1184                  * @since 3.1.0
1185                  *
1186                  * @param array $args {
1187                  *     An array of meta query SQL arguments.
1188                  *
1189                  *     @type array  $clauses           Array containing the query's JOIN and WHERE clauses.
1190                  *     @type array  $queries           Array of meta queries.
1191                  *     @type string $type              Type of meta.
1192                  *     @type string $primary_table     Primary table.
1193                  *     @type string $primary_id_column Primary column ID.
1194                  *     @type object $context           The main query object.
1195                  * }
1196                  */
1197                 return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
1198         }
1199
1200         /**
1201          * Generate SQL clauses to be appended to a main query.
1202          *
1203          * Called by the public {@see WP_Meta_Query::get_sql()}, this method
1204          * is abstracted out to maintain parity with the other Query classes.
1205          *
1206          * @since 4.1.0
1207          * @access protected
1208          *
1209          * @return array {
1210          *     Array containing JOIN and WHERE SQL clauses to append to the main query.
1211          *
1212          *     @type string $join  SQL fragment to append to the main JOIN clause.
1213          *     @type string $where SQL fragment to append to the main WHERE clause.
1214          * }
1215          */
1216         protected function get_sql_clauses() {
1217                 /*
1218                  * $queries are passed by reference to get_sql_for_query() for recursion.
1219                  * To keep $this->queries unaltered, pass a copy.
1220                  */
1221                 $queries = $this->queries;
1222                 $sql = $this->get_sql_for_query( $queries );
1223
1224                 if ( ! empty( $sql['where'] ) ) {
1225                         $sql['where'] = ' AND ' . $sql['where'];
1226                 }
1227
1228                 return $sql;
1229         }
1230
1231         /**
1232          * Generate SQL clauses for a single query array.
1233          *
1234          * If nested subqueries are found, this method recurses the tree to
1235          * produce the properly nested SQL.
1236          *
1237          * @since 4.1.0
1238          * @access protected
1239          *
1240          * @param array $query Query to parse, passed by reference.
1241          * @param int   $depth Optional. Number of tree levels deep we currently are.
1242          *                     Used to calculate indentation. Default 0.
1243          * @return array {
1244          *     Array containing JOIN and WHERE SQL clauses to append to a single query array.
1245          *
1246          *     @type string $join  SQL fragment to append to the main JOIN clause.
1247          *     @type string $where SQL fragment to append to the main WHERE clause.
1248          * }
1249          */
1250         protected function get_sql_for_query( &$query, $depth = 0 ) {
1251                 $sql_chunks = array(
1252                         'join'  => array(),
1253                         'where' => array(),
1254                 );
1255
1256                 $sql = array(
1257                         'join'  => '',
1258                         'where' => '',
1259                 );
1260
1261                 $indent = '';
1262                 for ( $i = 0; $i < $depth; $i++ ) {
1263                         $indent .= "  ";
1264                 }
1265
1266                 foreach ( $query as $key => &$clause ) {
1267                         if ( 'relation' === $key ) {
1268                                 $relation = $query['relation'];
1269                         } elseif ( is_array( $clause ) ) {
1270
1271                                 // This is a first-order clause.
1272                                 if ( $this->is_first_order_clause( $clause ) ) {
1273                                         $clause_sql = $this->get_sql_for_clause( $clause, $query, $key );
1274
1275                                         $where_count = count( $clause_sql['where'] );
1276                                         if ( ! $where_count ) {
1277                                                 $sql_chunks['where'][] = '';
1278                                         } elseif ( 1 === $where_count ) {
1279                                                 $sql_chunks['where'][] = $clause_sql['where'][0];
1280                                         } else {
1281                                                 $sql_chunks['where'][] = '( ' . implode( ' AND ', $clause_sql['where'] ) . ' )';
1282                                         }
1283
1284                                         $sql_chunks['join'] = array_merge( $sql_chunks['join'], $clause_sql['join'] );
1285                                 // This is a subquery, so we recurse.
1286                                 } else {
1287                                         $clause_sql = $this->get_sql_for_query( $clause, $depth + 1 );
1288
1289                                         $sql_chunks['where'][] = $clause_sql['where'];
1290                                         $sql_chunks['join'][]  = $clause_sql['join'];
1291                                 }
1292                         }
1293                 }
1294
1295                 // Filter to remove empties.
1296                 $sql_chunks['join']  = array_filter( $sql_chunks['join'] );
1297                 $sql_chunks['where'] = array_filter( $sql_chunks['where'] );
1298
1299                 if ( empty( $relation ) ) {
1300                         $relation = 'AND';
1301                 }
1302
1303                 // Filter duplicate JOIN clauses and combine into a single string.
1304                 if ( ! empty( $sql_chunks['join'] ) ) {
1305                         $sql['join'] = implode( ' ', array_unique( $sql_chunks['join'] ) );
1306                 }
1307
1308                 // Generate a single WHERE clause with proper brackets and indentation.
1309                 if ( ! empty( $sql_chunks['where'] ) ) {
1310                         $sql['where'] = '( ' . "\n  " . $indent . implode( ' ' . "\n  " . $indent . $relation . ' ' . "\n  " . $indent, $sql_chunks['where'] ) . "\n" . $indent . ')';
1311                 }
1312
1313                 return $sql;
1314         }
1315
1316         /**
1317          * Generate SQL JOIN and WHERE clauses for a first-order query clause.
1318          *
1319          * "First-order" means that it's an array with a 'key' or 'value'.
1320          *
1321          * @since 4.1.0
1322          * @access public
1323          *
1324          * @param array  $clause       Query clause, passed by reference.
1325          * @param array  $parent_query Parent query array.
1326          * @param string $clause_key   Optional. The array key used to name the clause in the original `$meta_query`
1327          *                             parameters. If not provided, a key will be generated automatically.
1328          * @return array {
1329          *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
1330          *
1331          *     @type string $join  SQL fragment to append to the main JOIN clause.
1332          *     @type string $where SQL fragment to append to the main WHERE clause.
1333          * }
1334          */
1335         public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) {
1336                 global $wpdb;
1337
1338                 $sql_chunks = array(
1339                         'where' => array(),
1340                         'join' => array(),
1341                 );
1342
1343                 if ( isset( $clause['compare'] ) ) {
1344                         $clause['compare'] = strtoupper( $clause['compare'] );
1345                 } else {
1346                         $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '=';
1347                 }
1348
1349                 if ( ! in_array( $clause['compare'], array(
1350                         '=', '!=', '>', '>=', '<', '<=',
1351                         'LIKE', 'NOT LIKE',
1352                         'IN', 'NOT IN',
1353                         'BETWEEN', 'NOT BETWEEN',
1354                         'EXISTS', 'NOT EXISTS',
1355                         'REGEXP', 'NOT REGEXP', 'RLIKE'
1356                 ) ) ) {
1357                         $clause['compare'] = '=';
1358                 }
1359
1360                 $meta_compare = $clause['compare'];
1361
1362                 // First build the JOIN clause, if one is required.
1363                 $join = '';
1364
1365                 // We prefer to avoid joins if possible. Look for an existing join compatible with this clause.
1366                 $alias = $this->find_compatible_table_alias( $clause, $parent_query );
1367                 if ( false === $alias ) {
1368                         $i = count( $this->table_aliases );
1369                         $alias = $i ? 'mt' . $i : $this->meta_table;
1370
1371                         // JOIN clauses for NOT EXISTS have their own syntax.
1372                         if ( 'NOT EXISTS' === $meta_compare ) {
1373                                 $join .= " LEFT JOIN $this->meta_table";
1374                                 $join .= $i ? " AS $alias" : '';
1375                                 $join .= $wpdb->prepare( " ON ($this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column AND $alias.meta_key = %s )", $clause['key'] );
1376
1377                         // All other JOIN clauses.
1378                         } else {
1379                                 $join .= " INNER JOIN $this->meta_table";
1380                                 $join .= $i ? " AS $alias" : '';
1381                                 $join .= " ON ( $this->primary_table.$this->primary_id_column = $alias.$this->meta_id_column )";
1382                         }
1383
1384                         $this->table_aliases[] = $alias;
1385                         $sql_chunks['join'][] = $join;
1386                 }
1387
1388                 // Save the alias to this clause, for future siblings to find.
1389                 $clause['alias'] = $alias;
1390
1391                 // Determine the data type.
1392                 $_meta_type = isset( $clause['type'] ) ? $clause['type'] : '';
1393                 $meta_type  = $this->get_cast_for_type( $_meta_type );
1394                 $clause['cast'] = $meta_type;
1395
1396                 // Fallback for clause keys is the table alias.
1397                 if ( ! $clause_key ) {
1398                         $clause_key = $clause['alias'];
1399                 }
1400
1401                 // Ensure unique clause keys, so none are overwritten.
1402                 $iterator = 1;
1403                 $clause_key_base = $clause_key;
1404                 while ( isset( $this->clauses[ $clause_key ] ) ) {
1405                         $clause_key = $clause_key_base . '-' . $iterator;
1406                         $iterator++;
1407                 }
1408
1409                 // Store the clause in our flat array.
1410                 $this->clauses[ $clause_key ] =& $clause;
1411
1412                 // Next, build the WHERE clause.
1413
1414                 // meta_key.
1415                 if ( array_key_exists( 'key', $clause ) ) {
1416                         if ( 'NOT EXISTS' === $meta_compare ) {
1417                                 $sql_chunks['where'][] = $alias . '.' . $this->meta_id_column . ' IS NULL';
1418                         } else {
1419                                 $sql_chunks['where'][] = $wpdb->prepare( "$alias.meta_key = %s", trim( $clause['key'] ) );
1420                         }
1421                 }
1422
1423                 // meta_value.
1424                 if ( array_key_exists( 'value', $clause ) ) {
1425                         $meta_value = $clause['value'];
1426
1427                         if ( in_array( $meta_compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ) ) ) {
1428                                 if ( ! is_array( $meta_value ) ) {
1429                                         $meta_value = preg_split( '/[,\s]+/', $meta_value );
1430                                 }
1431                         } else {
1432                                 $meta_value = trim( $meta_value );
1433                         }
1434
1435                         switch ( $meta_compare ) {
1436                                 case 'IN' :
1437                                 case 'NOT IN' :
1438                                         $meta_compare_string = '(' . substr( str_repeat( ',%s', count( $meta_value ) ), 1 ) . ')';
1439                                         $where = $wpdb->prepare( $meta_compare_string, $meta_value );
1440                                         break;
1441
1442                                 case 'BETWEEN' :
1443                                 case 'NOT BETWEEN' :
1444                                         $meta_value = array_slice( $meta_value, 0, 2 );
1445                                         $where = $wpdb->prepare( '%s AND %s', $meta_value );
1446                                         break;
1447
1448                                 case 'LIKE' :
1449                                 case 'NOT LIKE' :
1450                                         $meta_value = '%' . $wpdb->esc_like( $meta_value ) . '%';
1451                                         $where = $wpdb->prepare( '%s', $meta_value );
1452                                         break;
1453
1454                                 // EXISTS with a value is interpreted as '='.
1455                                 case 'EXISTS' :
1456                                         $meta_compare = '=';
1457                                         $where = $wpdb->prepare( '%s', $meta_value );
1458                                         break;
1459
1460                                 // 'value' is ignored for NOT EXISTS.
1461                                 case 'NOT EXISTS' :
1462                                         $where = '';
1463                                         break;
1464
1465                                 default :
1466                                         $where = $wpdb->prepare( '%s', $meta_value );
1467                                         break;
1468
1469                         }
1470
1471                         if ( $where ) {
1472                                 $sql_chunks['where'][] = "CAST($alias.meta_value AS {$meta_type}) {$meta_compare} {$where}";
1473                         }
1474                 }
1475
1476                 /*
1477                  * Multiple WHERE clauses (for meta_key and meta_value) should
1478                  * be joined in parentheses.
1479                  */
1480                 if ( 1 < count( $sql_chunks['where'] ) ) {
1481                         $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' );
1482                 }
1483
1484                 return $sql_chunks;
1485         }
1486
1487         /**
1488          * Get a flattened list of sanitized meta clauses.
1489          *
1490          * This array should be used for clause lookup, as when the table alias and CAST type must be determined for
1491          * a value of 'orderby' corresponding to a meta clause.
1492          *
1493          * @since 4.2.0
1494          * @access public
1495          *
1496          * @return array Meta clauses.
1497          */
1498         public function get_clauses() {
1499                 return $this->clauses;
1500         }
1501
1502         /**
1503          * Identify an existing table alias that is compatible with the current
1504          * query clause.
1505          *
1506          * We avoid unnecessary table joins by allowing each clause to look for
1507          * an existing table alias that is compatible with the query that it
1508          * needs to perform.
1509          *
1510          * An existing alias is compatible if (a) it is a sibling of `$clause`
1511          * (ie, it's under the scope of the same relation), and (b) the combination
1512          * of operator and relation between the clauses allows for a shared table join.
1513          * In the case of {@see WP_Meta_Query}, this only applies to 'IN' clauses that
1514          * are connected by the relation 'OR'.
1515          *
1516          * @since 4.1.0
1517          * @access protected
1518          *
1519          * @param  array       $clause       Query clause.
1520          * @param  array       $parent_query Parent query of $clause.
1521          * @return string|bool Table alias if found, otherwise false.
1522          */
1523         protected function find_compatible_table_alias( $clause, $parent_query ) {
1524                 $alias = false;
1525
1526                 foreach ( $parent_query as $sibling ) {
1527                         // If the sibling has no alias yet, there's nothing to check.
1528                         if ( empty( $sibling['alias'] ) ) {
1529                                 continue;
1530                         }
1531
1532                         // We're only interested in siblings that are first-order clauses.
1533                         if ( ! is_array( $sibling ) || ! $this->is_first_order_clause( $sibling ) ) {
1534                                 continue;
1535                         }
1536
1537                         $compatible_compares = array();
1538
1539                         // Clauses connected by OR can share joins as long as they have "positive" operators.
1540                         if ( 'OR' === $parent_query['relation'] ) {
1541                                 $compatible_compares = array( '=', 'IN', 'BETWEEN', 'LIKE', 'REGEXP', 'RLIKE', '>', '>=', '<', '<=' );
1542
1543                         // Clauses joined by AND with "negative" operators share a join only if they also share a key.
1544                         } elseif ( isset( $sibling['key'] ) && isset( $clause['key'] ) && $sibling['key'] === $clause['key'] ) {
1545                                 $compatible_compares = array( '!=', 'NOT IN', 'NOT LIKE' );
1546                         }
1547
1548                         $clause_compare  = strtoupper( $clause['compare'] );
1549                         $sibling_compare = strtoupper( $sibling['compare'] );
1550                         if ( in_array( $clause_compare, $compatible_compares ) && in_array( $sibling_compare, $compatible_compares ) ) {
1551                                 $alias = $sibling['alias'];
1552                                 break;
1553                         }
1554                 }
1555
1556                 /**
1557                  * Filter the table alias identified as compatible with the current clause.
1558                  *
1559                  * @since 4.1.0
1560                  *
1561                  * @param string|bool $alias        Table alias, or false if none was found.
1562                  * @param array       $clause       First-order query clause.
1563                  * @param array       $parent_query Parent of $clause.
1564                  * @param object      $this         WP_Meta_Query object.
1565                  */
1566                 return apply_filters( 'meta_query_find_compatible_table_alias', $alias, $clause, $parent_query, $this ) ;
1567         }
1568 }
1569
1570 /**
1571  * Retrieve the name of the metadata table for the specified object type.
1572  *
1573  * @since 2.9.0
1574  *
1575  * @global wpdb $wpdb WordPress database abstraction object.
1576  *
1577  * @param string $type Type of object to get metadata table for (e.g., comment, post, or user)
1578  * @return mixed Metadata table name, or false if no metadata table exists
1579  */
1580 function _get_meta_table($type) {
1581         global $wpdb;
1582
1583         $table_name = $type . 'meta';
1584
1585         if ( empty($wpdb->$table_name) )
1586                 return false;
1587
1588         return $wpdb->$table_name;
1589 }
1590
1591 /**
1592  * Determine whether a meta key is protected.
1593  *
1594  * @since 3.1.3
1595  *
1596  * @param string      $meta_key Meta key
1597  * @param string|null $meta_type
1598  * @return bool True if the key is protected, false otherwise.
1599  */
1600 function is_protected_meta( $meta_key, $meta_type = null ) {
1601         $protected = ( '_' == $meta_key[0] );
1602
1603         /**
1604          * Filter whether a meta key is protected.
1605          *
1606          * @since 3.2.0
1607          *
1608          * @param bool   $protected Whether the key is protected. Default false.
1609          * @param string $meta_key  Meta key.
1610          * @param string $meta_type Meta type.
1611          */
1612         return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
1613 }
1614
1615 /**
1616  * Sanitize meta value.
1617  *
1618  * @since 3.1.3
1619  *
1620  * @param string $meta_key Meta key
1621  * @param mixed $meta_value Meta value to sanitize
1622  * @param string $meta_type Type of meta
1623  * @return mixed Sanitized $meta_value
1624  */
1625 function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
1626
1627         /**
1628          * Filter the sanitization of a specific meta key of a specific meta type.
1629          *
1630          * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
1631          * refer to the metadata object type (comment, post, or user) and the meta
1632          * key value,
1633          * respectively.
1634          *
1635          * @since 3.3.0
1636          *
1637          * @param mixed  $meta_value Meta value to sanitize.
1638          * @param string $meta_key   Meta key.
1639          * @param string $meta_type  Meta type.
1640          */
1641         return apply_filters( "sanitize_{$meta_type}_meta_{$meta_key}", $meta_value, $meta_key, $meta_type );
1642 }
1643
1644 /**
1645  * Register meta key
1646  *
1647  * @since 3.3.0
1648  *
1649  * @param string $meta_type Type of meta
1650  * @param string $meta_key Meta key
1651  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
1652  * @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.
1653  */
1654 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
1655         if ( is_callable( $sanitize_callback ) )
1656                 add_filter( "sanitize_{$meta_type}_meta_{$meta_key}", $sanitize_callback, 10, 3 );
1657
1658         if ( empty( $auth_callback ) ) {
1659                 if ( is_protected_meta( $meta_key, $meta_type ) )
1660                         $auth_callback = '__return_false';
1661                 else
1662                         $auth_callback = '__return_true';
1663         }
1664
1665         if ( is_callable( $auth_callback ) )
1666                 add_filter( "auth_{$meta_type}_meta_{$meta_key}", $auth_callback, 10, 6 );
1667 }