feat!: make `permission_callback` arg required #73

justlevine · 2025-09-13T12:22:41Z

What

This PR makes permission_callback a required argument.

Warning

This is a breaking change.
As a result of this change, Abilities that do not include a permission_callback will now return a WP_Error.

Why

Fixes Make the permission_callback argument required #68

How

Specific implementation notes on diff.

Copilot

Pull Request Overview

This PR makes the permission_callback argument required for ability registration, introducing a breaking change to prevent abilities from running without proper permission checks.

Removes support for abilities without permission callbacks
Updates validation logic to require permission_callback as a mandatory parameter
Removes tests that verify null permission callback behavior

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/rest-api/wpRestAbilitiesRunController.php	Removes test for abilities without permission callbacks
tests/unit/abilities-api/wpRegisterAbility.php	Minor formatting cleanup
tests/unit/abilities-api/wpAbilitiesRegistry.php	Adds test to verify rejection of abilities without permission callbacks
includes/abilities-api/class-wp-ability.php	Updates validation logic to require permission_callback and removes nullable type
includes/abilities-api/class-wp-abilities-registry.php	Updates documentation to reflect required permission_callback
includes/abilities-api.php	Reorders parameter documentation for consistency
docs/3.registering-abilities.md	Updates documentation to mark permission_callback as required

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

tests/unit/abilities-api/wpAbilitiesRegistry.php

Co-authored-by: Copilot <[email protected]>

codecov · 2025-09-13T12:26:12Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.91%. Comparing base (59d8ec6) to head (c99eaae).

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk      #73      +/-   ##
============================================
+ Coverage     83.33%   86.91%   +3.58%     
+ Complexity       96       94       -2     
============================================
  Files             8        8              
  Lines           516      512       -4     
============================================
+ Hits            430      445      +15     
+ Misses           86       67      -19

Flag	Coverage Δ
unit	`86.91% <100.00%> (+3.58%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

justlevine · 2025-09-13T12:24:20Z

includes/abilities-api.php

 *   description?: string,
- *   input_schema?: array<string,mixed>,
- *   output_schema?: array<string,mixed>,


Required before optional.

includes/abilities-api/class-wp-abilities-registry.php

justlevine · 2025-09-13T12:28:38Z

includes/abilities-api/class-wp-ability.php

-		if ( empty( $this->get_input_schema() ) ) {
-			return call_user_func( $this->permission_callback );
-		}


This is handled by ::validate_input()

The point is that, if there is no schema, then we don't pass any input. What we agreed upon was that if someone wants to explicitly pass null, they need to provide the schema. This builds predictability, and that's why the condition is in place also here.

Previously, I considered adding a method for calling these callbacks, but it felt like more code than necessary. However, having a method could help document this expected behavior better.

What we agreed upon was that if someone wants to explicitly pass null, they need to provide the schema.

Can you clarify? If I understood you correctly that behavior is what this change enforces.

Previously diff, if there was no input schema, then any $input would get stripped and the execution callback would be be handled as if nothing was passed. As a result, if the schema allows an "explicit null, then the ability would still execute even if the supplied $input doesn't meet the correct shape.

With this diff, both no $input must be passed and the schema must support a null value for the ability to execute successfully.

(If you're referring to our internal ability to differentiate between null and unset, that was just one one of the concerns about going to mixed that I raised on #58 . Until core's minimum PHP supports named arguments, nothing can compete with either the dx or future-compat of a partially-sealed array, nullable or otherwise. 🤷‍♂️)

I'm not sure I follow, so let me explain it in a different way:

if there is no input schema declared, it means there is no input to pass, so the callback should be executed with no arguments

If there is an input schema provided, it means it needs to be validated. This also allows passing an explicit null as the first argument, but also any other type of data: string, boolean, array, etc.

if there is no input schema declared, it means there is no input to pass, so the callback should be executed with no arguments

If there is no input schema declared, but a user/mcp/traditional-tool nevertheless passes an $input what should the expected behavior be? E.g.

$post_getter => wp_get_ability( 'my-custom/get-posts ' ); $posts = $post_getter->execute(); $posts_explicit_null = $post_getter->execute( null ); $just_products = $post_getter->execute( [ 'post_type' => 'product' ] );

$posts will return an error if an input_schema is defined, but will proceed if an input schema is not defined. (✔️ both ways)

$posts_explicit_null

old: will pass if no input_schema is defined, will fail if an input_schema is defined but does not allow for an explicit null.

this pr: will fail both if the input_schema is defined but doesn't allow for an explicit null and if no input_schema is defined. (because you're not passing "nothing", you're explicitly passing a null)

$just_products : Here's the IRL dx footgun:

old: if no input_schema is defined (IRL: filtering isn't supporting for by this specific ability), it will **return the same results as both $posts and $post_explicit_null. Only if there is an input_schema defined will you get a WP_Error saying that e.g. the expected argument is called type not post_type .
(or worse, that you should have called $get_all_posts->execute( int $amount_of_posts ) and that ability will never be able to support post type filtering without breaking schema changes. This was my argument against Fix $input type hint in WP_Ability #58 and why mixed is arguably the worst thing we could do to this or any public API 🤷)

this: will fail both if the input_schema is defined (as it should), but also if there is no input_schema, correctly alerting the user that this is likely not the WP_Ability they're looking for.

I believe the behavior here is still ideal, even if the change to mixed negates a small part of the DX win.

Either way once clarified, I'll add backfill the necessary unit test to guarantee the behavior here doesn't change unintentionally

If there is no input schema, and there is any input provided, then validate_input() kicks in. Reference:

abilities-api/includes/abilities-api/class-wp-ability.php

Lines 275 to 289 in 59d8ec6

protected function validate_input( $input = null ) {

$input_schema = $this->get_input_schema();

if ( empty( $input_schema ) ) {

if ( null === $input ) {

return true;

}

return new \WP_Error(

'ability_missing_input_schema',

sprintf(

/* translators: %s ability name. */

__( 'Ability "%s" does not define an input schema required to validate the provided input.' ),

$this->name

)

);

}

So there are no concerns that someone passes an input that can't be validated due to a missing input schema. That's why we can safely skip the argument, making a better experience for devs as they don't have to always include ( $input = null ) for the callbacks that don't consume anything.

It's all a minor thing about ensuring we don't pass the default null when it is not needed.

Okay now I'm sure we're not following each other, because that's literally the initial comment I left here explaining why I removed this conditional here, except you're using it to (seemingly) justify the opposite of what I am 😭

I'll add the unit tests for the above edge cases, if that doesn't clear things up (for either of us), i'll revert here and open a separate bug report that follows up #61 .

Works for me.

The key here is that it needs to be impossible to pass unvalidated input through to permission_callback (and similarly execute_callback).

@justlevine You're right that technically we can drop the empty( $this->get_input_schema() ) condition because if this is the case and the input isn't null, the validate_input method would return a WP_Error and this code wouldn't be reached.

That being said, I do think this is good to keep as a safe guard for good measure. We have the same in do_execute. Having this extra check in there ensures directly before the relevant call that we don't pass any input (i.e. enforce null) when there's no input schema.

Is it necessary? No. Is it a good measure for defensive coding and clarifying the importance of this to someone new working on this code in the future? Yes, I think so.

IMO we should just keep it. It doesn't hurt.

tests/unit/rest-api/wpRestAbilitiesRunController.php

justlevine · 2025-09-13T12:43:13Z

tests/unit/abilities-api/wpAbilitiesRegistry.php

This is here because reordering the prepare_properties() by required/not-required (et al) seemed like the least intrusive way to do this, but it's more of an Integration test pattern and not pure PHPUnit.

If wp-core needs vanilla unit tests, we can relocate and refactor these tests to use new WP_Ability()

github-actions · 2025-09-13T12:44:16Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: justlevine <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: johnbillion <[email protected]>

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

gziolo

I had only one minor feedback where I explained the reasoning why to keep extra logic. The rest of the changes look exactly as expected 💯

includes/abilities-api/class-wp-abilities-registry.php

gziolo · 2025-09-15T09:12:32Z

includes/abilities-api/class-wp-ability.php

-		if ( empty( $this->get_input_schema() ) ) {
-			return call_user_func( $this->permission_callback );
-		}


The point is that, if there is no schema, then we don't pass any input. What we agreed upon was that if someone wants to explicitly pass null, they need to provide the schema. This builds predictability, and that's why the condition is in place also here.

tests/unit/rest-api/wpRestAbilitiesRunController.php

feat!: make permission_callback arg required

b99744c

justlevine requested a review from Copilot September 13, 2025 12:22

Copilot AI reviewed Sep 13, 2025

View reviewed changes

tests/unit/abilities-api/wpAbilitiesRegistry.php Outdated Show resolved Hide resolved

Update tests/unit/abilities-api/wpAbilitiesRegistry.php

4d7ba35

Co-authored-by: Copilot <[email protected]>

tests: add WP_Ability::prepare_properties to coverage

b08da61

justlevine commented Sep 13, 2025

View reviewed changes

justlevine marked this pull request as ready for review September 13, 2025 12:44

justlevine requested review from johnbillion, gziolo and felixarntz September 13, 2025 12:44

This was referenced Sep 13, 2025

Make the permission_callback argument required #68

Open

Fix has_permission() return type inconsistency (Issue #67) #76

Open

gziolo added the [Type] Bug Something isn't working label Sep 15, 2025

gziolo assigned justlevine Sep 15, 2025

gziolo reviewed Sep 15, 2025

View reviewed changes

Merge branch 'trunk' into feat/require-permission_callback

c99eaae

	protected function validate_input( $input = null ) {
	$input_schema = $this->get_input_schema();
	if ( empty( $input_schema ) ) {
	if ( null === $input ) {
	return true;
	}
	return new \WP_Error(
	'ability_missing_input_schema',
	sprintf(
	/* translators: %s ability name. */
	__( 'Ability "%s" does not define an input schema required to validate the provided input.' ),
	$this->name
	)
	);
	}

feat!: make permission_callback arg required #73

Are you sure you want to change the base?

feat!: make permission_callback arg required #73

Uh oh!

Conversation

justlevine commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

codecov bot commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gziolo Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justlevine Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 13, 2025

Uh oh!

gziolo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

feat!: make `permission_callback` arg required #73

feat!: make `permission_callback` arg required #73

justlevine commented Sep 13, 2025 •

edited

Loading

codecov bot commented Sep 13, 2025 •

edited

Loading

gziolo Sep 15, 2025 •

edited

Loading

justlevine Sep 15, 2025 •

edited

Loading