Add Filtering Capabilities for Registered Abilities #115

galatanovidiu · 2025-10-14T08:37:35Z

Summary

Closes #38.

Adds querying and filtering capabilities to the Abilities API, allowing developers to efficiently find and retrieve specific abilities from potentially thousands of registered abilities.

This PR introduces the WP_Abilities_Query class and extends wp_get_abilities() to accept filtering arguments, enabling server-side filtering by category, namespace, meta properties, search terms, and more.

Changes

New Features

New WP_Abilities_Query class - WordPress-standard query interface for filtering abilities
Enhanced wp_get_abilities() function - Now accepts optional $args parameter for filtering
Multiple filter types:
- category - Filter by category slug (single or array)
- namespace - Filter by namespace (single or array)
- search - Search in name, label, and description
- meta - Filter by meta properties (show_in_rest, annotations, custom meta)
- orderby - Sort by name, label, or category
- order - Sort direction (ASC/DESC)
- limit/offset - Pagination support

Implementation Details

All filters use AND logic between different filter types
Multiple values in category or namespace use OR logic
Meta filters support nested arrays with AND logic
Single-pass filtering for optimal performance

Documentation

New comprehensive documentation in docs/8.querying-filtering-abilities.md
Updated docs/4.using-abilities.md with filtering examples
Includes a quick reference table and detailed examples

Backward Compatibility

Fully backward compatible - existing code calling wp_get_abilities() without arguments continues to work unchanged.

…lities

github-actions · 2025-10-14T08:37:49Z

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: galatanovidiu <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: justlevine <[email protected]>
Co-authored-by: jonathanbossenger <[email protected]>
Co-authored-by: emdashcodes <[email protected]>

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

codecov · 2025-10-14T08:38:48Z

Codecov Report

❌ Patch coverage is 93.82716% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.66%. Comparing base (c1b24b8) to head (8a5c01f).
⚠️ Report is 1 commits behind head on trunk.

Files with missing lines	Patch %	Lines
...ncludes/abilities-api/class-wp-abilities-query.php	94.93%	8 Missing ⚠️
includes/bootstrap.php	0.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #115      +/-   ##
============================================
+ Coverage     86.65%   87.66%   +1.00%     
- Complexity      148      211      +63     
============================================
  Files            18       19       +1     
  Lines           982     1143     +161     
  Branches         92       92              
============================================
+ Hits            851     1002     +151     
- Misses          131      141      +10

Flag	Coverage Δ
javascript	`93.04% <ø> (ø)`
unit	`86.30% <93.82%> (+1.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.

Public constants are converted to private static properties Additionally, validation methods are updated to use guard clauses, and some boolean logic is simplified.

JasonTheAdams

Great work, @galatanovidiu! Left a few suggestions!

JasonTheAdams · 2025-10-14T15:40:56Z

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

+	 * @since n.e.x.t
+	 * @var int
+	 */
+	private static $no_limit = -1;


Why is this a static property instead of a constant? Same for the static properties below.

Here should be fine to use const like here:

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

Line 29 in c1b24b8

protected const DEFAULT_SHOW_IN_REST = false;

For arrays, PHP 7.2 is unhappy, so here:

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

Line 38 in c1b24b8

protected static $default_annotations = array(

It's a complex env to support WP core 😅

I'm not sure what you mean. Why would PHP 7.2 be unhappy for arrays as constant values? I believe arrays as scalar values was introduced in PHP 5.6.

In that case, it’s linter that is very strict and prohibits usage. That would be similar case to array short syntax.

Can we update the linter? const FOO = array( 'bar' => 123 ); is supported, and reducing our architecture quality to appease linting feels lame. Hahah!

As far as I’m aware that was discussed at WC US, and someone has to champion the proposal and adjustments to the codebase.

Good point! I initially implemented these as constants, but our PHP linter was flagging them with errors. To maintain compatibility with our linting rules (which appear to be stricter than PHP 7.2's actual capabilities), I converted them to private static properties.

That's unfortunate. Is this the right place to propose the change? https://github.com/WordPress/WordPress-Coding-Standards?

I found the Core Committer meeting notes, which include an entire section on the need for changes in coding standards. You can try in that GitHub repository, or raise it as a topic for the weekly dev chat (next one today).

includes/abilities-api.php

JasonTheAdams · 2025-10-14T15:42:45Z

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

+	 * @phpstan-param array{
+	 *   category?: string|array<string>,
+	 *   namespace?: string|array<string>,
+	 *   search?: string,
+	 *   meta?: array<string,mixed>,
+	 *   orderby?: string,
+	 *   order?: string,
+	 *   limit?: int,
+	 *   offset?: int,
+	 *   ...<string, mixed>
+	 * } $args


Let's define this as a type in the class docblock, and then use @phpstan-import-type in the wp_get_abilities function. We can then set that as the @param type in this method, too.

I've tried this, but it looks like @phpstan-import-type doesn't work in function docblocks (only in class docblocks)

Correct! It would go like this:

Add an AbilityQueryArgs type in the class docblock

Use it as the @param type for this method

Import and use it in the function

This is exactly what I tried and is not working.

@phpstan-import-type only works in class docblocks, not in function docblocks. PHPStan throws an error: "Parameter $args has invalid type AbilityQueryArgs".

The solution is to keep the full @phpstan-param array shape in both places:

Define @phpstan-type AbilityQueryArgs in the class docblock as the source of truth

Duplicate the full array shape using @phpstan-param in the function docblock

This reduces duplication within the class but we still need to duplicate it for standalone functions since @phpstan-import-type doesn't work outside of class contexts.

Please check d3275fd

JasonTheAdams · 2025-10-14T15:46:48Z

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

+		$this->validate_meta_arg();
+		$this->validate_orderby();
+		$this->validate_order();
+		$this->validate_pagination_args();


Hmm, these validation methods are interesting. They "validate" in the sense that they check if the provided value is valid, but then fallback on a default instead of notifying of the issue in any way. Is this how the WP_Query class works, so we're doing this for consistency? I feel like we should at least be calling doing_it_wrong so people know why there's unexpected behavior.

I should have used sanitize instead of validate
WP_Query also only sanitizes the args.
I can implement validation if you want, but I'd prefer to keep it simple.

Please check 68fea1b

Ah, gotcha. I'm inclined to let people know when they're straight up doing things wrong (I've personally felt the consternation of figuring out that I have a typo in a query), but won't push it if it's not recommended otherwise.

JasonTheAdams · 2025-10-14T15:50:34Z

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

+		usort(
+			$abilities,
+			static function ( $a, $b ) use ( $getter_method, $order_multiplier ) {
+				return strcasecmp( $a->$getter_method(), $b->$getter_method() ) * $order_multiplier;


Ohh, I like the use of $order_multiplier here! Clever! 😃

WP_Abilities_Query already returns all abilities when args is empty, making the backward compatibility check unnecessary.

Updates type hints to specify arrays of strings for 'category' and 'namespace' parameters.

Updates method names and related docblocks to clarify that query argument processing focuses on sanitization rather than validation.

Improves documentation to specify use of the query class for retrieving and filtering abilities.

justlevine · 2025-10-14T21:26:54Z

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

+ *
+ * @since n.e.x.t
+ */
+class WP_Abilities_Query {


From the docs it seems this class isn't meant to be consumed/extended directly (which IMO makes sense from a 6.9 iterative POV).

If so, can we mark the class final and add an @internal + a note pointing to wp_get_abilities( $args ) in the doc-block? Would give us more freedom to iterate in future versions.

justlevine

I'm concerned about using the WP_*_Query when that pattern is

used by core for DB lookups
often encouraged to be used directly versus getters (e.g. new WP_Term_Query() versus get_terms(). )

Neither afaik are true here and docs can only help so much.

From a code POV, we could also simplify implementation significantly if we weren't trying to mimic WP_Query. E.g. we don't need 011y, query getters, or pagination when we're just sorting/filtering an array in PHP.

justlevine · 2025-10-14T21:27:53Z

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

+	 * @since n.e.x.t
+	 *
+	 * @param array<string,mixed> $args Query arguments.
+	 *


Nit: I'm assuming the blank end-lines in the comments throughout this file are unintentional

Suggested change

*

This is a really fair point, @justlevine. Thinking on this, I wonder if this would be a good use for introducing an Abilities_Collection class, instead of a querying system like this. It would implement IteratorAggregate, ArrayAccess, and such, and be what the registry stores all the abilities into.

From there, it could have methods such as Abilities_Collection::with_category(...$categories) which returns an array (or another Abilities_Collection subset). If it's the latter, then folks can chain:

$abilities = wp_get_abilities() ->with_namespace('woo') ->with_category('orders');

This way, to your point, we're treating it more like an in-memory array rather than querying against an external system. Constructing a query is most important for efficiently retrieving the data in one go. But for something like this it's not really necessary.

What do you think, including @galatanovidiu?

If you feel this needs more time to define the API’s shape, we will have to postpone it to WordPress 7.0. This is a rather substantial change that needs some longer conversation, so contributors can have time to chime in and share their perspective on how the codebase evolves, so they can later replicate better patterns.

I agree with all of you.
I know we are in a hurry to have this functionality out and ready for 6.9, but I also like the idea of the Abilities Collection a lot. I've used Laravel collections a lot, and I know how natural and DX-friendly that is.

Because of that, I've prepared a POC here: #119

It's also important to consider performance. The proposal for collections will loop through once for the current set of abilities per filter. In contrast, in this PR, there is a single pass over the entire set, and all filters are applied to a single item at once. There is also an extensibility story that needs to be taken into account. WP_Query is at extreme with 44 occurrences of apply_filters() and apply_filters_ref_array(), but some sort of filtering will eventually need to be added, so custom filters can be executed, for example, when fetching abilities through the REST API.

This is a rather substantial change that needs some longer conversation,

I second @gziolo, but probably take it further than he.

While I'm a big fan of fluent APIs in general (and love how much simpler #119 reads), I don't think that us introducing the concept of a *_Collection into WordPress on the cusp of 6.9 is a great idea. It's also possible that the WP_Query parrten will turn out to be ideal in 7.x after we find a reason to have abilities be backed by something in the DB (a la plugins/themes/fonts), in which case preemptively going with a Collection pattern would be hard to untangle.

I'm hoping we can take the simplified methods from @galatanovidiu 's #119 but move them to private functions inside WP_Abilities_Registry. That would give us all the surface area we need for MVP filtering support in 6.9 (albeit via passed $args), while still keeping our hands free for whatever pattern we ultimately decide is best (when we have some unpressured time to reach the decision holistically).

Thanks for weighing in, folks! And for throwing together the draft so quickly, @galatanovidiu! 😄

Overall, I agree with the desire to not rush this. If we start with simple arrays in 6.9 with no built-in filtering (folks can always get the abilities and filter them themselves), I'm fine with that.

Regarding the introduction of the *_Collection concept, in my opinion, WordPress errs too much on the side of using "we haven't done that before" argument as a reason not to do things. Concepts like Collections are tried and true patterns across multiple systems. We're not creating a new concept entirely, we're porting one over. I do appreciate you raising the point, @justlevine, as it is a good one to be mindful of. I would love to see more tried-and-true practices and patterns brought tastefully into WordPress over time.

With regards to performance, @galatanovidiu, in this case I think it's negligible — absolutely nothing like performance from a database perspective. And even chaining things like with_x is working from a smaller. subset each time, so the iteration performance jumps each time. Frankly, this isn't too unlike how databases often filter things down.

In short, I'm in favor of closing this PR to explore a better API. I really like the draft (which I need to dig into more), and would like to explore that sort of direction further. 😄

justlevine · 2025-10-14T21:40:05Z

docs/8.querying-filtering-abilities.md

+// Paginate results
+$abilities = wp_get_abilities( array(
+    'limit'  => 10,
+    'offset' => 0,
+) );
+```


Is there a specific need for pagination?

I see that you're trying to mirror WP_Query et al (versus adding sorting/filtering as registry methods) but abilities are in a PHP array, not a database. Do we really need a shortcut for what's essentially an array_slice()?

Filtering abilities are the most crucial aspect from my perspective. Ordering and pagination are nice-to-haves, but I want to acknowledge that they fit well together in the proposed implementation, as they allow easy selection of a precise number of abilities that meet specific criteria, which might be useful when passing data to an LLM with limited context. @galatanovidiu might have a better overview of the real needs based on the work he has done for the MCP Adapter.

gziolo · 2025-10-15T10:28:27Z

One thing I want to note is that some filters are hard to express in this array notation. For example, a category or namespace let you provide an array of options where the existence of one of them means a match (OR strategy). In the case of meta where the structure is more complex, the approach used (AND strategy) makes more sense, but this comes at the cost of the developer having to be very careful when studying the docs to ensure they express their intent appropriately. However, for meta it isn't currently possible to request an OR condition in case at least one of several meta conditions is met.

Defines a new `@phpstan-type` called `AbilityQueryArgs` to represent the arguments for an abilities query. This centralizes the complex array shape definition, which was previously defined inline in the constructor's docblock. Using this shared type improves code readability and maintainability. The `wp_get_abilities` function documentation is also updated to reference this new type for better consistency.

Marks the `WP_Abilities_Query` class as `final` and `@internal` to clarify that it is not part of the public API. This change prevents the class from being extended or consumed directly, encouraging developers to use the stable `wp_get_abilities()` function instead. This helps ensure forward-compatibility and avoids potential breakage from future implementation changes.

Co-authored-by: Dovid Levine <[email protected]>

galatanovidiu added 4 commits October 14, 2025 11:21

feat(abilities-api): Introduce WP_Abilities_Query class

01cff2f

feat(abilities-api): Add filtering capabilities to wp_get_abilities

46d4711

test(abilities-api): Add unit tests for WP_Abilities_Query

3ebeb37

docs(abilities-api): Add documentation for querying and filtering abi…

45d3917

…lities

galatanovidiu requested review from JasonTheAdams, gziolo, justlevine and swissspidy October 14, 2025 08:37

Refactor WP_Abilities_Query for compatibility

f114dae

Public constants are converted to private static properties Additionally, validation methods are updated to use guard clauses, and some boolean logic is simplified.

gziolo assigned galatanovidiu Oct 14, 2025

gziolo added the [Type] Enhancement New feature or request label Oct 14, 2025

gziolo added this to WordPress Abilities API: planning Oct 14, 2025

gziolo moved this to Needs review in WordPress Abilities API: planning Oct 14, 2025

This was referenced Oct 14, 2025

Add category support to client package #114

Merged

Feature Proposal: Categories for Abilities API #101

Closed

JasonTheAdams requested changes Oct 14, 2025

View reviewed changes

galatanovidiu added 6 commits October 14, 2025 21:49

Remove redundant empty args check in wp_get_abilities()

c89f085

WP_Abilities_Query already returns all abilities when args is empty, making the backward compatibility check unnecessary.

Clarifies array type annotations in documentation

2ca7dae

Updates type hints to specify arrays of strings for 'category' and 'namespace' parameters.

Rename validation methods to sanitization methods

68fea1b

Updates method names and related docblocks to clarify that query argument processing focuses on sanitization rather than validation.

Clarifies abilities retrieval and filtering doc

de10fa7

Improves documentation to specify use of the query class for retrieving and filtering abilities.

Enforces non-negative offset and valid limit in pagination

74c0990

Refactor sanitize_pagination_args to use early exit pattern

844dddb

galatanovidiu requested a review from JasonTheAdams October 14, 2025 19:44

Merge branch 'trunk' into feature/filter-registered-abilities

937c778

justlevine reviewed Oct 14, 2025

View reviewed changes

galatanovidiu mentioned this pull request Oct 15, 2025

Add Filtering Capabilities for Registered Abilities using collections (POC) #119

Draft

galatanovidiu and others added 3 commits October 15, 2025 18:14

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

8a5c01f

Co-authored-by: Dovid Levine <[email protected]>

gziolo mentioned this pull request Oct 15, 2025

Proposal: Add a convienient way to filter the list of all registered abilities #38

Open

JasonTheAdams mentioned this pull request Oct 17, 2025

Abilities API: Implement server-side registry with REST API endpoints WordPress/wordpress-develop#9410

Closed

15 tasks

gziolo mentioned this pull request Oct 24, 2025

Add wp_query_abilities: flexible filtering for registered abilities #85

Open

Uh oh!

Add Filtering Capabilities for Registered Abilities #115

Are you sure you want to change the base?

Add Filtering Capabilities for Registered Abilities #115

Conversation

galatanovidiu commented Oct 14, 2025 • edited by gziolo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Documentation

Backward Compatibility

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

JasonTheAdams 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!

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!

Choose a reason for hiding this comment

Uh oh!

justlevine left a comment • 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 Oct 14, 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!

JasonTheAdams Oct 14, 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

galatanovidiu commented Oct 14, 2025 •

edited by gziolo

Loading

github-actions bot commented Oct 14, 2025 •

edited

Loading

codecov bot commented Oct 14, 2025 •

edited

Loading

justlevine left a comment •

edited

Loading

justlevine Oct 14, 2025 •

edited

Loading

JasonTheAdams Oct 14, 2025 •

edited

Loading

gziolo Oct 15, 2025 •

edited

Loading