close

Make WordPress Core

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: 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

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:

  1. Update the @return annotation to replace void with null (or remove |void where the function always returns a typed value)
  2. Change bare return; statements to return null;
  3. 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 Image @huzaifaalmesbah
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

Image

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.

#3 Image @westonruter
2 weeks ago

  • Milestone changed from Awaiting Review to 7.0
  • Owner set to westonruter
  • Status changed from new to reviewing
Note: See TracTickets for help on using tickets.