dev: add `wp_ability_args` filter [Proposal] #74

justlevine · 2025-09-13T17:03:05Z

What

This PR exposes the ~~ability_args~~ wp_ability_args filter as a way to centrally extend and change the behavior of registered abilities.

Why

Part of Proposal: Provide extensibility for individual abilities #39
This is a counterproposal to Propose filters to use with the registered ability #37 :
- Placing the filter in WP_Abilities_Registry::register() makes behavior robust against WP_Ability class overloads and keeps the lifecycle + validation intact. In other words: filtering abilities remains idempotent to their non-filtered versions.
- Smaller API footprint (one filter vs several) means smaller chance for future tech debt.
- Arrays continue to be unbeaten when it comes to future backcompat.

How

wp_ability_args is used before the merge to core, but it should be changed to abilities_api as part of 6.9 IMO.
Once merged into core, we can just add_filter( 'ability_args', function ( ... ) { return apply_filters_deprecated( 'wp_ability_args' ); to allow anyone who builds something between now and December time to transition.

Copilot

Pull Request Overview

This PR introduces the wp_ability_args filter to the Abilities API, allowing developers to modify ability arguments before validation and instantiation. This provides a centralized mechanism for extending and customizing ability behavior.

Adds a filter hook in the registry's register method to modify ability arguments
Includes comprehensive documentation with usage examples
Uses wp_ prefix to avoid naming collisions before core integration

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
includes/abilities-api/class-wp-abilities-registry.php	Adds the `wp_ability_args` filter in the register method before validation
docs/5.hooks.md	Documents the new filter with detailed usage examples and parameters

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

docs/5.hooks.md

Copilot · 2025-09-13T17:03:46Z

docs/5.hooks.md

+  $args['has_permissions' ] = static function ( $input = null ) use ( $args ) {
+    $previous_check = is_callable( $args['has_permissions'] ) ? $args['has_permissions']( $input ) : true;
+
+    // If we already failed, no need for stricter checks.
+    if ( ! $previous_check || is_wp_error( $previous_check ) ) {
+      return $previous_check;
+    }
+
+    return current_user_can( 'my_custom_ability_cap', $args['name'] )
+  }


This creates a circular reference issue. The closure captures $args by reference, but then tries to access $args['has_permissions'] which would be the closure itself, causing infinite recursion. The original callback should be stored in a separate variable before reassigning.

Suggested change

$args['has_permissions' ] = static function ( $input = null ) use ( $args ) {

$previous_check = is_callable( $args['has_permissions'] ) ? $args['has_permissions']( $input ) : true;

// If we already failed, no need for stricter checks.

if ( ! $previous_check || is_wp_error( $previous_check ) ) {

return $previous_check;

}

return current_user_can( 'my_custom_ability_cap', $args['name'] )

}

$previous_has_permissions = $args['has_permissions'] ?? null;

$args['has_permissions'] = static function ( $input = null ) use ( $args, $previous_has_permissions ) {

$previous_check = is_callable( $previous_has_permissions ) ? $previous_has_permissions( $input ) : true;

// If we already failed, no need for stricter checks.

if ( ! $previous_check || is_wp_error( $previous_check ) ) {

return $previous_check;

}

return current_user_can( 'my_custom_ability_cap', $args['name'] );

};

I dont think this is true 🤔 we're only calling inside the function, not reassigning.

docs/5.hooks.md

codecov · 2025-09-13T17:05:32Z

Codecov Report

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

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk      #74      +/-   ##
============================================
+ Coverage     83.33%   83.36%   +0.03%     
  Complexity       96       96              
============================================
  Files             8        8              
  Lines           516      517       +1     
============================================
+ Hits            430      431       +1     
  Misses           86       86

Flag	Coverage Δ
unit	`83.36% <100.00%> (+0.03%)`	⬆️

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.

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

github-actions · 2025-09-13T17:17:48Z

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]>

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

gziolo

I left some minor feedback. Overall, I'm very much in favor of the proposed extensibility option.

gziolo · 2025-09-15T10:17:21Z

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

+		 * @param array<string,mixed> $args The arguments used to instantiate the ability.
+		 * @param string              $name The name of the ability, with its namespace.
+		 */
+		$args = apply_filters( 'wp_ability_args', $args, $name );


Minor note, this could get moved after all checks against $name to ensure it doesn't get processed on abilities that have an incorrect name.

My intent here is intentionally the opposite, since it allows changes/recoverability of the $name while still ensuring it passes the necessary validation for downstream checks.

IMO (pseudocode):

add_filter( 'register_ability_args', // Or whatever prefixes/missing-namespaces are enforced by validation. static fn ( &$args, $original_name ) => $args['name'] = sprintf( '!$#@#_%s', str_replace( '/', '_', $original_name ), 10, 2 );

should not be allowed since it means adapters/downstream cant reliably depend on the namespace/shape for their needs.

Meanwhile, I'm believe that e.g.

add_filter( 'register_ability_args', static function( $args,) { if ( str_starts_with( 'my_legacy_namespace/', $args['name' ) ) { $args['name'] = str_replace( 'my_legacy_namespace/', 'my_new_namespace/', $args['name'] ); } } );

should still be flexible enough for any downstream/back-compat considerations without making the expected shape of the Ability API unreliable, but I'm happy to evaluate other use cases (the only one I can think of is if a user intentionally registers a namespace wrong initially, but the immediate error they face should prevent that from ever shipping and thus preempting the need for a downstream filter)

(PS: moving this to after the checks after a 6.9 merge is a nonbreaking change. moving it up to enforce name validation

$args is not used to read the name. It's a separate variable $name which can't be modified by the hook.

Indeed 🤦 too much task switching that even with the function in front of me I got our $name handling confused with $ability_class. Sorry for wasting your time 😬

I'll move it down to after the ->is_registered() check. When that and the other comments are handled I'll ping you for re-review 🙇

No worries, it's why additional eyes are helpful to the implementation from a different perspective 👍🏻

gziolo · 2025-09-15T10:20:35Z

docs/5.hooks.md

+> [!IMPORTANT]
+> This filter is prefixed with `wp_` to avoid potential naming collisions.
+> Once merged into WordPress core, the prefix will likely be removed to preserve backward-compatibility.


I would go with the final name from the start to avoid the hassle. register_ability_args should be distinct enough.

register_ability_args is better than ability_args I had in mind too as it aligns with register_{post_type|taxonomy} args.

I'm closely familiar with register_block_type_args, which was likely inspired by these you listed.

gziolo · 2025-09-15T10:21:34Z

docs/5.hooks.md

+  );
+
+  // Even if they're callbacks.
+  $args['has_permissions' ] = static function ( $input = null ) use ( $args, $ability_name ) {


This should be permission_callback rather than has_permissions.

gziolo · 2025-09-17T08:10:16Z

We will also need some basic unit test coverage to illustrate the expected behavior better and prevent future regressions.

I plan to add some tests today to:

Add execute actions to the ability object #56

We can coordinate how to ensure we avoid more complex merge conflicts.

dev: add wp_ability_args filter

eb16f47

justlevine requested a review from Copilot September 13, 2025 17:03

Copilot AI reviewed Sep 13, 2025

View reviewed changes

justlevine and others added 2 commits September 13, 2025 20:10

Update docs/5.hooks.md

15664a3

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

docs: fix has_permissions overload example

dc10954

justlevine requested a review from gziolo September 13, 2025 17:16

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

justlevine mentioned this pull request Sep 13, 2025

Proposal: Provide extensibility for individual abilities #39

Open

gziolo reviewed Sep 15, 2025

View reviewed changes

gziolo assigned justlevine Sep 15, 2025

gziolo added the [Type] Enhancement New feature or request label Sep 15, 2025

dev: add wp_ability_args filter [Proposal] #74

Are you sure you want to change the base?

dev: add wp_ability_args filter [Proposal] #74

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!

Copilot AI Sep 13, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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!

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!

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 commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dev: add `wp_ability_args` filter [Proposal] #74

dev: add `wp_ability_args` filter [Proposal] #74

justlevine commented Sep 13, 2025 •

edited

Loading

codecov bot commented Sep 13, 2025 •

edited

Loading

github-actions bot commented Sep 13, 2025 •

edited

Loading

gziolo commented Sep 17, 2025 •

edited

Loading