<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[56612] trunk: Media: Enhance `wp_get_loading_optimization_attributes()` to support arbitrary context values.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/56612">56612</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/56612","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>flixos90</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2023-09-18 14:53:37 +0000 (Mon, 18 Sep 2023)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Media: Enhance `wp_get_loading_optimization_attributes()` to support arbitrary context values.
The `wp_get_loading_optimization_attributes()` function, which was introduced in 6.3, based on the now deprecated `wp_get_loading_attr_default()` function introduced in 5.5, relies on a `$context` parameter based on which it may alter its behavior and the attributes returned. So far, it has only supported context values used within WordPress core.
This changeset decouples the behaviors of the function from specific contexts, allowing for more flexibility. Theme and plugin developers will be able to rely on their own context values when rendering images in non-standard ways, rather than being forced to use a core context, to get the loading optimization benefits the function provides.
As part of this change, a `wp_loading_optimization_force_header_contexts` filter is introduced, which allows filtering the map of context values and whether they should be considered header contexts, i.e. i.e. any image having one of these contexts will be assumed to appear above the fold.
Props mukesh27, costdev, flixos90.
Fixes <a href="https://core.trac.wordpress.org/ticket/58894">#58894</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesmediaphp">trunk/src/wp-includes/media.php</a></li>
<li><a href="#trunktestsphpunittestsmediaphp">trunk/tests/phpunit/tests/media.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesmediaphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-includes/media.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-includes/media.php 2023-09-18 13:17:39 UTC (rev 56611)
+++ trunk/src/wp-includes/media.php 2023-09-18 14:53:37 UTC (rev 56612)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -5652,13 +5652,9 @@
</span><span class="cx" style="display: block; padding: 0 10px"> * can result in the first post content image being lazy-loaded or an image further down the page being marked as a
</span><span class="cx" style="display: block; padding: 0 10px"> * high priority.
</span><span class="cx" style="display: block; padding: 0 10px"> */
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- switch ( $context ) {
- case 'the_post_thumbnail':
- case 'wp_get_attachment_image':
- case 'widget_media_image':
- if ( doing_filter( 'the_content' ) ) {
- return $loading_attrs;
- }
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // TODO: Handle shortcode images together with the content (see https://core.trac.wordpress.org/ticket/58853).
+ if ( 'the_content' !== $context && 'do_shortcode' !== $context && doing_filter( 'the_content' ) ) {
+ return $loading_attrs;
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /*
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -5709,64 +5705,56 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( null === $maybe_in_viewport ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- switch ( $context ) {
- // Consider elements with these header-specific contexts to be in viewport.
- case 'template_part_' . WP_TEMPLATE_PART_AREA_HEADER:
- case 'get_header_image_tag':
- $maybe_in_viewport = true;
- $maybe_increase_count = true;
- break;
- // Count main content elements and detect whether in viewport.
- case 'the_content':
- case 'the_post_thumbnail':
- case 'do_shortcode':
- // Only elements within the main query loop have special handling.
- if ( ! is_admin() && in_the_loop() && is_main_query() ) {
- /*
- * Get the content media count, since this is a main query
- * content element. This is accomplished by "increasing"
- * the count by zero, as the only way to get the count is
- * to call this function.
- * The actual count increase happens further below, based
- * on the `$increase_count` flag set here.
- */
- $content_media_count = wp_increase_content_media_count( 0 );
- $increase_count = true;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ $header_enforced_contexts = array(
+ 'template_part_' . WP_TEMPLATE_PART_AREA_HEADER => true,
+ 'get_header_image_tag' => true,
+ );
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // If the count so far is below the threshold, `loading` attribute is omitted.
- if ( $content_media_count < wp_omit_loading_attr_threshold() ) {
- $maybe_in_viewport = true;
- } else {
- $maybe_in_viewport = false;
- }
- }
- /*
- * For the 'the_post_thumbnail' context, the following case
- * clause needs to be considered as well, therefore skip the
- * break statement here if the viewport has not been
- * determined.
- */
- if ( 'the_post_thumbnail' !== $context || null !== $maybe_in_viewport ) {
- break;
- }
- // phpcs:ignore Generic.WhiteSpace.ScopeIndent.Incorrect
- // Consider elements before the loop as being in viewport.
- case 'wp_get_attachment_image':
- case 'widget_media_image':
- if (
- // Only apply for main query but before the loop.
- $wp_query->before_loop && $wp_query->is_main_query()
- /*
- * Any image before the loop, but after the header has started should not be lazy-loaded,
- * except when the footer has already started which can happen when the current template
- * does not include any loop.
- */
- && did_action( 'get_header' ) && ! did_action( 'get_footer' )
- ) {
- $maybe_in_viewport = true;
- $maybe_increase_count = true;
- }
- break;
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Filters the header-specific contexts.
+ *
+ * @since 6.4.0
+ *
+ * @param array $default_header_enforced_contexts Map of contexts for which elements should be considered
+ * in the header of the page, as $context => $enabled
+ * pairs. The $enabled should always be true.
+ */
+ $header_enforced_contexts = apply_filters( 'wp_loading_optimization_force_header_contexts', $header_enforced_contexts );
+
+ // Consider elements with these header-specific contexts to be in viewport.
+ if ( isset( $header_enforced_contexts[ $context ] ) ) {
+ $maybe_in_viewport = true;
+ $maybe_increase_count = true;
+ } elseif ( ! is_admin() && in_the_loop() && is_main_query() ) {
+ /*
+ * Get the content media count, since this is a main query
+ * content element. This is accomplished by "increasing"
+ * the count by zero, as the only way to get the count is
+ * to call this function.
+ * The actual count increase happens further below, based
+ * on the `$increase_count` flag set here.
+ */
+ $content_media_count = wp_increase_content_media_count( 0 );
+ $increase_count = true;
+
+ // If the count so far is below the threshold, `loading` attribute is omitted.
+ if ( $content_media_count < wp_omit_loading_attr_threshold() ) {
+ $maybe_in_viewport = true;
+ } else {
+ $maybe_in_viewport = false;
+ }
+ } elseif (
+ // Only apply for main query but before the loop.
+ $wp_query->before_loop && $wp_query->is_main_query()
+ /*
+ * Any image before the loop, but after the header has started should not be lazy-loaded,
+ * except when the footer has already started which can happen when the current template
+ * does not include any loop.
+ */
+ && did_action( 'get_header' ) && ! did_action( 'get_footer' )
+ ) {
+ $maybe_in_viewport = true;
+ $maybe_increase_count = true;
</ins><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span></span></pre></div>
<a id="trunktestsphpunittestsmediaphp"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/tests/phpunit/tests/media.php</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/tests/phpunit/tests/media.php 2023-09-18 13:17:39 UTC (rev 56611)
+++ trunk/tests/phpunit/tests/media.php 2023-09-18 14:53:37 UTC (rev 56612)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4301,15 +4301,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> // Set as main query.
</span><span class="cx" style="display: block; padding: 0 10px"> $this->set_main_query( $query );
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- /*
- * For contexts other than for the main content, still return 'lazy' even in the loop
- * and in the main query, and do not increase the content media count.
- */
- $this->assertSame(
- array( 'loading' => 'lazy' ),
- wp_get_loading_optimization_attributes( 'img', $attr, 'wp_get_attachment_image' )
- );
-
</del><span class="cx" style="display: block; padding: 0 10px"> // First three element are not lazy loaded. However, first image is loaded with fetchpriority high.
</span><span class="cx" style="display: block; padding: 0 10px"> $this->assertSame(
</span><span class="cx" style="display: block; padding: 0 10px"> array( 'fetchpriority' => 'high' ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -4340,6 +4331,184 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> /**
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ * Tests that wp_get_loading_optimization_attributes() returns fetchpriority=high and increases the count for arbitrary contexts in the main loop.
+ *
+ * @ticket 58894
+ *
+ * @covers ::wp_get_loading_optimization_attributes
+ *
+ * @dataProvider data_wp_get_loading_optimization_attributes_arbitrary_contexts
+ *
+ * @param string $context Context for the element for which the loading optimization attribute is requested.
+ */
+ public function test_wp_get_loading_optimization_attributes_with_arbitrary_contexts_in_main_loop( $context ) {
+ $attr = $this->get_width_height_for_high_priority();
+
+ $this->assertSame(
+ array( 'loading' => 'lazy' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'The "loading" attribute should be "lazy" when not in the loop or the main query.'
+ );
+
+ $query = $this->get_new_wp_query_for_published_post();
+
+ // Set as main query.
+ $this->set_main_query( $query );
+
+ while ( have_posts() ) {
+ the_post();
+
+ $this->assertSame(
+ array( 'fetchpriority' => 'high' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'The "fetchpriority" attribute should be "high" while in the loop and the main query.'
+ );
+
+ // Images with a certain minimum size in the arbitrary contexts of the page are also counted towards the threshold.
+ $this->assertSame( 1, wp_increase_content_media_count( 0 ), 'The content media count should be 1.' );
+ }
+ }
+
+ /**
+ * Tests that wp_get_loading_optimization_attributes() does not return lazy loading attributes when arbitrary contexts are used before the main query loop.
+ *
+ * @ticket 58894
+ *
+ * @covers ::wp_get_loading_optimization_attributes
+ *
+ * @dataProvider data_wp_get_loading_optimization_attributes_arbitrary_contexts
+ *
+ * @param string $context Context for the element for which the loading optimization attribute is requested.
+ */
+ public function test_wp_get_loading_optimization_attributes_with_arbitrary_contexts_before_main_query_loop( $context ) {
+ $attr = $this->get_width_height_for_high_priority();
+
+ $query = $this->get_new_wp_query_for_published_post();
+
+ // Set as main query.
+ $this->set_main_query( $query );
+
+ $this->assertSame(
+ array( 'loading' => 'lazy' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'The "loading" attribute should be "lazy" before the main query loop.'
+ );
+
+ while ( have_posts() ) {
+ the_post();
+
+ $this->assertSame(
+ array( 'fetchpriority' => 'high' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'The "fetchpriority" attribute should be "high" while in the loop and the main query.'
+ );
+
+ $this->assertArrayNotHasKey(
+ 'loading',
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'No "loading" attribute should be present on the second image in the main query loop.'
+ );
+ }
+ }
+
+ /**
+ * Data provider.
+ *
+ * @return array[]
+ */
+ public function data_wp_get_loading_optimization_attributes_arbitrary_contexts() {
+ return array(
+ array( 'wp_get_attachment_image' ),
+ array( 'something_completely_arbitrary' ),
+ );
+ }
+
+ /**
+ * Tests that wp_get_loading_optimization_attributes() returns empty array for arbitrary context.
+ *
+ * @ticket 58894
+ *
+ * @covers ::wp_get_loading_optimization_attributes
+ */
+ public function test_wp_get_loading_optimization_attributes_should_return_empty_array_for_any_arbitrary_context() {
+ remove_all_filters( 'the_content' );
+
+ $result = null;
+ add_filter(
+ 'the_content',
+ function( $content ) use ( &$result ) {
+ $attr = $this->get_width_height_for_high_priority();
+ $result = wp_get_loading_optimization_attributes( 'img', $attr, 'something_completely_arbitrary' );
+ return $content;
+ }
+ );
+ apply_filters( 'the_content', '' );
+
+ $this->assertSame( array(), $result );
+ }
+
+ /**
+ * @ticket 58894
+ *
+ * @covers ::wp_get_loading_optimization_attributes
+ *
+ * @dataProvider data_wp_get_loading_optimization_attributes_header_context
+ *
+ * @param string $context The context for the header.
+ */
+ public function test_wp_get_loading_optimization_attributes_header_contexts( $context ) {
+ $attr = $this->get_width_height_for_high_priority();
+
+ $this->assertArrayNotHasKey(
+ 'loading',
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'Images in the header context should not be lazy-loaded.'
+ );
+
+ add_filter( 'wp_loading_optimization_force_header_contexts', '__return_empty_array' );
+
+ $this->assertSame(
+ array( 'loading' => 'lazy' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, $context ),
+ 'Images in the header context should get lazy-loaded after the wp_loading_optimization_force_header_contexts filter.'
+ );
+ }
+
+ /**
+ * Data provider.
+ *
+ * @return array[]
+ */
+ public function data_wp_get_loading_optimization_attributes_header_context() {
+ return array(
+ array( 'template_part_' . WP_TEMPLATE_PART_AREA_HEADER ),
+ array( 'get_header_image_tag' ),
+ );
+ }
+
+ /**
+ * @ticket 58894
+ *
+ * @covers ::wp_get_loading_optimization_attributes
+ */
+ public function test_wp_loading_optimization_force_header_contexts_filter() {
+ $attr = $this->get_width_height_for_high_priority();
+
+ add_filter(
+ 'wp_loading_optimization_force_header_contexts',
+ function( $context ) {
+ $contexts['something_completely_arbitrary'] = true;
+ return $contexts;
+ }
+ );
+
+ $this->assertSame(
+ array( 'fetchpriority' => 'high' ),
+ wp_get_loading_optimization_attributes( 'img', $attr, 'something_completely_arbitrary' )
+ );
+ }
+
+ /**
</ins><span class="cx" style="display: block; padding: 0 10px"> * Tests that wp_get_loading_optimization_attributes() returns the expected loading attribute value before loop but after get_header if not main query.
</span><span class="cx" style="display: block; padding: 0 10px"> *
</span><span class="cx" style="display: block; padding: 0 10px"> * @ticket 58211
</span></span></pre>
</div>
</div>
</body>
</html>