feat!: make permission_callback arg required

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.

[justlevine]

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

• FixesMake 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.}

[codecov]

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.

[justlevine]

This is handled by ::validate_input()

[gziolo]

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.

[gziolo]

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.

[justlevine]

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. 🤷‍♂️)

[gziolo]

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.

[justlevine]

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 .

[gziolo]

Works for me.

[felixarntz]

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.

[gziolo]

Can we bring it back here as discussed?

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

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

[gziolo]

I addressed it with 00d5099.

[github-actions]

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 <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: johnbillion <johnbillion@git.wordpress.org>

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 💯

[gziolo]

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.