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

[WordPress Trac]

#64701: `Code Modernization: Replace void in PHPDoc union return types with null in
Customize`
--------------------------+-----------------------------
 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 8 instances across 4 Customize files where `@return` annotations
 incorrectly use `void` as part of a union type.

 The `|void` pattern in these files was introduced in WordPress 4.3 via
 [32568] — "Use `void` instead of `null` where appropriate when pipe-
 delimiting `@return` types". The `get_current_image_src()` annotation
 originated in the same commit but was carried to its current file location
 in WP 4.4 via a file move.

 === 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`
 2. Change bare `return;` statements to `return null;`
 3. Update description text to say "null" instead of "void" / "nothing"

 === Affected Functions ===

 ||= File =||= Function =||= Line =||= Current =||= Recommendation =||
 || `class-wp-customize-manager.php` || `get_setting()` || 3866 ||
 `WP_Customize_Setting|void` || `WP_Customize_Setting|null` ||
 || `class-wp-customize-manager.php` || `get_panel()` || 3918 ||
 `WP_Customize_Panel|void` || `WP_Customize_Panel|null` ||
 || `class-wp-customize-manager.php` || `get_section()` || 4014 ||
 `WP_Customize_Section|void` || `WP_Customize_Section|null` ||
 || `class-wp-customize-manager.php` || `get_control()` || 4093 ||
 `WP_Customize_Control|void` || `WP_Customize_Control|null` ||
 || `class-wp-customize-setting.php` || `multidimensional()` || 859 ||
 `array|void` || `array|null` ||
 || `class-wp-customize-header-image-control.php` ||
 `get_current_image_src()` || 196 || `string|void` || `string|null` ||
 || `class-wp-customize-widgets.php` || `get_setting_type()` || 179 ||
 `string|void` || `string|null` ||
 || `class-wp-customize-widgets.php` || `sanitize_widget_instance()` ||
 1457 || `array|void` || `array|null` ||

 See [#64694] for prior art.

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