[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> meta.php (source)

   1  <?php
   2  /**
   3   * Core Metadata API
   4   *
   5   * Functions for retrieving and manipulating metadata of various WordPress object types. Metadata
   6   * for an object is a represented by a simple key-value pair. Objects may contain multiple
   7   * metadata entries that share the same key and differ only in their value.
   8   *
   9   * @package WordPress
  10   * @subpackage Meta
  11   */
  12  
  13  /**
  14   * Add metadata for the specified object.
  15   *
  16   * @since 2.9.0
  17   *
  18   * @global wpdb $wpdb WordPress database abstraction object.
  19   *
  20   * @param string $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
  21   * @param int    $object_id  ID of the object metadata is for
  22   * @param string $meta_key   Metadata key
  23   * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
  24   * @param bool   $unique     Optional, default is false.
  25   *                           Whether the specified metadata key should be unique for the object.
  26   *                           If true, and the object already has a value for the specified metadata key,
  27   *                           no change will be made.
  28   * @return int|false The meta ID on success, false on failure.
  29   */
  30  function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = false ) {
  31      global $wpdb;
  32  
  33      if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
  34          return false;
  35      }
  36  
  37      $object_id = absint( $object_id );
  38      if ( ! $object_id ) {
  39          return false;
  40      }
  41  
  42      $table = _get_meta_table( $meta_type );
  43      if ( ! $table ) {
  44          return false;
  45      }
  46  
  47      $meta_subtype = get_object_subtype( $meta_type, $object_id );
  48  
  49      $column = sanitize_key( $meta_type . '_id' );
  50  
  51      // expected_slashed ($meta_key)
  52      $meta_key   = wp_unslash( $meta_key );
  53      $meta_value = wp_unslash( $meta_value );
  54      $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type, $meta_subtype );
  55  
  56      /**
  57       * Filters whether to add metadata of a specific type.
  58       *
  59       * The dynamic portion of the hook, `$meta_type`, refers to the meta
  60       * object type (comment, post, term, or user). Returning a non-null value
  61       * will effectively short-circuit the function.
  62       *
  63       * @since 3.1.0
  64       *
  65       * @param null|bool $check      Whether to allow adding metadata for the given type.
  66       * @param int       $object_id  Object ID.
  67       * @param string    $meta_key   Meta key.
  68       * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
  69       * @param bool      $unique     Whether the specified meta key should be unique
  70       *                              for the object. Optional. Default false.
  71       */
  72      $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique );
  73      if ( null !== $check ) {
  74          return $check;
  75      }
  76  
  77      if ( $unique && $wpdb->get_var(
  78          $wpdb->prepare(
  79              "SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",
  80              $meta_key,
  81              $object_id
  82          )
  83      ) ) {
  84          return false;
  85      }
  86  
  87      $_meta_value = $meta_value;
  88      $meta_value  = maybe_serialize( $meta_value );
  89  
  90      /**
  91       * Fires immediately before meta of a specific type is added.
  92       *
  93       * The dynamic portion of the hook, `$meta_type`, refers to the meta
  94       * object type (comment, post, term, or user).
  95       *
  96       * @since 3.1.0
  97       *
  98       * @param int    $object_id   Object ID.
  99       * @param string $meta_key    Meta key.
 100       * @param mixed  $_meta_value Meta value.
 101       */
 102      do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value );
 103  
 104      $result = $wpdb->insert(
 105          $table,
 106          array(
 107              $column      => $object_id,
 108              'meta_key'   => $meta_key,
 109              'meta_value' => $meta_value,
 110          )
 111      );
 112  
 113      if ( ! $result ) {
 114          return false;
 115      }
 116  
 117      $mid = (int) $wpdb->insert_id;
 118  
 119      wp_cache_delete( $object_id, $meta_type . '_meta' );
 120  
 121      /**
 122       * Fires immediately after meta of a specific type is added.
 123       *
 124       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 125       * object type (comment, post, term, or user).
 126       *
 127       * @since 2.9.0
 128       *
 129       * @param int    $mid         The meta ID after successful update.
 130       * @param int    $object_id   Object ID.
 131       * @param string $meta_key    Meta key.
 132       * @param mixed  $_meta_value Meta value.
 133       */
 134      do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
 135  
 136      return $mid;
 137  }
 138  
 139  /**
 140   * Update metadata for the specified object. If no value already exists for the specified object
 141   * ID and metadata key, the metadata will be added.
 142   *
 143   * @since 2.9.0
 144   *
 145   * @global wpdb $wpdb WordPress database abstraction object.
 146   *
 147   * @param string $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
 148   * @param int    $object_id  ID of the object metadata is for
 149   * @param string $meta_key   Metadata key
 150   * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
 151   * @param mixed  $prev_value Optional. If specified, only update existing metadata entries with
 152   *                           the specified value. Otherwise, update all entries.
 153   * @return int|bool The new meta field ID if a field with the given key didn't exist and was
 154   *                  therefore added, true on successful update, false on failure.
 155   */
 156  function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) {
 157      global $wpdb;
 158  
 159      if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) {
 160          return false;
 161      }
 162  
 163      $object_id = absint( $object_id );
 164      if ( ! $object_id ) {
 165          return false;
 166      }
 167  
 168      $table = _get_meta_table( $meta_type );
 169      if ( ! $table ) {
 170          return false;
 171      }
 172  
 173      $meta_subtype = get_object_subtype( $meta_type, $object_id );
 174  
 175      $column    = sanitize_key( $meta_type . '_id' );
 176      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 177  
 178      // expected_slashed ($meta_key)
 179      $raw_meta_key = $meta_key;
 180      $meta_key     = wp_unslash( $meta_key );
 181      $passed_value = $meta_value;
 182      $meta_value   = wp_unslash( $meta_value );
 183      $meta_value   = sanitize_meta( $meta_key, $meta_value, $meta_type, $meta_subtype );
 184  
 185      /**
 186       * Filters whether to update metadata of a specific type.
 187       *
 188       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 189       * object type (comment, post, term, or user). Returning a non-null value
 190       * will effectively short-circuit the function.
 191       *
 192       * @since 3.1.0
 193       *
 194       * @param null|bool $check      Whether to allow updating metadata for the given type.
 195       * @param int       $object_id  Object ID.
 196       * @param string    $meta_key   Meta key.
 197       * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
 198       * @param mixed     $prev_value Optional. If specified, only update existing
 199       *                              metadata entries with the specified value.
 200       *                              Otherwise, update all entries.
 201       */
 202      $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );
 203      if ( null !== $check ) {
 204          return (bool) $check;
 205      }
 206  
 207      // Compare existing value to new value if no prev value given and the key exists only once.
 208      if ( empty( $prev_value ) ) {
 209          $old_value = get_metadata( $meta_type, $object_id, $meta_key );
 210          if ( count( $old_value ) == 1 ) {
 211              if ( $old_value[0] === $meta_value ) {
 212                  return false;
 213              }
 214          }
 215      }
 216  
 217      $meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) );
 218      if ( empty( $meta_ids ) ) {
 219          return add_metadata( $meta_type, $object_id, $raw_meta_key, $passed_value );
 220      }
 221  
 222      $_meta_value = $meta_value;
 223      $meta_value  = maybe_serialize( $meta_value );
 224  
 225      $data  = compact( 'meta_value' );
 226      $where = array(
 227          $column    => $object_id,
 228          'meta_key' => $meta_key,
 229      );
 230  
 231      if ( ! empty( $prev_value ) ) {
 232          $prev_value          = maybe_serialize( $prev_value );
 233          $where['meta_value'] = $prev_value;
 234      }
 235  
 236      foreach ( $meta_ids as $meta_id ) {
 237          /**
 238           * Fires immediately before updating metadata of a specific type.
 239           *
 240           * The dynamic portion of the hook, `$meta_type`, refers to the meta
 241           * object type (comment, post, term, or user).
 242           *
 243           * @since 2.9.0
 244           *
 245           * @param int    $meta_id     ID of the metadata entry to update.
 246           * @param int    $object_id   Object ID.
 247           * @param string $meta_key    Meta key.
 248           * @param mixed  $_meta_value Meta value.
 249           */
 250          do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 251  
 252          if ( 'post' == $meta_type ) {
 253              /**
 254               * Fires immediately before updating a post's metadata.
 255               *
 256               * @since 2.9.0
 257               *
 258               * @param int    $meta_id    ID of metadata entry to update.
 259               * @param int    $object_id  Post ID.
 260               * @param string $meta_key   Meta key.
 261               * @param mixed  $meta_value Meta value. This will be a PHP-serialized string representation of the value if
 262               *                           the value is an array, an object, or itself a PHP-serialized string.
 263               */
 264              do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 265          }
 266      }
 267  
 268      $result = $wpdb->update( $table, $data, $where );
 269      if ( ! $result ) {
 270          return false;
 271      }
 272  
 273      wp_cache_delete( $object_id, $meta_type . '_meta' );
 274  
 275      foreach ( $meta_ids as $meta_id ) {
 276          /**
 277           * Fires immediately after updating metadata of a specific type.
 278           *
 279           * The dynamic portion of the hook, `$meta_type`, refers to the meta
 280           * object type (comment, post, term, or user).
 281           *
 282           * @since 2.9.0
 283           *
 284           * @param int    $meta_id     ID of updated metadata entry.
 285           * @param int    $object_id   Object ID.
 286           * @param string $meta_key    Meta key.
 287           * @param mixed  $_meta_value Meta value.
 288           */
 289          do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 290  
 291          if ( 'post' == $meta_type ) {
 292              /**
 293               * Fires immediately after updating a post's metadata.
 294               *
 295               * @since 2.9.0
 296               *
 297               * @param int    $meta_id    ID of updated metadata entry.
 298               * @param int    $object_id  Post ID.
 299               * @param string $meta_key   Meta key.
 300               * @param mixed  $meta_value Meta value. This will be a PHP-serialized string representation of the value if
 301               *                           the value is an array, an object, or itself a PHP-serialized string.
 302               */
 303              do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 304          }
 305      }
 306  
 307      return true;
 308  }
 309  
 310  /**
 311   * Delete metadata for the specified object.
 312   *
 313   * @since 2.9.0
 314   *
 315   * @global wpdb $wpdb WordPress database abstraction object.
 316   *
 317   * @param string $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
 318   * @param int    $object_id  ID of the object metadata is for
 319   * @param string $meta_key   Metadata key
 320   * @param mixed  $meta_value Optional. Metadata value. Must be serializable if non-scalar. If specified, only delete
 321   *                           metadata entries with this value. Otherwise, delete all entries with the specified meta_key.
 322   *                           Pass `null`, `false`, or an empty string to skip this check. (For backward compatibility,
 323   *                           it is not possible to pass an empty string to delete those entries with an empty string
 324   *                           for a value.)
 325   * @param bool   $delete_all Optional, default is false. If true, delete matching metadata entries for all objects,
 326   *                           ignoring the specified object_id. Otherwise, only delete matching metadata entries for
 327   *                           the specified object_id.
 328   * @return bool True on successful delete, false on failure.
 329   */
 330  function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false ) {
 331      global $wpdb;
 332  
 333      if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
 334          return false;
 335      }
 336  
 337      $object_id = absint( $object_id );
 338      if ( ! $object_id && ! $delete_all ) {
 339          return false;
 340      }
 341  
 342      $table = _get_meta_table( $meta_type );
 343      if ( ! $table ) {
 344          return false;
 345      }
 346  
 347      $type_column = sanitize_key( $meta_type . '_id' );
 348      $id_column   = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 349      // expected_slashed ($meta_key)
 350      $meta_key   = wp_unslash( $meta_key );
 351      $meta_value = wp_unslash( $meta_value );
 352  
 353      /**
 354       * Filters whether to delete metadata of a specific type.
 355       *
 356       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 357       * object type (comment, post, term, or user). Returning a non-null value
 358       * will effectively short-circuit the function.
 359       *
 360       * @since 3.1.0
 361       *
 362       * @param null|bool $delete     Whether to allow metadata deletion of the given type.
 363       * @param int       $object_id  Object ID.
 364       * @param string    $meta_key   Meta key.
 365       * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
 366       * @param bool      $delete_all Whether to delete the matching metadata entries
 367       *                              for all objects, ignoring the specified $object_id.
 368       *                              Default false.
 369       */
 370      $check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
 371      if ( null !== $check ) {
 372          return (bool) $check;
 373      }
 374  
 375      $_meta_value = $meta_value;
 376      $meta_value  = maybe_serialize( $meta_value );
 377  
 378      $query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );
 379  
 380      if ( ! $delete_all ) {
 381          $query .= $wpdb->prepare( " AND $type_column = %d", $object_id );
 382      }
 383  
 384      if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value ) {
 385          $query .= $wpdb->prepare( ' AND meta_value = %s', $meta_value );
 386      }
 387  
 388      $meta_ids = $wpdb->get_col( $query );
 389      if ( ! count( $meta_ids ) ) {
 390          return false;
 391      }
 392  
 393      if ( $delete_all ) {
 394          if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value ) {
 395              $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s AND meta_value = %s", $meta_key, $meta_value ) );
 396          } else {
 397              $object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
 398          }
 399      }
 400  
 401      /**
 402       * Fires immediately before deleting metadata of a specific type.
 403       *
 404       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 405       * object type (comment, post, term, or user).
 406       *
 407       * @since 3.1.0
 408       *
 409       * @param string[] $meta_ids    An array of metadata entry IDs to delete.
 410       * @param int      $object_id   Object ID.
 411       * @param string   $meta_key    Meta key.
 412       * @param mixed    $_meta_value Meta value.
 413       */
 414      do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 415  
 416      // Old-style action.
 417      if ( 'post' == $meta_type ) {
 418          /**
 419           * Fires immediately before deleting metadata for a post.
 420           *
 421           * @since 2.9.0
 422           *
 423           * @param string[] $meta_ids An array of metadata entry IDs to delete.
 424           */
 425          do_action( 'delete_postmeta', $meta_ids );
 426      }
 427  
 428      $query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . ' )';
 429  
 430      $count = $wpdb->query( $query );
 431  
 432      if ( ! $count ) {
 433          return false;
 434      }
 435  
 436      if ( $delete_all ) {
 437          foreach ( (array) $object_ids as $o_id ) {
 438              wp_cache_delete( $o_id, $meta_type . '_meta' );
 439          }
 440      } else {
 441          wp_cache_delete( $object_id, $meta_type . '_meta' );
 442      }
 443  
 444      /**
 445       * Fires immediately after deleting metadata of a specific type.
 446       *
 447       * The dynamic portion of the hook name, `$meta_type`, refers to the meta
 448       * object type (comment, post, term, or user).
 449       *
 450       * @since 2.9.0
 451       *
 452       * @param string[] $meta_ids    An array of metadata entry IDs to delete.
 453       * @param int      $object_id   Object ID.
 454       * @param string   $meta_key    Meta key.
 455       * @param mixed    $_meta_value Meta value.
 456       */
 457      do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );
 458  
 459      // Old-style action.
 460      if ( 'post' == $meta_type ) {
 461          /**
 462           * Fires immediately after deleting metadata for a post.
 463           *
 464           * @since 2.9.0
 465           *
 466           * @param string[] $meta_ids An array of metadata entry IDs to delete.
 467           */
 468          do_action( 'deleted_postmeta', $meta_ids );
 469      }
 470  
 471      return true;
 472  }
 473  
 474  /**
 475   * Retrieve metadata for the specified object.
 476   *
 477   * @since 2.9.0
 478   *
 479   * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 480   * @param int    $object_id ID of the object metadata is for
 481   * @param string $meta_key  Optional. Metadata key. If not specified, retrieve all metadata for
 482   *                          the specified object.
 483   * @param bool   $single    Optional, default is false.
 484   *                          If true, return only the first value of the specified meta_key.
 485   *                          This parameter has no effect if meta_key is not specified.
 486   * @return mixed Single metadata value, or array of values
 487   */
 488  function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
 489      if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 490          return false;
 491      }
 492  
 493      $object_id = absint( $object_id );
 494      if ( ! $object_id ) {
 495          return false;
 496      }
 497  
 498      /**
 499       * Filters whether to retrieve metadata of a specific type.
 500       *
 501       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 502       * object type (comment, post, term, or user). Returning a non-null value
 503       * will effectively short-circuit the function.
 504       *
 505       * @since 3.1.0
 506       *
 507       * @param null|array|string $value     The value get_metadata() should return - a single metadata value,
 508       *                                     or an array of values.
 509       * @param int               $object_id Object ID.
 510       * @param string            $meta_key  Meta key.
 511       * @param bool              $single    Whether to return only the first value of the specified $meta_key.
 512       */
 513      $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single );
 514      if ( null !== $check ) {
 515          if ( $single && is_array( $check ) ) {
 516              return $check[0];
 517          } else {
 518              return $check;
 519          }
 520      }
 521  
 522      $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
 523  
 524      if ( ! $meta_cache ) {
 525          $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 526          if ( isset( $meta_cache[ $object_id ] ) ) {
 527              $meta_cache = $meta_cache[ $object_id ];
 528          } else {
 529              $meta_cache = null;
 530          }
 531      }
 532  
 533      if ( ! $meta_key ) {
 534          return $meta_cache;
 535      }
 536  
 537      if ( isset( $meta_cache[ $meta_key ] ) ) {
 538          if ( $single ) {
 539              return maybe_unserialize( $meta_cache[ $meta_key ][0] );
 540          } else {
 541              return array_map( 'maybe_unserialize', $meta_cache[ $meta_key ] );
 542          }
 543      }
 544  
 545      if ( $single ) {
 546          return '';
 547      } else {
 548          return array();
 549      }
 550  }
 551  
 552  /**
 553   * Determine if a meta key is set for a given object
 554   *
 555   * @since 3.3.0
 556   *
 557   * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 558   * @param int    $object_id ID of the object metadata is for
 559   * @param string $meta_key  Metadata key.
 560   * @return bool True of the key is set, false if not.
 561   */
 562  function metadata_exists( $meta_type, $object_id, $meta_key ) {
 563      if ( ! $meta_type || ! is_numeric( $object_id ) ) {
 564          return false;
 565      }
 566  
 567      $object_id = absint( $object_id );
 568      if ( ! $object_id ) {
 569          return false;
 570      }
 571  
 572      /** This filter is documented in wp-includes/meta.php */
 573      $check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, true );
 574      if ( null !== $check ) {
 575          return (bool) $check;
 576      }
 577  
 578      $meta_cache = wp_cache_get( $object_id, $meta_type . '_meta' );
 579  
 580      if ( ! $meta_cache ) {
 581          $meta_cache = update_meta_cache( $meta_type, array( $object_id ) );
 582          $meta_cache = $meta_cache[ $object_id ];
 583      }
 584  
 585      if ( isset( $meta_cache[ $meta_key ] ) ) {
 586          return true;
 587      }
 588  
 589      return false;
 590  }
 591  
 592  /**
 593   * Get meta data by meta ID
 594   *
 595   * @since 3.3.0
 596   *
 597   * @global wpdb $wpdb WordPress database abstraction object.
 598   *
 599   * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 600   * @param int    $meta_id   ID for a specific meta row
 601   * @return object|false Meta object or false.
 602   */
 603  function get_metadata_by_mid( $meta_type, $meta_id ) {
 604      global $wpdb;
 605  
 606      if ( ! $meta_type || ! is_numeric( $meta_id ) || floor( $meta_id ) != $meta_id ) {
 607          return false;
 608      }
 609  
 610      $meta_id = intval( $meta_id );
 611      if ( $meta_id <= 0 ) {
 612          return false;
 613      }
 614  
 615      $table = _get_meta_table( $meta_type );
 616      if ( ! $table ) {
 617          return false;
 618      }
 619  
 620      $id_column = ( 'user' == $meta_type ) ? 'umeta_id' : 'meta_id';
 621  
 622      /**
 623       * Filters whether to retrieve metadata of a specific type by meta ID.
 624       *
 625       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 626       * object type (comment, post, term, or user). Returning a non-null value
 627       * will effectively short-circuit the function.
 628       *
 629       * @since 5.0.0
 630       *
 631       * @param mixed $value    The value get_metadata_by_mid() should return.
 632       * @param int   $meta_id  Meta ID.
 633       */
 634      $check = apply_filters( "get_{$meta_type}_metadata_by_mid", null, $meta_id );
 635      if ( null !== $check ) {
 636          return $check;
 637      }
 638  
 639      $meta = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $table WHERE $id_column = %d", $meta_id ) );
 640  
 641      if ( empty( $meta ) ) {
 642          return false;
 643      }
 644  
 645      if ( isset( $meta->meta_value ) ) {
 646          $meta->meta_value = maybe_unserialize( $meta->meta_value );
 647      }
 648  
 649      return $meta;
 650  }
 651  
 652  /**
 653   * Update meta data by meta ID
 654   *
 655   * @since 3.3.0
 656   *
 657   * @global wpdb $wpdb WordPress database abstraction object.
 658   *
 659   * @param string $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
 660   * @param int    $meta_id    ID for a specific meta row
 661   * @param string $meta_value Metadata value
 662   * @param string $meta_key   Optional, you can provide a meta key to update it
 663   * @return bool True on successful update, false on failure.
 664   */
 665  function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = false ) {
 666      global $wpdb;
 667  
 668      // Make sure everything is valid.
 669      if ( ! $meta_type || ! is_numeric( $meta_id ) || floor( $meta_id ) != $meta_id ) {
 670          return false;
 671      }
 672  
 673      $meta_id = intval( $meta_id );
 674      if ( $meta_id <= 0 ) {
 675          return false;
 676      }
 677  
 678      $table = _get_meta_table( $meta_type );
 679      if ( ! $table ) {
 680          return false;
 681      }
 682  
 683      $column    = sanitize_key( $meta_type . '_id' );
 684      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 685  
 686      /**
 687       * Filters whether to update metadata of a specific type by meta ID.
 688       *
 689       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 690       * object type (comment, post, term, or user). Returning a non-null value
 691       * will effectively short-circuit the function.
 692       *
 693       * @since 5.0.0
 694       *
 695       * @param null|bool   $check      Whether to allow updating metadata for the given type.
 696       * @param int         $meta_id    Meta ID.
 697       * @param mixed       $meta_value Meta value. Must be serializable if non-scalar.
 698       * @param string|bool $meta_key   Meta key, if provided.
 699       */
 700      $check = apply_filters( "update_{$meta_type}_metadata_by_mid", null, $meta_id, $meta_value, $meta_key );
 701      if ( null !== $check ) {
 702          return (bool) $check;
 703      }
 704  
 705      // Fetch the meta and go on if it's found.
 706      $meta = get_metadata_by_mid( $meta_type, $meta_id );
 707      if ( $meta ) {
 708          $original_key = $meta->meta_key;
 709          $object_id    = $meta->{$column};
 710  
 711          // If a new meta_key (last parameter) was specified, change the meta key,
 712          // otherwise use the original key in the update statement.
 713          if ( false === $meta_key ) {
 714              $meta_key = $original_key;
 715          } elseif ( ! is_string( $meta_key ) ) {
 716              return false;
 717          }
 718  
 719          $meta_subtype = get_object_subtype( $meta_type, $object_id );
 720  
 721          // Sanitize the meta
 722          $_meta_value = $meta_value;
 723          $meta_value  = sanitize_meta( $meta_key, $meta_value, $meta_type, $meta_subtype );
 724          $meta_value  = maybe_serialize( $meta_value );
 725  
 726          // Format the data query arguments.
 727          $data = array(
 728              'meta_key'   => $meta_key,
 729              'meta_value' => $meta_value,
 730          );
 731  
 732          // Format the where query arguments.
 733          $where               = array();
 734          $where[ $id_column ] = $meta_id;
 735  
 736          /** This action is documented in wp-includes/meta.php */
 737          do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 738  
 739          if ( 'post' == $meta_type ) {
 740              /** This action is documented in wp-includes/meta.php */
 741              do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 742          }
 743  
 744          // Run the update query, all fields in $data are %s, $where is a %d.
 745          $result = $wpdb->update( $table, $data, $where, '%s', '%d' );
 746          if ( ! $result ) {
 747              return false;
 748          }
 749  
 750          // Clear the caches.
 751          wp_cache_delete( $object_id, $meta_type . '_meta' );
 752  
 753          /** This action is documented in wp-includes/meta.php */
 754          do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value );
 755  
 756          if ( 'post' == $meta_type ) {
 757              /** This action is documented in wp-includes/meta.php */
 758              do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value );
 759          }
 760  
 761          return true;
 762      }
 763  
 764      // And if the meta was not found.
 765      return false;
 766  }
 767  
 768  /**
 769   * Delete meta data by meta ID
 770   *
 771   * @since 3.3.0
 772   *
 773   * @global wpdb $wpdb WordPress database abstraction object.
 774   *
 775   * @param string $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
 776   * @param int    $meta_id   ID for a specific meta row
 777   * @return bool True on successful delete, false on failure.
 778   */
 779  function delete_metadata_by_mid( $meta_type, $meta_id ) {
 780      global $wpdb;
 781  
 782      // Make sure everything is valid.
 783      if ( ! $meta_type || ! is_numeric( $meta_id ) || floor( $meta_id ) != $meta_id ) {
 784          return false;
 785      }
 786  
 787      $meta_id = intval( $meta_id );
 788      if ( $meta_id <= 0 ) {
 789          return false;
 790      }
 791  
 792      $table = _get_meta_table( $meta_type );
 793      if ( ! $table ) {
 794          return false;
 795      }
 796  
 797      // object and id columns
 798      $column    = sanitize_key( $meta_type . '_id' );
 799      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 800  
 801      /**
 802       * Filters whether to delete metadata of a specific type by meta ID.
 803       *
 804       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 805       * object type (comment, post, term, or user). Returning a non-null value
 806       * will effectively short-circuit the function.
 807       *
 808       * @since 5.0.0
 809       *
 810       * @param null|bool $delete  Whether to allow metadata deletion of the given type.
 811       * @param int       $meta_id Meta ID.
 812       */
 813      $check = apply_filters( "delete_{$meta_type}_metadata_by_mid", null, $meta_id );
 814      if ( null !== $check ) {
 815          return (bool) $check;
 816      }
 817  
 818      // Fetch the meta and go on if it's found.
 819      $meta = get_metadata_by_mid( $meta_type, $meta_id );
 820      if ( $meta ) {
 821          $object_id = (int) $meta->{$column};
 822  
 823          /** This action is documented in wp-includes/meta.php */
 824          do_action( "delete_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 825  
 826          // Old-style action.
 827          if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 828              /**
 829               * Fires immediately before deleting post or comment metadata of a specific type.
 830               *
 831               * The dynamic portion of the hook, `$meta_type`, refers to the meta
 832               * object type (post or comment).
 833               *
 834               * @since 3.4.0
 835               *
 836               * @param int $meta_id ID of the metadata entry to delete.
 837               */
 838              do_action( "delete_{$meta_type}meta", $meta_id );
 839          }
 840  
 841          // Run the query, will return true if deleted, false otherwise
 842          $result = (bool) $wpdb->delete( $table, array( $id_column => $meta_id ) );
 843  
 844          // Clear the caches.
 845          wp_cache_delete( $object_id, $meta_type . '_meta' );
 846  
 847          /** This action is documented in wp-includes/meta.php */
 848          do_action( "deleted_{$meta_type}_meta", (array) $meta_id, $object_id, $meta->meta_key, $meta->meta_value );
 849  
 850          // Old-style action.
 851          if ( 'post' == $meta_type || 'comment' == $meta_type ) {
 852              /**
 853               * Fires immediately after deleting post or comment metadata of a specific type.
 854               *
 855               * The dynamic portion of the hook, `$meta_type`, refers to the meta
 856               * object type (post or comment).
 857               *
 858               * @since 3.4.0
 859               *
 860               * @param int $meta_ids Deleted metadata entry ID.
 861               */
 862              do_action( "deleted_{$meta_type}meta", $meta_id );
 863          }
 864  
 865          return $result;
 866  
 867      }
 868  
 869      // Meta id was not found.
 870      return false;
 871  }
 872  
 873  /**
 874   * Update the metadata cache for the specified objects.
 875   *
 876   * @since 2.9.0
 877   *
 878   * @global wpdb $wpdb WordPress database abstraction object.
 879   *
 880   * @param string       $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
 881   * @param string|int[] $object_ids Array or comma delimited list of object IDs to update cache for.
 882   * @return array|false Metadata cache for the specified objects, or false on failure.
 883   */
 884  function update_meta_cache( $meta_type, $object_ids ) {
 885      global $wpdb;
 886  
 887      if ( ! $meta_type || ! $object_ids ) {
 888          return false;
 889      }
 890  
 891      $table = _get_meta_table( $meta_type );
 892      if ( ! $table ) {
 893          return false;
 894      }
 895  
 896      $column = sanitize_key( $meta_type . '_id' );
 897  
 898      if ( ! is_array( $object_ids ) ) {
 899          $object_ids = preg_replace( '|[^0-9,]|', '', $object_ids );
 900          $object_ids = explode( ',', $object_ids );
 901      }
 902  
 903      $object_ids = array_map( 'intval', $object_ids );
 904  
 905      /**
 906       * Filters whether to update the metadata cache of a specific type.
 907       *
 908       * The dynamic portion of the hook, `$meta_type`, refers to the meta
 909       * object type (comment, post, term, or user). Returning a non-null value
 910       * will effectively short-circuit the function.
 911       *
 912       * @since 5.0.0
 913       *
 914       * @param mixed $check      Whether to allow updating the meta cache of the given type.
 915       * @param int[] $object_ids Array of object IDs to update the meta cache for.
 916       */
 917      $check = apply_filters( "update_{$meta_type}_metadata_cache", null, $object_ids );
 918      if ( null !== $check ) {
 919          return (bool) $check;
 920      }
 921  
 922      $cache_key = $meta_type . '_meta';
 923      $ids       = array();
 924      $cache     = array();
 925      foreach ( $object_ids as $id ) {
 926          $cached_object = wp_cache_get( $id, $cache_key );
 927          if ( false === $cached_object ) {
 928              $ids[] = $id;
 929          } else {
 930              $cache[ $id ] = $cached_object;
 931          }
 932      }
 933  
 934      if ( empty( $ids ) ) {
 935          return $cache;
 936      }
 937  
 938      // Get meta info
 939      $id_list   = join( ',', $ids );
 940      $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id';
 941      $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 );
 942  
 943      if ( ! empty( $meta_list ) ) {
 944          foreach ( $meta_list as $metarow ) {
 945              $mpid = intval( $metarow[ $column ] );
 946              $mkey = $metarow['meta_key'];
 947              $mval = $metarow['meta_value'];
 948  
 949              // Force subkeys to be array type:
 950              if ( ! isset( $cache[ $mpid ] ) || ! is_array( $cache[ $mpid ] ) ) {
 951                  $cache[ $mpid ] = array();
 952              }
 953              if ( ! isset( $cache[ $mpid ][ $mkey ] ) || ! is_array( $cache[ $mpid ][ $mkey ] ) ) {
 954                  $cache[ $mpid ][ $mkey ] = array();
 955              }
 956  
 957              // Add a value to the current pid/key:
 958              $cache[ $mpid ][ $mkey ][] = $mval;
 959          }
 960      }
 961  
 962      foreach ( $ids as $id ) {
 963          if ( ! isset( $cache[ $id ] ) ) {
 964              $cache[ $id ] = array();
 965          }
 966          wp_cache_add( $id, $cache[ $id ], $cache_key );
 967      }
 968  
 969      return $cache;
 970  }
 971  
 972  /**
 973   * Retrieves the queue for lazy-loading metadata.
 974   *
 975   * @since 4.5.0
 976   *
 977   * @return WP_Metadata_Lazyloader $lazyloader Metadata lazyloader queue.
 978   */
 979  function wp_metadata_lazyloader() {
 980      static $wp_metadata_lazyloader;
 981  
 982      if ( null === $wp_metadata_lazyloader ) {
 983          $wp_metadata_lazyloader = new WP_Metadata_Lazyloader();
 984      }
 985  
 986      return $wp_metadata_lazyloader;
 987  }
 988  
 989  /**
 990   * Given a meta query, generates SQL clauses to be appended to a main query.
 991   *
 992   * @since 3.2.0
 993   *
 994   * @see WP_Meta_Query
 995   *
 996   * @param array $meta_query         A meta query.
 997   * @param string $type              Type of meta.
 998   * @param string $primary_table     Primary database table name.
 999   * @param string $primary_id_column Primary ID column name.
1000   * @param object $context           Optional. The main query object
1001   * @return array Associative array of `JOIN` and `WHERE` SQL.
1002   */
1003  function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) {
1004      $meta_query_obj = new WP_Meta_Query( $meta_query );
1005      return $meta_query_obj->get_sql( $type, $primary_table, $primary_id_column, $context );
1006  }
1007  
1008  /**
1009   * Retrieve the name of the metadata table for the specified object type.
1010   *
1011   * @since 2.9.0
1012   *
1013   * @global wpdb $wpdb WordPress database abstraction object.
1014   *
1015   * @param string $type Type of object to get metadata table for (e.g., comment, post, term, or user).
1016   * @return string|false Metadata table name, or false if no metadata table exists
1017   */
1018  function _get_meta_table( $type ) {
1019      global $wpdb;
1020  
1021      $table_name = $type . 'meta';
1022  
1023      if ( empty( $wpdb->$table_name ) ) {
1024          return false;
1025      }
1026  
1027      return $wpdb->$table_name;
1028  }
1029  
1030  /**
1031   * Determines whether a meta key is considered protected.
1032   *
1033   * @since 3.1.3
1034   *
1035   * @param string      $meta_key  Meta key.
1036   * @param string|null $meta_type Optional. Type of object metadata is for (e.g., comment, post, term, or user).
1037   * @return bool Whether the meta key is considered protected.
1038   */
1039  function is_protected_meta( $meta_key, $meta_type = null ) {
1040      $protected = ( '_' == $meta_key[0] );
1041  
1042      /**
1043       * Filters whether a meta key is considered protected.
1044       *
1045       * @since 3.2.0
1046       *
1047       * @param bool        $protected Whether the key is considered protected.
1048       * @param string      $meta_key  Meta key.
1049       * @param string|null $meta_type Type of object metadata is for (e.g., comment, post, term, or user).
1050       */
1051      return apply_filters( 'is_protected_meta', $protected, $meta_key, $meta_type );
1052  }
1053  
1054  /**
1055   * Sanitize meta value.
1056   *
1057   * @since 3.1.3
1058   * @since 4.9.8 The `$object_subtype` parameter was added.
1059   *
1060   * @param string $meta_key       Meta key.
1061   * @param mixed  $meta_value     Meta value to sanitize.
1062   * @param string $object_type    Type of object the meta is registered to.
1063   * @param string $object_subtype Optional. The subtype of the object type.
1064   *
1065   * @return mixed Sanitized $meta_value.
1066   */
1067  function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) {
1068      if ( ! empty( $object_subtype ) && has_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}" ) ) {
1069  
1070          /**
1071           * Filters the sanitization of a specific meta key of a specific meta type and subtype.
1072           *
1073           * The dynamic portions of the hook name, `$object_type`, `$meta_key`,
1074           * and `$object_subtype`, refer to the metadata object type (comment, post, term, or user),
1075           * the meta key value, and the object subtype respectively.
1076           *
1077           * @since 4.9.8
1078           *
1079           * @param mixed  $meta_value     Meta value to sanitize.
1080           * @param string $meta_key       Meta key.
1081           * @param string $object_type    Object type.
1082           * @param string $object_subtype Object subtype.
1083           */
1084          return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $meta_value, $meta_key, $object_type, $object_subtype );
1085      }
1086  
1087      /**
1088       * Filters the sanitization of a specific meta key of a specific meta type.
1089       *
1090       * The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
1091       * refer to the metadata object type (comment, post, term, or user) and the meta
1092       * key value, respectively.
1093       *
1094       * @since 3.3.0
1095       *
1096       * @param mixed  $meta_value      Meta value to sanitize.
1097       * @param string $meta_key        Meta key.
1098       * @param string $object_type     Object type.
1099       */
1100      return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type );
1101  }
1102  
1103  /**
1104   * Registers a meta key.
1105   *
1106   * It is recommended to register meta keys for a specific combination of object type and object subtype. If passing
1107   * an object subtype is omitted, the meta key will be registered for the entire object type, however it can be partly
1108   * overridden in case a more specific meta key of the same name exists for the same object type and a subtype.
1109   *
1110   * If an object type does not support any subtypes, such as users or comments, you should commonly call this function
1111   * without passing a subtype.
1112   *
1113   * @since 3.3.0
1114   * @since 4.6.0 {@link https://core.trac.wordpress.org/ticket/35658 Modified
1115   *              to support an array of data to attach to registered meta keys}. Previous arguments for
1116   *              `$sanitize_callback` and `$auth_callback` have been folded into this array.
1117   * @since 4.9.8 The `$object_subtype` argument was added to the arguments array.
1118   * @since 5.3.0 Valid meta types expanded to include "array" and "object".
1119   *
1120   * @param string $object_type    Type of object this meta is registered to.
1121   * @param string $meta_key       Meta key to register.
1122   * @param array  $args {
1123   *     Data used to describe the meta key when registered.
1124   *
1125   *     @type string     $object_subtype    A subtype; e.g. if the object type is "post", the post type. If left empty,
1126   *                                         the meta key will be registered on the entire object type. Default empty.
1127   *     @type string     $type              The type of data associated with this meta key.
1128   *                                         Valid values are 'string', 'boolean', 'integer', 'number', 'array', and 'object'.
1129   *     @type string     $description       A description of the data attached to this meta key.
1130   *     @type bool       $single            Whether the meta key has one value per object, or an array of values per object.
1131   *     @type string     $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
1132   *     @type string     $auth_callback     Optional. A function or method to call when performing edit_post_meta,
1133   *                                         add_post_meta, and delete_post_meta capability checks.
1134   *     @type bool|array $show_in_rest      Whether data associated with this meta key can be considered public and
1135   *                                         should be accessible via the REST API. A custom post type must also declare
1136   *                                         support for custom fields for registered meta to be accessible via REST.
1137   *                                         When registering complex meta values this argument may optionally be an
1138   *                                         array with 'schema' or 'prepare_callback' keys instead of a boolean.
1139   * }
1140   * @param string|array $deprecated Deprecated. Use `$args` instead.
1141   *
1142   * @return bool True if the meta key was successfully registered in the global array, false if not.
1143   *                       Registering a meta key with distinct sanitize and auth callbacks will fire those
1144   *                       callbacks, but will not add to the global registry.
1145   */
1146  function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
1147      global $wp_meta_keys;
1148  
1149      if ( ! is_array( $wp_meta_keys ) ) {
1150          $wp_meta_keys = array();
1151      }
1152  
1153      $defaults = array(
1154          'object_subtype'    => '',
1155          'type'              => 'string',
1156          'description'       => '',
1157          'single'            => false,
1158          'sanitize_callback' => null,
1159          'auth_callback'     => null,
1160          'show_in_rest'      => false,
1161      );
1162  
1163      // There used to be individual args for sanitize and auth callbacks
1164      $has_old_sanitize_cb = false;
1165      $has_old_auth_cb     = false;
1166  
1167      if ( is_callable( $args ) ) {
1168          $args = array(
1169              'sanitize_callback' => $args,
1170          );
1171  
1172          $has_old_sanitize_cb = true;
1173      } else {
1174          $args = (array) $args;
1175      }
1176  
1177      if ( is_callable( $deprecated ) ) {
1178          $args['auth_callback'] = $deprecated;
1179          $has_old_auth_cb       = true;
1180      }
1181  
1182      /**
1183       * Filters the registration arguments when registering meta.
1184       *
1185       * @since 4.6.0
1186       *
1187       * @param array  $args        Array of meta registration arguments.
1188       * @param array  $defaults    Array of default arguments.
1189       * @param string $object_type Object type.
1190       * @param string $meta_key    Meta key.
1191       */
1192      $args = apply_filters( 'register_meta_args', $args, $defaults, $object_type, $meta_key );
1193      $args = wp_parse_args( $args, $defaults );
1194  
1195      // Require an item schema when registering array meta.
1196      if ( false !== $args['show_in_rest'] && 'array' === $args['type'] ) {
1197          if ( ! is_array( $args['show_in_rest'] ) || ! isset( $args['show_in_rest']['schema']['items'] ) ) {
1198              _doing_it_wrong( __FUNCTION__, __( 'When registering an "array" meta type to show in the REST API, you must specify the schema for each array item in "show_in_rest.schema.items".' ), '5.3.0' );
1199  
1200              return false;
1201          }
1202      }
1203  
1204      $object_subtype = ! empty( $args['object_subtype'] ) ? $args['object_subtype'] : '';
1205  
1206      // If `auth_callback` is not provided, fall back to `is_protected_meta()`.
1207      if ( empty( $args['auth_callback'] ) ) {
1208          if ( is_protected_meta( $meta_key, $object_type ) ) {
1209              $args['auth_callback'] = '__return_false';
1210          } else {
1211              $args['auth_callback'] = '__return_true';
1212          }
1213      }
1214  
1215      // Back-compat: old sanitize and auth callbacks are applied to all of an object type.
1216      if ( is_callable( $args['sanitize_callback'] ) ) {
1217          if ( ! empty( $object_subtype ) ) {
1218              add_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['sanitize_callback'], 10, 4 );
1219          } else {
1220              add_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'], 10, 3 );
1221          }
1222      }
1223  
1224      if ( is_callable( $args['auth_callback'] ) ) {
1225          if ( ! empty( $object_subtype ) ) {
1226              add_filter( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['auth_callback'], 10, 6 );
1227          } else {
1228              add_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'], 10, 6 );
1229          }
1230      }
1231  
1232      // Global registry only contains meta keys registered with the array of arguments added in 4.6.0.
1233      if ( ! $has_old_auth_cb && ! $has_old_sanitize_cb ) {
1234          unset( $args['object_subtype'] );
1235  
1236          $wp_meta_keys[ $object_type ][ $object_subtype ][ $meta_key ] = $args;
1237  
1238          return true;
1239      }
1240  
1241      return false;
1242  }
1243  
1244  /**
1245   * Checks if a meta key is registered.
1246   *
1247   * @since 4.6.0
1248   * @since 4.9.8 The `$object_subtype` parameter was added.
1249   *
1250   * @param string $object_type    The type of object.
1251   * @param string $meta_key       The meta key.
1252   * @param string $object_subtype Optional. The subtype of the object type.
1253   *
1254   * @return bool True if the meta key is registered to the object type and, if provided,
1255   *              the object subtype. False if not.
1256   */
1257  function registered_meta_key_exists( $object_type, $meta_key, $object_subtype = '' ) {
1258      $meta_keys = get_registered_meta_keys( $object_type, $object_subtype );
1259  
1260      return isset( $meta_keys[ $meta_key ] );
1261  }
1262  
1263  /**
1264   * Unregisters a meta key from the list of registered keys.
1265   *
1266   * @since 4.6.0
1267   * @since 4.9.8 The `$object_subtype` parameter was added.
1268   *
1269   * @param string $object_type    The type of object.
1270   * @param string $meta_key       The meta key.
1271   * @param string $object_subtype Optional. The subtype of the object type.
1272   * @return bool True if successful. False if the meta key was not registered.
1273   */
1274  function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
1275      global $wp_meta_keys;
1276  
1277      if ( ! registered_meta_key_exists( $object_type, $meta_key, $object_subtype ) ) {
1278          return false;
1279      }
1280  
1281      $args = $wp_meta_keys[ $object_type ][ $object_subtype ][ $meta_key ];
1282  
1283      if ( isset( $args['sanitize_callback'] ) && is_callable( $args['sanitize_callback'] ) ) {
1284          if ( ! empty( $object_subtype ) ) {
1285              remove_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['sanitize_callback'] );
1286          } else {
1287              remove_filter( "sanitize_{$object_type}_meta_{$meta_key}", $args['sanitize_callback'] );
1288          }
1289      }
1290  
1291      if ( isset( $args['auth_callback'] ) && is_callable( $args['auth_callback'] ) ) {
1292          if ( ! empty( $object_subtype ) ) {
1293              remove_filter( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $args['auth_callback'] );
1294          } else {
1295              remove_filter( "auth_{$object_type}_meta_{$meta_key}", $args['auth_callback'] );
1296          }
1297      }
1298  
1299      unset( $wp_meta_keys[ $object_type ][ $object_subtype ][ $meta_key ] );
1300  
1301      // Do some clean up
1302      if ( empty( $wp_meta_keys[ $object_type ][ $object_subtype ] ) ) {
1303          unset( $wp_meta_keys[ $object_type ][ $object_subtype ] );
1304      }
1305      if ( empty( $wp_meta_keys[ $object_type ] ) ) {
1306          unset( $wp_meta_keys[ $object_type ] );
1307      }
1308  
1309      return true;
1310  }
1311  
1312  /**
1313   * Retrieves a list of registered meta keys for an object type.
1314   *
1315   * @since 4.6.0
1316   * @since 4.9.8 The `$object_subtype` parameter was added.
1317   *
1318   * @param string $object_type    The type of object. Post, comment, user, term.
1319   * @param string $object_subtype Optional. The subtype of the object type.
1320   * @return string[] List of registered meta keys.
1321   */
1322  function get_registered_meta_keys( $object_type, $object_subtype = '' ) {
1323      global $wp_meta_keys;
1324  
1325      if ( ! is_array( $wp_meta_keys ) || ! isset( $wp_meta_keys[ $object_type ] ) || ! isset( $wp_meta_keys[ $object_type ][ $object_subtype ] ) ) {
1326          return array();
1327      }
1328  
1329      return $wp_meta_keys[ $object_type ][ $object_subtype ];
1330  }
1331  
1332  /**
1333   * Retrieves registered metadata for a specified object.
1334   *
1335   * The results include both meta that is registered specifically for the
1336   * object's subtype and meta that is registered for the entire object type.
1337   *
1338   * @since 4.6.0
1339   *
1340   * @param string $object_type Type of object to request metadata for. (e.g. comment, post, term, user)
1341   * @param int    $object_id   ID of the object the metadata is for.
1342   * @param string $meta_key    Optional. Registered metadata key. If not specified, retrieve all registered
1343   *                            metadata for the specified object.
1344   * @return mixed A single value or array of values for a key if specified. An array of all registered keys
1345   *               and values for an object ID if not. False if a given $meta_key is not registered.
1346   */
1347  function get_registered_metadata( $object_type, $object_id, $meta_key = '' ) {
1348      $object_subtype = get_object_subtype( $object_type, $object_id );
1349  
1350      if ( ! empty( $meta_key ) ) {
1351          if ( ! empty( $object_subtype ) && ! registered_meta_key_exists( $object_type, $meta_key, $object_subtype ) ) {
1352              $object_subtype = '';
1353          }
1354  
1355          if ( ! registered_meta_key_exists( $object_type, $meta_key, $object_subtype ) ) {
1356              return false;
1357          }
1358  
1359          $meta_keys     = get_registered_meta_keys( $object_type, $object_subtype );
1360          $meta_key_data = $meta_keys[ $meta_key ];
1361  
1362          $data = get_metadata( $object_type, $object_id, $meta_key, $meta_key_data['single'] );
1363  
1364          return $data;
1365      }
1366  
1367      $data = get_metadata( $object_type, $object_id );
1368      if ( ! $data ) {
1369          return array();
1370      }
1371  
1372      $meta_keys = get_registered_meta_keys( $object_type );
1373      if ( ! empty( $object_subtype ) ) {
1374          $meta_keys = array_merge( $meta_keys, get_registered_meta_keys( $object_type, $object_subtype ) );
1375      }
1376  
1377      return array_intersect_key( $data, $meta_keys );
1378  }
1379  
1380  /**
1381   * Filter out `register_meta()` args based on a whitelist.
1382   * `register_meta()` args may change over time, so requiring the whitelist
1383   * to be explicitly turned off is a warranty seal of sorts.
1384   *
1385   * @access private
1386   * @since 4.6.0
1387   *
1388   * @param array $args         Arguments from `register_meta()`.
1389   * @param array $default_args Default arguments for `register_meta()`.
1390   *
1391   * @return array Filtered arguments.
1392   */
1393  function _wp_register_meta_args_whitelist( $args, $default_args ) {
1394      return array_intersect_key( $args, $default_args );
1395  }
1396  
1397  /**
1398   * Returns the object subtype for a given object ID of a specific type.
1399   *
1400   * @since 4.9.8
1401   *
1402   * @param string $object_type Type of object to request metadata for. (e.g. comment, post, term, user)
1403   * @param int    $object_id   ID of the object to retrieve its subtype.
1404   * @return string The object subtype or an empty string if unspecified subtype.
1405   */
1406  function get_object_subtype( $object_type, $object_id ) {
1407      $object_id      = (int) $object_id;
1408      $object_subtype = '';
1409  
1410      switch ( $object_type ) {
1411          case 'post':
1412              $post_type = get_post_type( $object_id );
1413  
1414              if ( ! empty( $post_type ) ) {
1415                  $object_subtype = $post_type;
1416              }
1417              break;
1418  
1419          case 'term':
1420              $term = get_term( $object_id );
1421              if ( ! $term instanceof WP_Term ) {
1422                  break;
1423              }
1424  
1425              $object_subtype = $term->taxonomy;
1426              break;
1427  
1428          case 'comment':
1429              $comment = get_comment( $object_id );
1430              if ( ! $comment ) {
1431                  break;
1432              }
1433  
1434              $object_subtype = 'comment';
1435              break;
1436  
1437          case 'user':
1438              $user = get_user_by( 'id', $object_id );
1439              if ( ! $user ) {
1440                  break;
1441              }
1442  
1443              $object_subtype = 'user';
1444              break;
1445      }
1446  
1447      /**
1448       * Filters the object subtype identifier for a non standard object type.
1449       *
1450       * The dynamic portion of the hook, `$object_type`, refers to the object
1451       * type (post, comment, term, or user).
1452       *
1453       * @since 4.9.8
1454       *
1455       * @param string $object_subtype Empty string to override.
1456       * @param int    $object_id      ID of the object to get the subtype for.
1457       */
1458      return apply_filters( "get_object_subtype_{$object_type}", $object_subtype, $object_id );
1459  }


Generated: Mon Nov 18 01:00:04 2019 Cross-referenced by PHPXref 0.7.1