WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / class-wp-metadata-lazyloader.php
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 class WP_Metadata_Lazyloader {
32         /**
33          * Pending objects queue.
34          *
35          * @since 4.5.0
36          * @access protected
37          * @var array
38          */
39         protected $pending_objects;
40
41         /**
42          * Settings for supported object types.
43          *
44          * @since 4.5.0
45          * @access protected
46          * @var array
47          */
48         protected $settings = array();
49
50         /**
51          * Constructor.
52          *
53          * @since 4.5.0
54          * @access public
55          */
56         public function __construct() {
57                 $this->settings = array(
58                         'term' => array(
59                                 'filter'   => 'get_term_metadata',
60                                 'callback' => array( $this, 'lazyload_term_meta' ),
61                         ),
62                         'comment' => array(
63                                 'filter'   => 'get_comment_metadata',
64                                 'callback' => array( $this, 'lazyload_comment_meta' ),
65                         ),
66                 );
67         }
68
69         /**
70          * Adds objects to the metadata lazy-load queue.
71          *
72          * @since 4.5.0
73          * @access public
74          *
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.
78          */
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' ) );
82                 }
83
84                 $type_settings = $this->settings[ $object_type ];
85
86                 if ( ! isset( $this->pending_objects[ $object_type ] ) ) {
87                         $this->pending_objects[ $object_type ] = array();
88                 }
89
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;
94                         }
95                 }
96
97                 add_filter( $type_settings['filter'], $type_settings['callback'] );
98
99                 /**
100                  * Fires after objects are added to the metadata lazy-load queue.
101                  *
102                  * @since 4.5.0
103                  *
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.
107                  */
108                 do_action( 'metadata_lazyloader_queued_objects', $object_ids, $object_type, $this );
109         }
110
111         /**
112          * Resets lazy-load queue for a given object type.
113          *
114          * @since 4.5.0
115          * @access public
116          *
117          * @param string $object_type Object type. Accepts 'comment' or 'term'.
118          * @return bool|WP_Error True on success, 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          * @access public
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                 if ( ! empty( $this->pending_objects['term'] ) ) {
146                         update_termmeta_cache( array_keys( $this->pending_objects['term'] ) );
147
148                         // No need to run again for this set of terms.
149                         $this->reset_queue( 'term' );
150                 }
151
152                 return $check;
153         }
154
155         /**
156          * Lazy-loads comment meta for queued comments.
157          *
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.
160          *
161          * @since 4.5.0
162          *
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()`.
165          */
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'] ) );
169
170                         // No need to run again for this set of comments.
171                         $this->reset_queue( 'comment' );
172                 }
173
174                 return $check;
175         }
176 }