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 87.45%. Comparing base (409a77e) to head (a1b27ab).
⚠️ Report is 1 commits behind head on trunk.

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk      #73      +/-   ##
============================================
+ Coverage     83.84%   87.45%   +3.60%     
+ Complexity       96       95       -1     
============================================
  Files             8        8              
  Lines           520      518       -2     
============================================
+ Hits            436      453      +17     
+ Misses           84       65      -19

Flag	Coverage Δ
unit	`87.45% <100.00%> (+3.60%)`	⬆️

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.

includes/abilities-api.php

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.

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.

Can we bring it back here as discussed?

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

That's the only remaining item to approve and land this PR.

I addressed it with 00d5099.

tests/unit/rest-api/wpRestAbilitiesRunController.php

tests/unit/abilities-api/wpAbilitiesRegistry.php

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: felixarntz <[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

includes/abilities-api/class-wp-ability.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 felixarntz, gziolo and johnbillion September 13, 2025 12:44

This was referenced Sep 13, 2025

Make the permission_callback argument required #68

Closed

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

Merged

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

gziolo reviewed Sep 23, 2025

View reviewed changes

includes/abilities-api/class-wp-ability.php Show resolved Hide resolved

gziolo added 2 commits September 23, 2025 11:50

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

00d5099

Merge branch 'trunk' into feat/require-permission_callback

a1b27ab

gziolo approved these changes Sep 23, 2025

View reviewed changes

gziolo enabled auto-merge (squash) September 23, 2025 09:52

gziolo merged commit 2f3cda7 into WordPress:trunk Sep 23, 2025
17 checks passed

justlevine mentioned this pull request Sep 27, 2025

Make the required argument elements required justlevine/abilities-api#6

Closed

feat!: make permission_callback arg required #73

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!

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!

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!

Uh oh!

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

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

github-actions bot commented Sep 13, 2025 •

edited

Loading