Skip to content

Docs: Replace void with null in union return types in Administration #11008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
apermo wants to merge 8 commits into
base: trunk
Choose a base branch
from
Open

Docs: Replace void with null in union return types in Administration #11008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
544414a
Docs: Replace void with null in union return types in Administration
apermo Feb 23, 2026
b123868
fix: resolve PHPStan warnings in file.php and post.php
apermo Feb 23, 2026
2f1d8d5
Docs: Address review feedback for return types
apermo Feb 25, 2026
7d677fa
Remove return for media_send_to_editor() calls
apermo Feb 25, 2026
12a2bc5
Docs: Use array shape for perform_test() return type
apermo Feb 25, 2026
0a3e8f1
fix: Add default case to validate_file_to_edit() switch
apermo Feb 25, 2026
4013816
docs: Add @return never to media_send_to_editor()
apermo Feb 25, 2026
8f8ec70
fix: Use return null as default in validate_file_to_edit()
apermo Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions src/wp-admin/includes/class-wp-importer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,14 @@ public function get_imported_comments( $blog_id ) {
}

/**
* @param int $blog_id
* @return int|void
* Sets the blog to import to.
*
* Accepts a numeric blog ID or a URL string. When given a URL,
* the blog is looked up by domain and path. On multisite, switches
* to the resolved blog. Exits with an error if the blog cannot be found.
*
* @param int|string $blog_id Blog ID or URL.
* @return int|never Blog ID on success. Exits on failure.
*/
public function set_blog( $blog_id ) {
if ( is_numeric( $blog_id ) ) {
Expand Down Expand Up @@ -177,7 +183,7 @@ public function set_blog( $blog_id ) {

/**
* @param int $user_id
* @return int|void
* @return int|never
*/
public function set_user( $user_id ) {
if ( is_numeric( $user_id ) ) {
Expand Down
2 changes: 1 addition & 1 deletion src/wp-admin/includes/class-wp-privacy-requests-table.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,7 +435,7 @@ public function column_cb( $item ) {
* @since 4.9.6
*
* @param WP_User_Request $item Item being shown.
* @return string|void Status column markup. Returns a string if no status is found,
* @return string|null Status column markup. Returns a string if no status is found,
* otherwise it displays the markup.
*/
public function column_status( $item ) {
Expand Down
12 changes: 11 additions & 1 deletion src/wp-admin/includes/class-wp-site-health.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,17 @@ public function enqueue_scripts() {
* @since 5.4.0
*
* @param callable $callback
* @return mixed|void
* @return array{
* label: string,
* status: 'good'|'recommended'|'critical',
* badge: array{
* label: string,
* color: string,
* },
* description: string,
* actions: string,
* test: string,
* }
*/
private function perform_test( $callback ) {
/**
Expand Down
2 changes: 1 addition & 1 deletion src/wp-admin/includes/dashboard.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1648,7 +1648,7 @@ function wp_dashboard_primary_output( $widget_id, $feeds ) {
*
* @since 3.0.0
*
* @return true|void True if not multisite, user can't upload files, or the space check option is disabled.
* @return true|null True if not multisite, user can't upload files, or the space check option is disabled.
*/
function wp_dashboard_quota() {
if ( ! is_multisite() || ! current_user_can( 'upload_files' )
Expand Down
3 changes: 2 additions & 1 deletion src/wp-admin/includes/file.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -734,7 +734,7 @@ function wp_tempnam( $filename = '', $dir = '' ) {
* @param string $file File the user is attempting to edit.
* @param string[] $allowed_files Optional. Array of allowed files to edit.
* `$file` must match an entry exactly.
* @return string|void Returns the file name on success, dies on failure.
* @return string|null|never Returns the file name on success, null in case of absolute Windows drive paths, and dies on failure.
*/
function validate_file_to_edit( $file, $allowed_files = array() ) {
$code = validate_file( $file, $allowed_files );
Expand All @@ -753,6 +753,7 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
case 3:
wp_die( __( 'Sorry, that file cannot be edited.' ) );
}
return null;
}

/**
Expand Down
7 changes: 4 additions & 3 deletions src/wp-admin/includes/media.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,7 @@ function _cleanup_image_add_caption( $matches ) {
* @since 2.5.0
*
* @param string $html
* @return never
*/
function media_send_to_editor( $html ) {
?>
Expand Down Expand Up @@ -736,7 +737,7 @@ function get_upload_iframe_src( $type = null, $post_id = null, $tab = null ) {
*
* @since 2.5.0
*
* @return null|array|void Array of error messages keyed by attachment ID, null or void on success.
* @return null|array|never Array of error messages keyed by attachment ID, null on success, or exit.
*/
function media_upload_form_handler() {
check_admin_referer( 'media-form' );
Expand Down Expand Up @@ -857,7 +858,7 @@ function media_upload_form_handler() {
*/
$html = apply_filters( 'media_send_to_editor', $html, $send_id, $attachment );

return media_send_to_editor( $html );
media_send_to_editor( $html );
}

return $errors;
Expand Down Expand Up @@ -959,7 +960,7 @@ function wp_media_upload_handler() {
$html = apply_filters( 'image_send_to_editor_url', $html, sanitize_url( $src ), $alt, $align );
}

return media_send_to_editor( $html );
media_send_to_editor( $html );
}

if ( isset( $_POST['save'] ) ) {
Expand Down
4 changes: 2 additions & 2 deletions src/wp-admin/includes/plugin.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1296,8 +1296,8 @@ function is_uninstallable_plugin( $plugin ) {
* @since 2.7.0
*
* @param string $plugin Path to the plugin file relative to the plugins directory.
* @return true|void True if a plugin's uninstall.php file has been found and included.
* Void otherwise.
* @return true|null True if a plugin's uninstall.php file has been found and included.
* Null otherwise.
*/
function uninstall_plugin( $plugin ) {
$file = plugin_basename( $plugin );
Expand Down
6 changes: 3 additions & 3 deletions src/wp-admin/includes/post.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -982,15 +982,15 @@ function wp_write_post() {
*
* @since 2.0.0
*
* @return int|void Post ID on success, void on failure.
* @return int|never Post ID on success. Dies on failure.
Copy link

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updated docblock for write_post() says it "dies on failure", but wp_write_post() can return 0 (see the empty( $post_id ) branch in the same file) and write_post() will pass that 0 back to callers without calling wp_die(). Please adjust the description/return type to document the possible 0 return (or change the implementation to treat 0 as a failure if that’s the intent).

Suggested change
* @return int|never Post ID on success. Dies on failure.
* @return int|0|never Post ID on success, 0 on failure that is not represented as WP_Error. Dies on WP_Error failures.

Copilot uses AI. Check for mistakes.
Copy link
Member

@westonruter westonruter Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Humm. 0 is an int

Copy link
Author

@apermo apermo Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But a special int.

Joke aside, I made Claude review all core

That pattern (int|0) doesn't make sense as a PHPDoc type anyway — 0 isn't a type, it's a value

But none of them use 0 as a literal type in the union (like int|0|WP_Error). They all use int|WP_Error as the type and explain the 0 value in the description text.

The int|0|never pattern from your question doesn't exist anywhere in core. Literal value types like 0 in @return unions aren't a convention WordPress follows — the only instance is @return -1|0|1 in the vendored SimplePie library, which is a
spaceship-operator-style comparison return.

So I'd say this falls under AI hallucination.

Copy link
Member

@westonruter westonruter Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, using a literal for a type is okay, and PHPStan supports that. But it doesn't make sense when int is a superset of 0.

Copy link
Author

@apermo apermo Feb 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And according to the research through core it was never done besides the vendored library. And -1|0|1 is cherry picking 3 ints, vs int|0 is saying all integers and a single one from all integers. So thats a huge difference.

*/
function write_post() {
$result = wp_write_post();
if ( is_wp_error( $result ) ) {
wp_die( $result->get_error_message() );
} else {
return $result;
}

return $result;
}

//
Expand Down
19 changes: 10 additions & 9 deletions src/wp-includes/class-wp-admin-bar.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,24 +193,25 @@ final protected function _set_node( $args ) {
* @since 3.3.0
*
* @param string $id
* @return object|void Node.
* @return object|null Node.
*/
final public function get_node( $id ) {
$node = $this->_get_node( $id );
if ( $node ) {
return clone $node;
}
return null;
}

/**
* @since 3.3.0
*
* @param string $id
* @return object|void
* @return object|null
*/
final protected function _get_node( $id ) {
if ( $this->bound ) {
return;
return null;
}

if ( empty( $id ) ) {
Expand All @@ -225,12 +226,12 @@ final protected function _get_node( $id ) {
/**
* @since 3.3.0
*
* @return array|void
* @return array|null
*/
final public function get_nodes() {
$nodes = $this->_get_nodes();
if ( ! $nodes ) {
return;
return null;
}

foreach ( $nodes as &$node ) {
Expand All @@ -242,11 +243,11 @@ final public function get_nodes() {
/**
* @since 3.3.0
*
* @return array|void
* @return array|null
*/
final protected function _get_nodes() {
if ( $this->bound ) {
return;
return null;
}

return $this->nodes;
Expand Down Expand Up @@ -307,11 +308,11 @@ public function render() {
/**
* @since 3.3.0
*
* @return object|void
* @return object|null
*/
final protected function _bind() {
if ( $this->bound ) {
return;
return null;
}

/*
Expand Down
Loading