Make WordPress Core

Opened 12 days ago

Closed 8 days ago

#64701 closed defect (bug) (fixed)

Code Modernization: Replace void in PHPDoc union return types with null in Customize

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 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 #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.

Change History (7)

#1 @huzaifaalmesbah
12 days ago

  • Summary changed from `Code Modernization: Replace void in PHPDoc union return types with null in Customize` to Code Modernization: Replace void in PHPDoc union return types with null in Customize

This ticket was mentioned in PR #11006 on WordPress/wordpress-develop by @apermo.


12 days ago
#2

  • Keywords has-patch added

Co-Authored-By: xateman

Trac ticket: https://core.trac.wordpress.org/ticket/64701

## Use of AI Tools

Used AI for research, documentation and for the replacements. Everything was reviewed by myself and @xateman before opening this PR.

This ticket was mentioned in PR #11011 on WordPress/wordpress-develop by @pratiknawkar94.


12 days ago
#3

Trac ticket:

## Use of AI Tools

@apermo commented on PR #11011:


12 days ago
#4

Duplicate

#5 @apermo
12 days ago

Props: @xate

Co-Authored and Reviewed

#6 @westonruter
10 days ago

  • Milestone changed from Awaiting Review to 7.0
  • Owner set to westonruter
  • Status changed from new to reviewing

#7 @westonruter
8 days ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 61767:

Code Quality: Replace void with null in union return types in Customizer classes.

Developed in https://github.com/WordPress/wordpress-develop/pull/11006

Follow-up to r61766, r61719, r61716.

Props apermo, xate, mukesh27.
See #64238.
Fixes #64701.

Note: See TracTickets for help on using tickets.