Skip to content

Hooks/Docs: wp_die_*_handler filters (×6) — @param callable but string literal is passed as default #23

Closed as not planned

Description

@apermo

Problem

Six wp_die_*_handler filters in wp-includes/functions.php document their parameter as @param callable $callback but pass a string literal as the default value. In PHP, a string is a valid callable (it's a function name), but PHPStan's strict type checking does not consider string to be identical to callable, causing a reported type mismatch.

Affected filters

All six are in wp-includes/functions.php:

wp_die_ajax_handler (line 3789):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3782-L3789

wp_die_json_handler (line 3798):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3791-L3798

wp_die_jsonp_handler (line 3807):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3800-L3807

wp_die_xmlrpc_handler (line 3816):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3809-L3816

wp_die_xml_handler (line 3829):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3822-L3829

wp_die_handler (line 3838):
https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/functions.php#L3831-L3838

All follow the same pattern:

/**
 * @param callable $callback Callback function name.
 */
$callback = apply_filters( 'wp_die_ajax_handler', '_ajax_wp_die_handler' );

Root cause

PHP allows a string function name as a callable, but PHPStan treats callable and string as distinct types. The default value '_ajax_wp_die_handler' is inferred as string, which is narrower than callable.

Fix

Update all six @param tags to include string in the type union, reflecting that the default (and typical) value is a string function name:

- * @param callable $callback Callback function name.
+ * @param callable|string $callback Callback function name.

Alternatively, use @param callable-string if the intent is to restrict to named functions only (PHPStan understands callable-string as a callable that is specifically a string).

Activity

  1. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    False positive — the @param callable type is correct. The default value is a string function name, but the filter can legitimately return any callable (closure, array, etc.). The mismatch is a limitation of the custom PHPStan rule comparing the documented type against the inferred type of the default value.

  2. added
    wontfixAcknowledged but not worth the review effort
    on Mar 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    wontfixAcknowledged but not worth the review effort

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions