[wp-trac] [WordPress Trac] #64702: `Code Modernization: Replace void in PHPDoc union return types with null in Administration`

[WordPress Trac]

#64702: `Code Modernization: Replace void in PHPDoc union return types with null in
Administration`
--------------------------+-----------------------------
 Reporter:  apermo        |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:  4.3
 Severity:  normal        |   Keywords:
  Focuses:                |
--------------------------+-----------------------------
 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 [https://github.com/WordPress/wordpress-
 develop/pull/10999#pullrequestreview-3839142928 #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.

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