Context Navigation

← Previous Ticket
Next Ticket →

#64694 closed defect (bug) (fixed)

paginate_links(): @return uses void instead of null in union type

Reported by:	apermo	Owned by:	westonruter
Milestone:	7.0	Priority:	normal
Severity:	normal	Version:	4.3
Component:	General	Keywords:	has-patch
Focuses:		Cc:

Description

The @return tag on paginate_links() in wp-includes/general-template.php reads:

@return string|string[]|void

void is not valid in a union return type. It means "the function never returns a value," which contradicts the string|string[] part. The function uses a bare return; when $total < 2 (line ~4706), which at runtime evaluates to null.

The correct annotation is:

@return string|string[]|null

This causes real-world issues: static analysis tools (PHPStan, Psalm) generate stubs from the PHPDoc and omit null from the return type, leading callers to believe the return value is always string|string[]. Passing the result to functions like wp_kses_post() then triggers a PHP 8.1+ deprecation:

Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated

Change History (5)

This ticket was mentioned in PR #10999 on WordPress/wordpress-develop by @apermo.

13 days ago #1

Keywords has-patch added

Update paginate_links() to explicitly return null instead of void when the total number of pages is less than 2, and update the @return docblock to reflect this change.

Trac ticket: https://core.trac.wordpress.org/ticket/64694#ticket

## Use of AI Tools

AI used for analysis and commit message.
Fix done manually.

#2 @apermo
13 days ago

Note: It might be even better to change the behavior to return an empty string, instead of just returning null, but that would be a potentially breaking change, this is the defensive version, just updating the current behavior, so that PHPStan is able to correctly analyze the behavior.