Skip to content

Introduce an alias which represents a callable that may not be defined in the current scope #6

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
johnbillion merged 1 commit into from
Aug 24, 2026
Merged

Introduce an alias which represents a callable that may not be defined in the current scope #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions src/wp-includes/class-wp-hook.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,7 +201,7 @@ private function resort_active_iterations( $new_priority = false, $priority_exis
* a callback that may or may not exist.
* @param int $priority The exact priority used when adding the original filter callback.
* @return bool Whether the callback existed before it was removed.
* @phpstan-param callable|string|array{ 0: string|object, 1: string, ... } $callback
* @phpstan-param Maybe_Callable $callback

@westonruter westonruter Aug 21, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

One thing to note about this. PhpStorm doesn't understand what Maybe_Callable is:

Image

I seem to remember this being why I didn't go that route before.

Presumably other IDEs wouldn't either.

@westonruter westonruter Aug 21, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

OK, there is a 2-year-old Jetbrains issue requesting support for PHPStan type aliases: https://youtrack.jetbrains.com/projects/WI/issues/WI-79519/PHPStorm-doesnt-recognise-PHPStan-global-type-aliases

So presumably this will land eventually.

However, VS Code + Intelephense doesn't yet support this either: bmewburn/vscode-intelephense#3525

But VS Code + DEVSENSE PHP Tools does support this.

@westonruter westonruter Aug 21, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Something else to consider is whether the developer docs parser would need to be updated to support this.

In looking at the docs for \WP_Post::to_array(), I see that it doesn't do any parsing of:

@phpstan-return Data_Array

I also see the same in the docs for \WP_Connector_Registry::register(), that the @return is parsed but the @phpstan-return which includes tyhe type Connector is not mentioned.

So I think it's OK, if we only ever use these PHPStan type aliases in @phpstan- prefixed tags. However, I remember you mentioned the desire to be able to move away from having to do this. If so, then updating the developer docs parser would need to be added to the prerequisites.

@johnbillion johnbillion Aug 24, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

I'm still not sure what to do about @phpstan- prefixed tags. I'll draft a make/core post soon.

@westonruter westonruter Aug 24, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

See also WordPress#13233 which could lessen the need to add @phpstan- prefixed tags.

*/
public function remove_filter( $hook_name, $callback, $priority ) {
if ( null === $priority ) {
Expand Down Expand Up @@ -249,7 +249,7 @@ public function remove_filter( $hook_name, $callback, $priority ) {
* of that hook is returned, or false if the function is not attached.
* If `$callback` and `$priority` are both provided, a boolean is returned
* for whether the specific function is registered at that priority.
* @phpstan-param callable|string|array{ 0: string|object, 1: string, ... }|false $callback
* @phpstan-param Maybe_Callable|false $callback
*/
public function has_filter( $hook_name = '', $callback = false, $priority = false ) {
if ( false === $callback ) {
Expand Down
4 changes: 4 additions & 0 deletions src/wp-includes/plugin.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,7 @@ function apply_filters_ref_array( $hook_name, $args ) {
* of that hook is returned, or false if the function is not attached.
* If `$callback` and `$priority` are both provided, a boolean is returned
* for whether the specific function is registered at that priority.
* @phpstan-param Maybe_Callable|false $callback
*/
function has_filter( $hook_name, $callback = false, $priority = false ) {
global $wp_filter;
Expand Down Expand Up @@ -316,6 +317,7 @@ function has_filter( $hook_name, $callback = false, $priority = false ) {
* @param int $priority Optional. The exact priority used when adding the original
* filter callback. Default 10.
* @return bool Whether the function existed before it was removed.
* @phpstan-param Maybe_Callable $callback
*/
function remove_filter( $hook_name, $callback, $priority = 10 ) {
global $wp_filter;
Expand Down Expand Up @@ -597,6 +599,7 @@ function do_action_ref_array( $hook_name, $args ) {
* of that hook is returned, or false if the function is not attached.
* If `$callback` and `$priority` are both provided, a boolean is returned
* for whether the specific function is registered at that priority.
* @phpstan-param Maybe_Callable|false $callback
*/
function has_action( $hook_name, $callback = false, $priority = false ) {
return has_filter( $hook_name, $callback, $priority );
Expand All @@ -621,6 +624,7 @@ function has_action( $hook_name, $callback = false, $priority = false ) {
* @param int $priority Optional. The exact priority used when adding the original
* action callback. Default 10.
* @return bool Whether the function is removed.
* @phpstan-param Maybe_Callable $callback
*/
function remove_action( $hook_name, $callback, $priority = 10 ) {
return remove_filter( $hook_name, $callback, $priority );
Expand Down
8 changes: 8 additions & 0 deletions tests/phpstan/base.neon
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,3 +210,11 @@ parameters:
- ../../src/wp-includes/pomo
- ../../src/wp-includes/rss.php
- ../../src/wp-includes/sodium_compat
typeAliases:
# A callable that may not be defined in the current scope.
Maybe_Callable: '''
callable|string|array{
0: string|object,
1: string,
Comment thread
westonruter marked this conversation as resolved.
}
'''