3 * Meta API: WP_Metadata_Lazyloader class
11 * Core class used for lazy-loading object metadata.
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.
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.
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.
27 * Do not access this class directly. Use the wp_metadata_lazyloader() function.
31 class WP_Metadata_Lazyloader {
33 * Pending objects queue.
39 protected $pending_objects;
42 * Settings for supported object types.
48 protected $settings = array();
56 public function __construct() {
57 $this->settings = array(
59 'filter' => 'get_term_metadata',
60 'callback' => array( $this, 'lazyload_term_meta' ),
63 'filter' => 'get_comment_metadata',
64 'callback' => array( $this, 'lazyload_comment_meta' ),
70 * Adds objects to the metadata lazy-load queue.
75 * @param string $object_type Type of object whose meta is to be lazy-loaded. Accepts 'term' or 'comment'.
76 * @param array $object_ids Array of object IDs.
77 * @return bool|WP_Error True on success, WP_Error on failure.
79 public function queue_objects( $object_type, $object_ids ) {
80 if ( ! isset( $this->settings[ $object_type ] ) ) {
81 return new WP_Error( 'invalid_object_type', __( 'Invalid object type' ) );
84 $type_settings = $this->settings[ $object_type ];
86 if ( ! isset( $this->pending_objects[ $object_type ] ) ) {
87 $this->pending_objects[ $object_type ] = array();
90 foreach ( $object_ids as $object_id ) {
91 // Keyed by ID for faster lookup.
92 if ( ! isset( $this->pending_objects[ $object_type ][ $object_id ] ) ) {
93 $this->pending_objects[ $object_type ][ $object_id ] = 1;
97 add_filter( $type_settings['filter'], $type_settings['callback'] );
100 * Fires after objects are added to the metadata lazy-load queue.
104 * @param array $object_ids Object IDs.
105 * @param string $object_type Type of object being queued.
106 * @param WP_Metadata_Lazyloader $lazyloader The lazy-loader object.
108 do_action( 'metadata_lazyloader_queued_objects', $object_ids, $object_type, $this );
112 * Resets lazy-load queue for a given object type.
117 * @param string $object_type Object type. Accepts 'comment' or 'term'.
118 * @return bool|WP_Error True on success, WP_Error on failure.
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' ) );
125 $type_settings = $this->settings[ $object_type ];
127 $this->pending_objects[ $object_type ] = array();
128 remove_filter( $type_settings['filter'], $type_settings['callback'] );
132 * Lazy-loads term meta for queued terms.
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.
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.
144 public function lazyload_term_meta( $check ) {
145 if ( ! empty( $this->pending_objects['term'] ) ) {
146 update_termmeta_cache( array_keys( $this->pending_objects['term'] ) );
148 // No need to run again for this set of terms.
149 $this->reset_queue( 'term' );
156 * Lazy-loads comment meta for queued comments.
158 * This method is public so that it can be used as a filter callback. As a rule, there is no need to invoke it
159 * directly, from either inside or outside the `WP_Query` object.
163 * @param mixed $check The `$check` param passed from the 'get_comment_metadata' hook.
164 * @return mixed The original value of `$check`, so as not to short-circuit `get_comment_metadata()`.
166 public function lazyload_comment_meta( $check ) {
167 if ( ! empty( $this->pending_objects['comment'] ) ) {
168 update_meta_cache( 'comment', array_keys( $this->pending_objects['comment'] ) );
170 // No need to run again for this set of comments.
171 $this->reset_queue( 'comment' );