Make WordPress Core

Opened 12 days ago

Closed 8 days ago

#64700 closed defect (bug) (fixed)

Code Modernization: Replace void in PHPDoc union return types with null in general-template.php

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

Description (last modified by westonruter)

Following up on #64694 which fixed paginate_links(), this ticket addresses 10 instances in general-template.php where @return annotations incorrectly use void as part of a union type (e.g., @return string|void).

The |void pattern in this file was introduced in two waves:

  • WordPress 4.3 (8 functions) via [32598] — "Cleanup doc blocks in general-template.php"
  • WordPress 6.0 (2 functions) via [53300] — "Docs: Various docblock corrections"

Why this matters

In PHP's type system, void means "the function does not return a value" and cannot be part of a union type (this is a compile error in PHP 8.0+). When a function uses bare return; or falls off the end without returning, the actual runtime value is null. Therefore @return Type|void should be @return Type|null.

This affects:

  • Static analysis tools (PHPStan, Psalm)
  • IDE autocompletion and type inference
  • Developer expectations about return values

Backward Compatibility

This is a safe, non-breaking change. As demonstrated by @westonruter in the #64694 PR review, return; and return null; are identical at runtime across every PHP version from 4.3.0 through 8.5.3: https://3v4l.org/3KQC8

Proposed Changes

For each instance:

  1. Update the @return annotation to replace void with null
  2. Change bare return; statements to return null;
  3. Update description text to say "null" instead of "void" / "nothing"

Affected Functions

Function Line Current Recommendation Since
wp_title() 1341 string|void string|null 6.0
single_post_title() 1492 string|void string|null 4.3
post_type_archive_title() 1527 string|false|void string|null (also remove false) 4.3
single_cat_title() 1569 string|void string|null 4.3
single_tag_title() 1586 string|void string|null 4.3
single_term_title() 1603 string|void string|null 4.3
single_month_title() 1668 string|false|void string|false|null 6.0
the_date() 2684 string|void string|null 4.3
the_modified_date() 2759 string|void string|null 4.3
get_the_generator() 5169 string|void string|null 4.3

See #64694 for prior art.

Change History (7)

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


12 days ago
#1

  • Keywords has-patch added

Update 10 functions in general-template.php to use null instead of void in @return union types, and change bare return; statements to return null;.

In PHP's type system, void cannot be part of a union type. A bare return; actually returns null at runtime, so @return Type|null is the correct annotation.

Trac ticket: https://core.trac.wordpress.org/ticket/64700

## Use of AI Tools

Used AI for research, documentation and for the replacements. Everything was reviewed by myself and @xateman before opening this PR.

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


12 days ago
#2

Trac ticket:

## Use of AI Tools

@apermo commented on PR #11010:


12 days ago
#3

Duplicate of #11004 or #11005

#4 @apermo
12 days ago

Props: @xate

Co-Authored and Reviewed

#5 @westonruter
10 days ago

  • Milestone changed from Awaiting Review to 7.0
  • Owner set to westonruter
  • Status changed from new to reviewing

#6 @westonruter
8 days ago

  • Description modified (diff)

#7 @westonruter
8 days ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 61768:

Code Quality: Replace void with null in union return types in general-template.php.

Developed in https://github.com/WordPress/wordpress-develop/pull/11005

Follow-up to r61767, r61766, r61719, r61716, r53300, r32598.

Props apermo, xate, mukesh27.
See #64238.
Fixes #64700.

Note: See TracTickets for help on using tickets.