Skip to content

Abilities API: Say that the callback ran when output validation fails - #15333

Closed
MicahelE wants to merge 1 commit into
WordPress:trunkfrom
MicahelE:fix/66433-ability-callback-executed
Closed

MicahelE wants to merge 1 commit into
WordPress:trunkfrom
MicahelE:fix/66433-ability-callback-executed

Conversation

@MicahelE

@MicahelE MicahelE commented Nov 2, 2026

Copy link
Copy Markdown

The problem

When an ability runs, two things happen in order:

  1. Its callback runs.
  2. WordPress checks the callback's output against the output schema.

If the check in step 2 fails, the caller gets an ability_invalid_output error. But step 1 has already happened, so anything the callback changed is already saved.

The error doesn't say that. The caller may think nothing happened and try again, which makes the same change a second time.

The fix

The error now says that the callback ran. Here is the REST response:

Before

{
	"code": "ability_invalid_output",
	"data": null
}

After

{
	"code": "ability_invalid_output",
	"data": { "callback_executed": true }
}

The error from a wp_ability_validate_output filter gets the same flag, and any data the filter set is kept.

What the flag means

  • callback_executed: true means the callback ran. It doesn't mean the callback changed anything, because WordPress can't know that.
  • Errors from before the callback runs, like bad input or a failed permission check, don't get the flag.

What stays the same

  • The error code, the message and the HTTP status don't change.
  • wp_after_execute_ability still doesn't fire when the output check fails. The ticket mentions this too, but code using that action may expect valid output, so I think it should be discussed on the ticket first.
  • If the callback returns its own WP_Error, that error doesn't get the flag.

How to test

Run the new tests:

vendor/bin/phpunit --group 66433

Without the fix, 4 of the 6 tests fail. The other 2 check that the flag is not added when the callback didn't run, so they pass either way.

With the fix, these all pass on single site and multisite, on PHP 8.2 and MySQL 8.4:

  • The new tests.
  • --group abilities-api.

The REST run controller tests also pass on single site. PHPCS is clean on all three changed files, and PHPStan is clean on the changed source file.

One thing to check when committing

The docblock says @since 7.2.0. This ticket doesn't have a 7.2 milestone yet, so that needs changing if this lands in a later release.

Trac ticket: https://core.trac.wordpress.org/ticket/66433

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Reproducing the bug, writing the patch and tests, running the checks, and drafting this description.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

`WP_Ability::execute()` runs the callback and then validates its output. When validation fails, the caller gets an error but cannot tell that the callback already ran, so it may retry and repeat the same change.

The error data now includes `callback_executed` set to true. This also applies to errors from the `wp_ability_validate_output` filter, and any data they set is kept.

See #66433.
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props micahele, gziolo, zaguiini.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@github-actions

github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

@gziolo
gziolo requested a review from zaguiini November 6, 2026 12:37

@gziolo gziolo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for working on this, @MicahelE! I agree the caller should know that the callback already ran.

I'd like to suggest a different approach before we go into details. I don't think we need the callback_executed flag. validate_output() is only called from execute(), after the callback. So an ability_invalid_output error already means the callback ran.

What do you think about keeping the output in the error data instead (for example under output)? It is more useful for the caller. They can see what the callback produced, like the ID of a created post, and decide what to do instead of retrying blindly. It also works when the wp_ability_validate_output filter returns its own error code.

One thing to be careful about is REST. All error data goes to the client, and this output failed the schema check. It may contain data the client should not see, or values that can't be encoded as JSON. So I'd keep the output for PHP callers only and remove it in the REST run controller. REST clients still know the callback ran from the error code.

@zaguiini, as the ticket author, does this match what you had in mind?

@zaguiini

zaguiini commented Nov 6, 2026

Copy link
Copy Markdown
Member

Yes @gziolo, and output is better than the flag. The caller can see what was saved, not only that something ran. I agree that ability_invalid_output already says that the callback ran, so we can drop callback_executed.

I have no strong opinions about the REST run controller.

One question: should output also be in the data when the wp_ability_validate_output filter returns its own error code? You mention that case, and I'd like to make sure the patch covers it.

@gziolo

gziolo commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

One question: should output also be in the data when the wp_ability_validate_output filter returns its own error code? You mention that case, and I'd like to make sure the patch covers it.

The code looks as follows today:

$validity = apply_filters( 'wp_ability_validate_output', $is_valid, $output, $this->name );
if ( false === $validity ) {
	return new WP_Error( 'ability_invalid_output', __( 'Invalid output.' ) );
}
if ( is_wp_error( $validity ) && $validity->has_errors() ) {
	return $validity;
}
return true;

The filter receives the output, but if it returns false, it would swallow the output. So we should that handling for consistency 👍🏻

@gziolo

gziolo commented Nov 20, 2026

Copy link
Copy Markdown
Member

I took it over to bring it to the finish line in #16122. Thank you @MicahelE for starting the work. I'll see if we can still land it in WP 7.2.

@gziolo gziolo closed this Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants