Opened 3 weeks ago
Last modified 2 weeks ago
#64702 reviewing defect (bug)
Code Modernization: Replace void in PHPDoc union return types with null in Administration
| Reported by: |
|
Owned by: |
|
|---|---|---|---|
| Milestone: | 7.0 | Priority: | normal |
| Severity: | normal | Version: | 4.3 |
| Component: | General | Keywords: | has-patch |
| Focuses: | Cc: |
Description
Following up on #64694 which fixed paginate_links(), this ticket addresses 13 instances across Administration files (class-wp-admin-bar.php and wp-admin/includes/) where @return annotations incorrectly use void as part of a union type.
The |void pattern in these files was introduced across multiple versions from WordPress 4.3 through 6.8, with the most recent being column_status() in class-wp-privacy-requests-table.php added in WP 6.8 via [59336].
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(or remove|voidwhere the function always returns a typed value) - Change bare
return;statements toreturn null; - Update description text to say "null" instead of "void" / "nothing"
Affected Functions — class-wp-admin-bar.php (5)
| Function | Line | Current | Recommendation | Since |
|---|---|---|---|---|
get_node() | 196 | object|void | object|null | 5.3 |
_get_node() | 209 | object|void | object|null | 4.3 |
get_nodes() | 228 | array|void | array|null | 4.3 |
_get_nodes() | 245 | array|void | array|null | 4.3 |
_bind() | 310 | object|void | object|null | 4.3 |
Affected Functions — wp-admin/includes/ (8)
| File | Function | Line | Current | Recommendation | Since |
|---|---|---|---|---|---|
class-wp-importer.php | set_blog() | 139 | int|void | int (void incorrect) | 4.3 |
class-wp-importer.php | set_user() | 180 | int|void | int (void incorrect) | 4.3 |
class-wp-site-health.php | perform_test() | 170 | mixed|void | mixed (void incorrect) | 5.4 |
post.php | write_post() | 985 | int|void | int (void incorrect) | 5.7 |
media.php | media_upload_form_handler() | 739 | null|array|void | null|array (void redundant) | 5.9 |
plugin.php | uninstall_plugin() | 1299 | true|void | true|null | 5.7 |
file.php | validate_file_to_edit() | 737 | string|void | string (void incorrect) | 5.0 |
dashboard.php | wp_dashboard_quota() | 1651 | true|void | true|null | 5.7 |
class-wp-privacy-requests-table.php | column_status() | 438 | string|void | string|null | 6.8 |
See #64694 for prior art.
Change History (3)
#1
@
3 weeks ago
- Summary changed from `Code Modernization: Replace void in PHPDoc union return types with null in Administration` to Code Modernization: Replace void in PHPDoc union return types with null in Administration
This ticket was mentioned in PR #11008 on WordPress/wordpress-develop by @apermo.
3 weeks ago
#2
- Keywords has-patch added
Co-Authored-By: xateman
Trac ticket: https://core.trac.wordpress.org/ticket/64702
## Use of AI Tools
Used AI for research, documentation and for the replacements. Everything was reviewed by myself and @xateman before opening this PR.