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: |
|
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 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:
- Update the
@returnannotation to replacevoidwithnull - Change bare
return;statements toreturn null; - 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
@
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
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
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.