[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Meta API: WP_Metadata_Lazyloader class
   4   *
   5   * @package WordPress
   6   * @subpackage Meta
   7   * @since 4.5.0
   8   */
   9  
  10  /**
  11   * Core class used for lazy-loading object metadata.
  12   *
  13   * When loading many objects of a given type, such as posts in a WP_Query loop, it often makes
  14   * sense to prime various metadata caches at the beginning of the loop. This means fetching all
  15   * relevant metadata with a single database query, a technique that has the potential to improve
  16   * performance dramatically in some cases.
  17   *
  18   * In cases where the given metadata may not even be used in the loop, we can improve performance
  19   * even more by only priming the metadata cache for affected items the first time a piece of metadata
  20   * is requested - ie, by lazy-loading it. So, for example, comment meta may not be loaded into the
  21   * cache in the comments section of a post until the first time get_comment_meta() is called in the
  22   * context of the comment loop.
  23   *
  24   * WP uses the WP_Metadata_Lazyloader class to queue objects for metadata cache priming. The class
  25   * then detects the relevant get_*_meta() function call, and queries the metadata of all queued objects.
  26   *
  27   * Do not access this class directly. Use the wp_metadata_lazyloader() function.
  28   *
  29   * @since 4.5.0
  30   */
  31  #[AllowDynamicProperties]
  32  class WP_Metadata_Lazyloader {
  33      /**
  34       * Pending objects queue.
  35       *
  36       * @since 4.5.0
  37       * @var array
  38       */
  39      protected $pending_objects;
  40  
  41      /**
  42       * Settings for supported object types.
  43       *
  44       * @since 4.5.0
  45       * @var array
  46       */
  47      protected $settings = array();
  48  
  49      /**
  50       * Constructor.
  51       *
  52       * @since 4.5.0
  53       */
  54  	public function __construct() {
  55          $this->settings = array(
  56              'term'    => array(
  57                  'filter'   => 'get_term_metadata',
  58                  'callback' => array( $this, 'lazyload_meta_callback' ),
  59              ),
  60              'comment' => array(
  61                  'filter'   => 'get_comment_metadata',
  62                  'callback' => array( $this, 'lazyload_meta_callback' ),
  63              ),
  64              'blog'    => array(
  65                  'filter'   => 'get_blog_metadata',
  66                  'callback' => array( $this, 'lazyload_meta_callback' ),
  67              ),
  68          );
  69      }
  70  
  71      /**
  72       * Adds objects to the metadata lazy-load queue.
  73       *
  74       * @since 4.5.0
  75       *
  76       * @param string $object_type Type of object whose meta is to be lazy-loaded. Accepts 'term' or 'comment'.
  77       * @param array  $object_ids  Array of object IDs.
  78       * @return void|WP_Error WP_Error on failure.
  79       */
  80  	public function queue_objects( $object_type, $object_ids ) {
  81          if ( ! isset( $this->settings[ $object_type ] ) ) {
  82              return new WP_Error( 'invalid_object_type', __( 'Invalid object type.' ) );
  83          }
  84  
  85          $type_settings = $this->settings[ $object_type ];
  86  
  87          if ( ! isset( $this->pending_objects[ $object_type ] ) ) {
  88              $this->pending_objects[ $object_type ] = array();
  89          }
  90  
  91          foreach ( $object_ids as $object_id ) {
  92              // Keyed by ID for faster lookup.
  93              if ( ! isset( $this->pending_objects[ $object_type ][ $object_id ] ) ) {
  94                  $this->pending_objects[ $object_type ][ $object_id ] = 1;
  95              }
  96          }
  97  
  98          add_filter( $type_settings['filter'], $type_settings['callback'], 10, 5 );
  99  
 100          /**
 101           * Fires after objects are added to the metadata lazy-load queue.
 102           *
 103           * @since 4.5.0
 104           *
 105           * @param array                  $object_ids  Array of object IDs.
 106           * @param string                 $object_type Type of object being queued.
 107           * @param WP_Metadata_Lazyloader $lazyloader  The lazy-loader object.
 108           */
 109          do_action( 'metadata_lazyloader_queued_objects', $object_ids, $object_type, $this );
 110      }
 111  
 112      /**
 113       * Resets lazy-load queue for a given object type.
 114       *
 115       * @since 4.5.0
 116       *
 117       * @param string $object_type Object type. Accepts 'comment' or 'term'.
 118       * @return void|WP_Error WP_Error on failure.
 119       */
 120  	public function reset_queue( $object_type ) {
 121          if ( ! isset( $this->settings[ $object_type ] ) ) {
 122              return new WP_Error( 'invalid_object_type', __( 'Invalid object type.' ) );
 123          }
 124  
 125          $type_settings = $this->settings[ $object_type ];
 126  
 127          $this->pending_objects[ $object_type ] = array();
 128          remove_filter( $type_settings['filter'], $type_settings['callback'] );
 129      }
 130  
 131      /**
 132       * Lazy-loads term meta for queued terms.
 133       *
 134       * This method is public so that it can be used as a filter callback. As a rule, there
 135       * is no need to invoke it directly.
 136       *
 137       * @since 4.5.0
 138       * @deprecated 6.3.0 Use WP_Metadata_Lazyloader::lazyload_meta_callback() instead.
 139       *
 140       * @param mixed $check The `$check` param passed from the 'get_term_metadata' hook.
 141       * @return mixed In order not to short-circuit `get_metadata()`. Generally, this is `null`, but it could be
 142       *               another value if filtered by a plugin.
 143       */
 144  	public function lazyload_term_meta( $check ) {
 145          _deprecated_function( __METHOD__, '6.3.0', 'WP_Metadata_Lazyloader::lazyload_meta_callback' );
 146          return $this->lazyload_meta_callback( $check, 0, '', false, 'term' );
 147      }
 148  
 149      /**
 150       * Lazy-loads comment meta for queued comments.
 151       *
 152       * This method is public so that it can be used as a filter callback. As a rule, there is no need to invoke it
 153       * directly, from either inside or outside the `WP_Query` object.
 154       *
 155       * @since 4.5.0
 156       * @deprecated 6.3.0 Use WP_Metadata_Lazyloader::lazyload_meta_callback() instead.
 157       *
 158       * @param mixed $check The `$check` param passed from the {@see 'get_comment_metadata'} hook.
 159       * @return mixed The original value of `$check`, so as not to short-circuit `get_comment_metadata()`.
 160       */
 161  	public function lazyload_comment_meta( $check ) {
 162          _deprecated_function( __METHOD__, '6.3.0', 'WP_Metadata_Lazyloader::lazyload_meta_callback' );
 163          return $this->lazyload_meta_callback( $check, 0, '', false, 'comment' );
 164      }
 165  
 166      /**
 167       * Lazy-loads meta for queued objects.
 168       *
 169       * This method is public so that it can be used as a filter callback. As a rule, there
 170       * is no need to invoke it directly.
 171       *
 172       * @since 6.3.0
 173       *
 174       * @param mixed  $check     The `$check` param passed from the 'get_*_metadata' hook.
 175       * @param int    $object_id ID of the object metadata is for.
 176       * @param string $meta_key  Unused.
 177       * @param bool   $single    Unused.
 178       * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
 179       *                          or any other object type with an associated meta table.
 180       * @return mixed In order not to short-circuit `get_metadata()`. Generally, this is `null`, but it could be
 181       *               another value if filtered by a plugin.
 182       */
 183  	public function lazyload_meta_callback( $check, $object_id, $meta_key, $single, $meta_type ) {
 184          if ( empty( $this->pending_objects[ $meta_type ] ) ) {
 185              return $check;
 186          }
 187  
 188          $object_ids = array_keys( $this->pending_objects[ $meta_type ] );
 189          if ( $object_id && ! in_array( $object_id, $object_ids, true ) ) {
 190              $object_ids[] = $object_id;
 191          }
 192  
 193          update_meta_cache( $meta_type, $object_ids );
 194  
 195          // No need to run again for this set of objects.
 196          $this->reset_queue( $meta_type );
 197  
 198          return $check;
 199      }
 200  }