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: |
|
Owned by: |
|
|---|---|---|---|
| Milestone: | 7.0 | Priority: | normal |
| Severity: | normal | Version: | 4.3 |
| Component: | General | Keywords: | has-patch |
| Focuses: | Cc: |
Description (last modified by )
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:
- Update the
@returnannotation to replacevoidwithnull - Change bare
return;statements toreturn null; - 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
This ticket was mentioned in PR #11010 on WordPress/wordpress-develop by @pratiknawkar94.
12 days ago
#2
Trac ticket:
## Use of AI Tools
Update 10 functions in
general-template.phpto usenullinstead ofvoidin@returnunion types, and change barereturn;statements toreturn null;.In PHP's type system,
voidcannot be part of a union type. A barereturn;actually returnsnullat runtime, so@return Type|nullis 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.