Skip to content

code quality: add PHPStan array shape for ability $properties #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 19, 2025
Merged

code quality: add PHPStan array shape for ability $properties #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bf036b3
dev: add PHPStan array shape for ability `$properties`
justlevine Aug 16, 2025
a4ff8ae
Merge branch 'trunk' into dev/properties-array-shap
gziolo Aug 18, 2025
4679be9
Merge branch 'trunk' into dev/properties-array-shap
gziolo Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions includes/abilities-api.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,17 @@
* include `label`, `description`, `input_schema`, `output_schema`,
* `execute_callback`, `permission_callback`, and `meta`.
* @return ?\WP_Ability An instance of registered ability on success, null on failure.
*
* @phpstan-param array{
* label?: string,
* description?: string,
* input_schema?: array<string,mixed>,
* output_schema?: array<string,mixed>,
* execute_callback?: callable( array<string,mixed> $input): (mixed|\WP_Error),
* permission_callback?: callable( ?array<string,mixed> $input ): bool,
* meta?: array<string,mixed>,
* ...<string, mixed>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything else gets ignored, do we need to list it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's exaclty why it's here - this is the long-overdue syntax for partially sealed arrays.

Otherwise if users don't clean up their arrays (or more "justifiable" real world scenario: if extensions hook in their own custom args) they'll get errors about unsupported array values, when it doesn't matter because we only keep the ones we need.

Copy link
Member

@gziolo gziolo Aug 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t think it adds any value at the moment because it’s impossible to successfully pass more settings. It’ll rather change in the future when we add WP hooks.

* } $properties
*/
function wp_register_ability( $name, array $properties = array() ): ?WP_Ability {
if ( ! did_action( 'abilities_api_init' ) ) {
Expand Down
11 changes: 11 additions & 0 deletions includes/abilities-api/class-wp-abilities-registry.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,17 @@ final class WP_Abilities_Registry {
* include `label`, `description`, `input_schema`, `output_schema`,
* `execute_callback`, `permission_callback`, and `meta`.
* @return ?\WP_Ability The registered ability instance on success, null on failure.
*
* @phpstan-param array{
* label?: string,
* description?: string,
* input_schema?: array<string,mixed>,
* output_schema?: array<string,mixed>,
* execute_callback?: callable( array<string,mixed> $input): (mixed|\WP_Error),
* permission_callback?: ?callable( ?array<string,mixed> $input ): bool,
* meta?: array<string,mixed>,
* ...<string, mixed>
* } $properties
*/
public function register( $name, array $properties = array() ): ?WP_Ability {
$ability = null;
Expand Down
10 changes: 10 additions & 0 deletions includes/abilities-api/class-wp-ability.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,16 @@ class WP_Ability {
* @param array<string,mixed> $properties An associative array of properties for the ability. This should
* include `label`, `description`, `input_schema`, `output_schema`,
* `execute_callback`, `permission_callback`, and `meta`.
*
* @phpstan-param array{
* label: string,
* description: string,
* input_schema?: array<string,mixed>,
* output_schema?: array<string,mixed>,
* execute_callback: callable( array<string,mixed> $input): (mixed|\WP_Error),
* permission_callback?: ?callable( ?array<string,mixed> $input ): bool,
* meta?: array<string,mixed>,
* } $properties
*/
public function __construct( string $name, array $properties ) {
$this->name = $name;
Expand Down