diff options
Diffstat (limited to 'wp-includes/class-wp-metadata-lazyloader.php')
| -rw-r--r-- | wp-includes/class-wp-metadata-lazyloader.php | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/wp-includes/class-wp-metadata-lazyloader.php b/wp-includes/class-wp-metadata-lazyloader.php new file mode 100644 index 0000000..f9c0239 --- /dev/null +++ b/wp-includes/class-wp-metadata-lazyloader.php @@ -0,0 +1,200 @@ +<?php +/** + * Meta API: WP_Metadata_Lazyloader class + * + * @package WordPress + * @subpackage Meta + * @since 4.5.0 + */ + +/** + * Core class used for lazy-loading object metadata. + * + * When loading many objects of a given type, such as posts in a WP_Query loop, it often makes + * sense to prime various metadata caches at the beginning of the loop. This means fetching all + * relevant metadata with a single database query, a technique that has the potential to improve + * performance dramatically in some cases. + * + * In cases where the given metadata may not even be used in the loop, we can improve performance + * even more by only priming the metadata cache for affected items the first time a piece of metadata + * is requested - ie, by lazy-loading it. So, for example, comment meta may not be loaded into the + * cache in the comments section of a post until the first time get_comment_meta() is called in the + * context of the comment loop. + * + * WP uses the WP_Metadata_Lazyloader class to queue objects for metadata cache priming. The class + * then detects the relevant get_*_meta() function call, and queries the metadata of all queued objects. + * + * Do not access this class directly. Use the wp_metadata_lazyloader() function. + * + * @since 4.5.0 + */ +#[AllowDynamicProperties] +class WP_Metadata_Lazyloader { + /** + * Pending objects queue. + * + * @since 4.5.0 + * @var array + */ + protected $pending_objects; + + /** + * Settings for supported object types. + * + * @since 4.5.0 + * @var array + */ + protected $settings = array(); + + /** + * Constructor. + * + * @since 4.5.0 + */ + public function __construct() { + $this->settings = array( + 'term' => array( + 'filter' => 'get_term_metadata', + 'callback' => array( $this, 'lazyload_meta_callback' ), + ), + 'comment' => array( + 'filter' => 'get_comment_metadata', + 'callback' => array( $this, 'lazyload_meta_callback' ), + ), + 'blog' => array( + 'filter' => 'get_blog_metadata', + 'callback' => array( $this, 'lazyload_meta_callback' ), + ), + ); + } + + /** + * Adds objects to the metadata lazy-load queue. + * + * @since 4.5.0 + * + * @param string $object_type Type of object whose meta is to be lazy-loaded. Accepts 'term' or 'comment'. + * @param array $object_ids Array of object IDs. + * @return void|WP_Error WP_Error on failure. + */ + public function queue_objects( $object_type, $object_ids ) { + if ( ! isset( $this->settings[ $object_type ] ) ) { + return new WP_Error( 'invalid_object_type', __( 'Invalid object type.' ) ); + } + + $type_settings = $this->settings[ $object_type ]; + + if ( ! isset( $this->pending_objects[ $object_type ] ) ) { + $this->pending_objects[ $object_type ] = array(); + } + + foreach ( $object_ids as $object_id ) { + // Keyed by ID for faster lookup. + if ( ! isset( $this->pending_objects[ $object_type ][ $object_id ] ) ) { + $this->pending_objects[ $object_type ][ $object_id ] = 1; + } + } + + add_filter( $type_settings['filter'], $type_settings['callback'], 10, 5 ); + + /** + * Fires after objects are added to the metadata lazy-load queue. + * + * @since 4.5.0 + * + * @param array $object_ids Array of object IDs. + * @param string $object_type Type of object being queued. + * @param WP_Metadata_Lazyloader $lazyloader The lazy-loader object. + */ + do_action( 'metadata_lazyloader_queued_objects', $object_ids, $object_type, $this ); + } + + /** + * Resets lazy-load queue for a given object type. + * + * @since 4.5.0 + * + * @param string $object_type Object type. Accepts 'comment' or 'term'. + * @return void|WP_Error WP_Error on failure. + */ + public function reset_queue( $object_type ) { + if ( ! isset( $this->settings[ $object_type ] ) ) { + return new WP_Error( 'invalid_object_type', __( 'Invalid object type.' ) ); + } + + $type_settings = $this->settings[ $object_type ]; + + $this->pending_objects[ $object_type ] = array(); + remove_filter( $type_settings['filter'], $type_settings['callback'] ); + } + + /** + * Lazy-loads term meta for queued terms. + * + * This method is public so that it can be used as a filter callback. As a rule, there + * is no need to invoke it directly. + * + * @since 4.5.0 + * @deprecated 6.3.0 Use WP_Metadata_Lazyloader::lazyload_meta_callback() instead. + * + * @param mixed $check The `$check` param passed from the 'get_term_metadata' hook. + * @return mixed In order not to short-circuit `get_metadata()`. Generally, this is `null`, but it could be + * another value if filtered by a plugin. + */ + public function lazyload_term_meta( $check ) { + _deprecated_function( __METHOD__, '6.3.0', 'WP_Metadata_Lazyloader::lazyload_meta_callback' ); + return $this->lazyload_meta_callback( $check, 0, '', false, 'term' ); + } + + /** + * Lazy-loads comment meta for queued comments. + * + * This method is public so that it can be used as a filter callback. As a rule, there is no need to invoke it + * directly, from either inside or outside the `WP_Query` object. + * + * @since 4.5.0 + * @deprecated 6.3.0 Use WP_Metadata_Lazyloader::lazyload_meta_callback() instead. + * + * @param mixed $check The `$check` param passed from the {@see 'get_comment_metadata'} hook. + * @return mixed The original value of `$check`, so as not to short-circuit `get_comment_metadata()`. + */ + public function lazyload_comment_meta( $check ) { + _deprecated_function( __METHOD__, '6.3.0', 'WP_Metadata_Lazyloader::lazyload_meta_callback' ); + return $this->lazyload_meta_callback( $check, 0, '', false, 'comment' ); + } + + /** + * Lazy-loads meta for queued objects. + * + * This method is public so that it can be used as a filter callback. As a rule, there + * is no need to invoke it directly. + * + * @since 6.3.0 + * + * @param mixed $check The `$check` param passed from the 'get_*_metadata' hook. + * @param int $object_id ID of the object metadata is for. + * @param string $meta_key Unused. + * @param bool $single Unused. + * @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user', + * or any other object type with an associated meta table. + * @return mixed In order not to short-circuit `get_metadata()`. Generally, this is `null`, but it could be + * another value if filtered by a plugin. + */ + public function lazyload_meta_callback( $check, $object_id, $meta_key, $single, $meta_type ) { + if ( empty( $this->pending_objects[ $meta_type ] ) ) { + return $check; + } + + $object_ids = array_keys( $this->pending_objects[ $meta_type ] ); + if ( $object_id && ! in_array( $object_id, $object_ids, true ) ) { + $object_ids[] = $object_id; + } + + update_meta_cache( $meta_type, $object_ids ); + + // No need to run again for this set of objects. + $this->reset_queue( $meta_type ); + + return $check; + } +} |