[wp-trac] [WordPress Trac] #64694: paginate_links(): @return uses void instead of null in union type

[WordPress Trac]

#64694: paginate_links(): @return uses void instead of null in union type
--------------------------+-----------------------------
 Reporter:  apermo        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:
 Severity:  normal        |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 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

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64694>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform