Excerpt blocks don't respect the excerpt_length filter for user written excerpts

[tomjn]

Description

The post excerpt block does not respect the excerpt_length filter in local tests on WordPress v6.2.

Step-by-step reproduction instructions

Attempt to shorten an excerpt using excerpt_length with a filter such as this:

E.g.:

function mytheme_custom_excerpt_length( $length ) {
    return 2;
}
add_filter( 'excerpt_length', 'mytheme_custom_excerpt_length', 999 );

The excerpts in block themes should now be 2 words long but instead they are unchanged for excerpts that are manually set. This was not the case when using the_excerpt() in classic themes.

Environment info

WordPress v6.2, the gutenberg plugin is inactive

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[tomjn]

Noting that I had to work around this with a filter:

/**
 * Enforce excerpt length on all excerpts
 *
 * @param string $excerpt
 * @return string
 */
function get_the_excerpt( $excerpt ) : string {
    return wp_trim_words( $excerpt, 10 );
}

[skorasaurus]

Attempts to use excerptLength attributes e.g. <!-- wp:post-excerpt {"excerptLength":"10"}/--> result in no excerpts regardless of what number I use or wether it is wrapped in quotes

Could you explain a bit more? Are post excerpts not limited to 10 words on the frontend when you have <!-- wp:post-excerpt {"excerptLength":10}/--> within a query loop block?

Are you still experiencing it with Gutenberg 15.4?

maybe related to https://github.com/WordPress/gutenberg/pull/48598#issuecomment-1453933501

[tomjn]

Could you explain a bit more? Are post excerpts not limited to 10 words on the frontend when you have within a query loop block?

Any value be it in quotes or not resulted in 0 words being displayed, no excerpts were visible. This is under WP 6.2 stock in a block theme

[skorasaurus]

hrm, wow, that is pretty plain and obvious. I'm kinda surprised it slipped through and hasn't been caught yet; I'm able to reproduce this on WP 6.2. I'm not able to reproduce this with Gutenberg activated. twentytwentythree theme.

To reproduce:

Create a page whose content includes a query loop that contains a post excerpt block inside of it; e.g.

<!-- wp:query {"queryId":5,"query":{"perPage":6,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true},"displayLayout":{"type":"list"}} -->
<div class="wp-block-query"><!-- wp:post-template -->
<!-- wp:post-title {"isLink":true} /-->

<!-- wp:post-excerpt /-->

<!-- wp:separator {"opacity":"css"} -->
<hr class="wp-block-separator has-css-opacity"/>
<!-- /wp:separator -->

<!-- wp:post-date /-->
<!-- /wp:post-template --></div>
<!-- /wp:query -->

What happens:

No content of any kind is published on the frontend. The post excerpts do display as intended in the post editor.

[carolinan]

With Gutenberg active, the post excerpt block uses the length set in the option, which should not be overwritten by the filter. (Using the filtered numeric value as the default in the control is not implemented and would need a separate issue and PR)

The excerpt length option and code example linked above (with the comment) is not merged into WordPress 6.2.

[carolinan]

I am trying to reproduce this. The excerpt displays for me when inside a query loop in a home/index/frontpage template, like in Twenty Twenty Three.

Can you provide more details?

Create a page whose content includes a query loop that contains a post excerpt block inside of it; e.g.

When you say "page" do you mean a literal, post type "page"?

Update: I tried a query block in a page post type, and the excerpt in the loop displays correctly.

It is unclear to me if the first report is with Gutenberg active, because in core, the block does not have an excerpt length attribute.

[tomjn]

@carolinan are you trying to reproduce with 6.2 or with the latest Gutenberg plugin? The root of the problem is that the block calls get_the_excerpt then tries to trim it down using an attribute, providing no opportunities for the filter to run and breaking back compat.

It is unclear to me if the first report is with Gutenberg active, because in core, the block does not have an excerpt length attribute.

It is not, my tests are on a client project with stock vanilla WP 6.2.

I used `excerptLength from a reading of the code, and assumed since your commit was from February that it would be in v6.2, though this was my attempt to work around the problem, not the problem itself.

https://github.com/WordPress/gutenberg/commit/86d527ce4f71b33e6637104046e07258b8e410de

This issue is specifically for the excerpt_length filter not being used on the excerpt block in WP 6.2, everything else is contextual.

[tomjn]

On WordPress 6.2, If I add a filter on the excerpt_length to set it to 2 words, the post excerpt block has more than 2 words which is incorrect. This is regardless of the location of the block.

[tomjn]

I've updated the initial report to remove references to the attributes to avoid further confusion

Expectation:

WP 6.2:

[carolinan]

Thank you for the update.

Test results: WordPress version: 6.2.0 No plugins macOS, Chrome, PHP 7.4.3.0 nginx Theme: Twenty Twenty-Three with an added functions.php file with the filter:

function mytheme_custom_excerpt_length( $length ) {
    return 2;
}
add_filter( 'excerpt_length', 'mytheme_custom_excerpt_length', 999 );

Homepage, front view: Excerpts with two words are showing:

Search result page displaying a post with generated and custom excerpts, front view:

Single post with sample text content and an excerpt block in the content, front view

I can not reproduce the issue. I only tested with a block theme.

[erikyo]

I have the same issue, similar to what @tomjn mentioned. I believe it can be resolved by making a slight change to the post-excerpt render callback in the following file: https://github.com/WordPress/gutenberg/blob/2ba9faa46ad1c162e2c968e9f66b96709fcaca8c/packages/block-library/src/post-excerpt/index.php#L27-L31

Proposed Modification:

$excerpt_length = apply_filters('excerpt_length', $attributes['excerptLength']);
$excerpt        = get_the_excerpt( $block->context['postId'] );

if ( isset( $excerpt_length ) ) {
    $excerpt = wp_trim_words( $excerpt, $excerpt_length );
}

By implementing this modification, we can retrieve the value of the PHP filter excerpt_length and ensure that the wp_trim_words function works as intended. What do you think, can it work?

[erikyo]

ok i get it... @carolinan PR that fixed the excerpt length is part of gutenberg 15.2 but Wordpress 6.2.x still uses version 15.1. is this the reason?

[erikyo]

@tomjn since WordPress 6.3 is about to be released with a new Gutenberg version, could you please close this issue, which I personally find misleading?

[tomjn]

That depends, is the problem solved in v6.3? In the current release of WP ( 6.2 ) excerpt length is not respected. If the issue has been resolved then the person who resolved it should have closed the issue. I'm only going to close the issue if the issue is resolved

[tomjn]

Also noting that while it's claimed the issue could not be reproduced in https://github.com/WordPress/gutenberg/issues/49612#issuecomment-1498930976, the screenshots clearly show excerpts with more than 2 words despite the filter

[erikyo]

yep because the current guteberg version included in WP 6.2.x is the 15.1 and only in the next one (6.3) the @carolinan PR that include that fix will be added! I think even now, if you install the gutenberg plugin the issue would be solved, it is related to the fact that WP does not use the latest version of Gutenberg.

[carolinan]

Also noting that while it's claimed the issue could not be reproduced in #49612 (comment), the screenshots clearly show excerpts with more than 2 words despite the filter

Where? Do you mean the user defined excerpt in the screenshot of the search results template? The filter effects the automatically generated excerpt.

The screenshot of "my test post" shows a single post view with the full post content and the excerpt block below it.

[carolinan]

I am still unable to reproduce it in WP 6.3-RC1-56280.

I add a functions.php file with

function mytheme_custom_excerpt_length( $length ) {
    return 2;
}
add_filter( 'excerpt_length', 'mytheme_custom_excerpt_length', 999 );

In the editor, the excerpt block option is unchanged, set to the block's default value of max 55 words. And the blog on the home page displays two words from the post:

[carolinan]

How can we move forward with this issue?

• Can anyone test it and confirm if this is still an issue now that 6.3.0 has been released?
• Can anyone provide more guidance on what the expected result is? Adding a filter now breaks the excerpt length control in the block.

I activated Twenty Twenty-One and added the excerpt length filter above in functions.php. Next, I created a new post with some text and the excerpt block. In the single post view, the excerpt block does not show the number of words selected in the setting in the block sidebar; it shows the incorrect two words, the number decided by the filter. On the home / front page, the classic theme template uses the_excerpt() and shows the correct two words.

https://github.com/WordPress/gutenberg/assets/7422055/23cb02f5-d80e-4cf6-9fe4-d3a4adbef885

[erikyo]

With the release of WordPress 6.3 the problem was solved for me and now the excerpt block has the possibility to adjust the length of the text (thank you)

even if I use the filter (exactly copy and paste from here) it works as expected, so all perfect on my side

[carolinan]

I expect the setting on the block to override the filter. Because otherwise, the setting will seem broken for non-developer users, or basically for any user who isn't aware that the filter is applied.

[erikyo]

On my side isn't as you expecting and the filter has the priority over the block settings.

Maybe you want to skip the filter when the attributes['excerptLength'] is set, is that right?

[tomjn]

Where? Do you mean the user defined excerpt in the screenshot of the search results template? The filter effects the automatically generated excerpt.

That is the problem, and source of confusion. It's supposed to affect all excerpts, not just auto-generated excerpts, and that's how it worked for more than a decade! This is new and undocumented behaviour, a backwards compatibility break. Nothing is mentioned about a difference between user vs auto-generated excerpts in https://developer.wordpress.org/reference/hooks/excerpt_length/

For context, what lead me to this issue was a client requirement that excerpts have a maximum length, and under no circumstances, of any kind, can they exceed that length. the_excerpt(); respected this, the block did not.

Note that the introduction of this slider does not solve the original problem, and actually could be a problem for clients that already have filters like this and workarounds since it's now possible to change the max excerpt length where it wasn't before, and there is no official mechanism to turn it off.

In the single post view, the excerpt block does not show the number of words selected in the setting in the block sidebar; it shows the incorrect two words, the number decided by the filter.

This is highly desirable and intended, and fits with the expectations of how that filter works. "Fixing this" would be introducing a bug.

Also note that if the excerpt length attribute is not defined, due to it being saved pre-6.3, no excerpt max words is applied at all!

Maybe you want to skip the filter when the attributes['excerptLength'] is set, is that right?

This would make sense, though I would want the ability to not have that control, or for it to be ignored/overriden via theme.json.

The whole point of using excerpt_length was to provide a cast iron guarantee that showing the excerpt would only show X words, which was the case for more than a decade, and is now no longer reliable.

[carolinan]

I don't appreciate the tone and will not continue to participate.

[erikyo]

@tomjn the excerpt text is limited by the filter because the php render callback is using get_the_excerpt which is affected by that filter and, in short, the functionality remains consistent with its historical behavior.

However, what @carolinan said I think it's true and you shouldn't display to the user a number of words that he can't show. Just tossing an idea out there... what if the slider thing had a maximum limit set by the filter?

[tomjn]

That's an interesting proposal, but it doesn't seem in keeping with what I've seen of block themes. What do you think about an upper/lower limit defined in theme.json or predefined values similar to spacing padding etc?

[erikyo]

To me, yes, being able to set it up using theme.json sounds like a good plan. That way, we wouldn't need to use with the filter. But here's the thing: if I set it in both places, which one wins? Like, which value gets used?

Plus, even if we do that, it doesn't fix the issue of keeping things consistent between the filter's value and what you can pick in the editor (indeed it would be an additional value to take into account).

[tomjn]

I don't like the change in behaviour as it means breaking old stuff in classic themes, but even if the PHP filter worked the way I expected, the slider and being able to set it's bounds or availability is still useful to have. I think for the PHP filter the answer may well be that the documentation needs updating if it's not considered a bug.

If I were to build a new site today with my first block theme in 6.3 I'd assume the slider was how you'd do it and wonder if there's a way to set it everywhere, and may even go as far as filtering block attributes on the PHP side.

I do think discussion of the slider might be best in a new issue though. It's related but not the same.

[tomjn]

Also I realise I never articulated why someone might want to apply the excerpt filter to a user written excerpt and not just auto-generated excerpts:

• Preventing visual issues caused by very long excerpts
• writing style guides
• excerpts being used in places that are printed
• etc..

The benefit of these was that you could use conditionals, perhaps to shorten the display for specific situations, have a short excerpt in the homepage but a full excerpt in the RSS etc, but before the slider was added in 6.3 that wasn't possible in block themes.

In my case, a client did not want excerpts to go on to a 4th line for aesthetic and design reasons, but also used user specified excerpts for SEO reasons, leading me to raise this issue. The excerpt length slider on the excerpt block did not exist at the time.

[t-hamano]

If the user is changing the length of the excerpt in the Post Excerpt block, but still wants to control the length of the excerpt text by forcing it, the render_block_data hook could be used.

function gutenberg_block_test( $parsed_block ) {
    if ( 'core/post-excerpt' === $parsed_block['blockName'] ) {
        $parsed_block['attrs']['excerptLength'] = 2;
    }
    return $parsed_block;
}
add_filter( 'render_block_data', 'gutenberg_block_test' );

[t-hamano]

Hi @tomjn,

I just wanted to see the gist of this issue.

If the number of characters is limited by excerpt_length() filter, do you want to give priority to the number of characters filtered by excerpt_length, no matter what the "MAX NUMBER OF WORDS" setting of the Excerpt block is?

Please let me know if the approach I have presented in this comment is your solution.

I would be happy if you could tell me the problems you think and the results you expect with the latest Gutenberg.

[tomjn]

I moved on from the project where this was an issue a while ago, and had filtered the block attributes at the time to force the length attribute regardless of the block markup.

I had a chat with @carolinan and it the problem of how long should an excerpt be and wether it should be truncated is a lot messier and touches a lot more places than this, more than this issue could encompass

[annezazu]

👋🏼 Hey folks! I'm doing a sweep of high priority labeled issues and have removed the label from this issue. For context, the label should be resolved for widespread, high impact issues requiring quick action. This issue doesn't seem to fit that description due to the lack of replication and broader considerations. If that feels wrong or off, please just let me know as I want to get this label in a better place but want to get the remaining items right.

[justintadlock]

That is the problem, and source of confusion. It's supposed to affect all excerpts, not just auto-generated excerpts, and that's how it worked for more than a decade! This is new and undocumented behaviour, a backwards compatibility break. Nothing is mentioned about a difference between user vs auto-generated excerpts in https://developer.wordpress.org/reference/hooks/excerpt_length/

That's never been how the excerpt_length filter hook works, even though it's not documented for the function. It's always only applied to the auto-generated excerpt and not manual. The idea was that if the user manually wrote an excerpt, they expect the excerpt to be output as they wrote it on the front end.

The documentation for the_excerpt() specifically mentions it:

...It uses get_the_excerpt() to first generate a trimmed-down version of the full post content should there not be an explicit excerpt for the post...

If you read the user-contributed notes for get_the_excerpt() going back for years, you'll see folks working around this for various use cases:

• https://developer.wordpress.org/reference/functions/get_the_excerpt/#user-contributed-notes
• https://developer.wordpress.org/reference/functions/get_the_excerpt/#comment-3320

Here's a note from a theme I built 12 years ago that mentions it affects auto-excerpts:

• https://github.com/justintadlock/news/blob/master/functions.php#L308-L317

Here's a StackExchange question from 13 years ago that explains it as well:

• https://wordpress.stackexchange.com/questions/6310/how-to-control-manual-excerpt-length

---

Given the long history of excerpts working this way in Core, I'm going to relabel this ticket as an enhancement. Any changes to the current behavior of manual/explicit excerpts should take into account backward compatibility for users who expect their manually written excerpts to appear.

[talldan]

I just found this issue while investigating another bug with post excerpts.

I was very confused reading it.

I'm going to close this as it was never a bug or a regression (as explained by @justintadlock). I don't think it's worth keeping the issue open given it was never raised with the intention of being an enhancement and no-one has specifically requested it as one.

Changing the way it works also has some pretty big back compat concerns for existing sites, so I can't imagine this being changed. (also it would have to be a trac issue, the block uses get_the_excerpt which is implemented in WordPress core)