Code Quality: Replace void with proper return types in union PHPDoc annotations.

In PHP's type system, `void` means a function does not return a value and cannot be part of a union type. Many functions in core were documented as returning e.g. `string|void` while actually returning `null` implicitly via bare `return;` statements. This replaces `void` with `null` in union return types, adds explicit `return null;` statements, and updates `@return` annotations across 22 files in `wp-includes`.

Additionally:
* Adds `@return never` for `WP_Recovery_Mode::redirect_protected()`.
* Fixes `WP_Theme_JSON::set_spacing_sizes()` to use `@return void` instead of `@return null|void`.
* Removes `void` from return types where the function always returns a value or dies: `remove_theme_support()`, `WP_Recovery_Mode::handle_error()`.
* Fixes `wp_die()` return type from `never|void` to `void` with clarified description.
* Initializes `$primary` variable in `get_active_blog_for_user()` to prevent a possible undefined variable notice.

Developed in WordPress#11012

Follow-up to r62177, r61766, r61719.

Props apermo, xateman, westonruter, parthvataliya, nimeshatxecurify.
See #64704.


git-svn-id: https://develop.svn.wordpress.org/trunk@62178 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-includes/canonical.php

@@ -37,13 +37,13 @@
  * @param string $requested_url Optional. The URL that was requested, used to
  *                              figure if redirect is needed.
  * @param bool   $do_redirect   Optional. Redirect to the new URL.
- * @return string|void The string of the URL, if redirect needed.
+ * @return string|null The string of the URL, if redirect needed. Never returns if a redirect occurs, depending on $do_redirect.
  */
 function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	global $wp_rewrite, $is_IIS, $wp_query, $wpdb, $wp;
 
 	if ( isset( $_SERVER['REQUEST_METHOD'] ) && ! in_array( strtoupper( $_SERVER['REQUEST_METHOD'] ), array( 'GET', 'HEAD' ), true ) ) {
-		return;
+		return null;
 	}
 
 	/*
@@ -62,7 +62,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	if ( is_admin() || is_search() || is_preview() || is_trackback() || is_favicon()
 		|| ( $is_IIS && ! iis7_supports_permalinks() )
 	) {
-		return;
+		return null;
 	}
 
 	if ( ! $requested_url && isset( $_SERVER['HTTP_HOST'] ) ) {
@@ -74,7 +74,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 
 	$original = parse_url( $requested_url );
 	if ( false === $original ) {
-		return;
+		return null;
 	}
 
 	// Notice fixing.
@@ -771,7 +771,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	}
 
 	if ( ! $redirect_url || $redirect_url === $requested_url ) {
-		return;
+		return null;
 	}
 
 	// Hex-encoded octets are case-insensitive.
@@ -830,7 +830,7 @@ function lowercase_octets( $matches ) {
 
 	// Yes, again -- in case the filter aborted the request.
 	if ( ! $redirect_url || strip_fragment_from_url( $redirect_url ) === strip_fragment_from_url( $requested_url ) ) {
-		return;
+		return null;
 	}
 
 	if ( $do_redirect ) {
@@ -841,7 +841,7 @@ function lowercase_octets( $matches ) {
 		} else {
 			// Debug.
 			// die("1: $redirect_url<br />2: " . redirect_canonical( $redirect_url, false ) );
-			return;
+			return null;
 		}
 	} else {
 		return $redirect_url;

src/wp-includes/capabilities.php

@@ -1130,11 +1130,11 @@ function get_role( $role ) {
  * @param string                               $display_name Display name for role.
  * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
  *                                                           Default empty array.
- * @return WP_Role|void WP_Role object, if the role is added.
+ * @return WP_Role|null WP_Role object, if the role is added.
  */
 function add_role( $role, $display_name, $capabilities = array() ) {
 	if ( empty( $role ) ) {
-		return;
+		return null;
 	}
 
 	return wp_roles()->add_role( $role, $display_name, $capabilities );

src/wp-includes/class-wp-admin-bar.php

@@ -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 ) ) {
@@ -220,17 +221,18 @@ final protected function _get_node( $id ) {
 		if ( isset( $this->nodes[ $id ] ) ) {
 			return $this->nodes[ $id ];
 		}
+		return null;
 	}
 
 	/**
 	 * @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 ) {
@@ -242,11 +244,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;
@@ -307,11 +309,11 @@ public function render() {
 	/**
 	 * @since 3.3.0
 	 *
-	 * @return object|void
+	 * @return object|null
 	 */
 	final protected function _bind() {
 		if ( $this->bound ) {
-			return;
+			return null;
 		}
 
 		/*

src/wp-includes/class-wp-block-type.php

@@ -358,8 +358,8 @@ public function __construct( $block_type, $args = array() ) {
 	 *
 	 * @param string $name Deprecated property name.
 	 *
-	 * @return string|string[]|null|void The value read from the new property if the first item in the array provided,
-	 *                                   null when value not found, or void when unknown property name provided.
+	 * @return string|string[]|null The value read from the new property if the first item in the array provided,
+	 *                              null when value not found or when unknown property name provided.
 	 */
 	public function __get( $name ) {
 		if ( 'variations' === $name ) {
@@ -371,7 +371,7 @@ public function __get( $name ) {
 		}
 
 		if ( ! in_array( $name, $this->deprecated_properties, true ) ) {
-			return;
+			return null;
 		}
 
 		$new_name = $name . '_handles';

src/wp-includes/class-wp-plugin-dependencies.php

@@ -643,13 +643,13 @@ protected static function get_dependency_filepaths() {
 	 *
 	 * @global string $pagenow The filename of the current screen.
 	 *
-	 * @return array|void An array of dependency API data, or void on early exit.
+	 * @return array|null An array of dependency API data, or null on early exit.
 	 */
 	protected static function get_dependency_api_data() {
 		global $pagenow;
 
 		if ( ! is_admin() || ( 'plugins.php' !== $pagenow && 'plugin-install.php' !== $pagenow ) ) {
-			return;
+			return null;
 		}
 
 		if ( is_array( self::$dependency_api_data ) ) {

src/wp-includes/class-wp-recovery-mode.php

@@ -161,9 +161,9 @@ public function is_initialized() {
 	 * @since 5.2.0
 	 *
 	 * @param array $error Error details from `error_get_last()`.
-	 * @return true|WP_Error|void True if the error was handled and headers have already been sent.
-	 *                            Or the request will exit to try and catch multiple errors at once.
-	 *                            WP_Error if an error occurred preventing it from being handled.
+	 * @return true|WP_Error True if the error was handled and headers have already been sent.
+	 *                       Or the request will exit to try and catch multiple errors at once.
+	 *                       WP_Error if an error occurred preventing it from being handled.
 	 */
 	public function handle_error( array $error ) {
 
@@ -455,6 +455,8 @@ protected function store_error( $error ) {
 	 * next request again. Otherwise it will create a redirect loop.
 	 *
 	 * @since 5.2.0
+	 *
+	 * @return never
 	 */
 	protected function redirect_protected() {
 		// Pluggable is usually loaded after plugins, so we manually include it here for redirection functionality.

src/wp-includes/class-wp-roles.php

@@ -171,11 +171,11 @@ public function reinit() {
 	 * @param string                               $display_name Role display name.
 	 * @param array<string,bool>|array<int,string> $capabilities Capabilities to be added to the role.
 	 *                                                           Default empty array.
-	 * @return WP_Role|void WP_Role object, if the role is added.
+	 * @return WP_Role|null WP_Role object, if the role is added.
 	 */
 	public function add_role( $role, $display_name, $capabilities = array() ) {
 		if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
-			return;
+			return null;
 		}
 
 		if ( wp_is_numeric_array( $capabilities ) ) {

src/wp-includes/class-wp-scripts.php

@@ -201,7 +201,7 @@ public function print_scripts( $handles = false, $group = false ) {
 	 * @param string $handle  The script's registered handle.
 	 * @param bool   $display Optional. Whether to print the extra script
 	 *                        instead of just returning it. Default true.
-	 * @return bool|string|void Void if no data exists, extra scripts if `$display` is true,
+	 * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
 	 *                          true otherwise.
 	 */
 	public function print_scripts_l10n( $handle, $display = true ) {
@@ -217,13 +217,13 @@ public function print_scripts_l10n( $handle, $display = true ) {
 	 * @param string $handle  The script's registered handle.
 	 * @param bool   $display Optional. Whether to print the extra script
 	 *                        instead of just returning it. Default true.
-	 * @return bool|string|void Void if no data exists, extra scripts if `$display` is true,
+	 * @return bool|string|null Null if no data exists, extra scripts if `$display` is true,
 	 *                          true otherwise.
 	 */
 	public function print_extra_script( $handle, $display = true ) {
 		$output = $this->get_data( $handle, 'data' );
 		if ( ! $output ) {
-			return;
+			return null;
 		}
 
 		/*

src/wp-includes/class-wp-theme-json.php

@@ -4267,7 +4267,7 @@ public function get_data() {
 	 *                   generated in the constructor and merge methods instead
 	 *                   of manually after instantiation.
 	 *
-	 * @return null|void
+	 * @return void
 	 */
 	public function set_spacing_sizes() {
 		_deprecated_function( __METHOD__, '6.6.0' );
@@ -4296,12 +4296,12 @@ public function set_spacing_sizes() {
 					E_USER_NOTICE
 				);
 			}
-			return null;
+			return;
 		}
 
 		// If theme authors want to prevent the generation of the core spacing scale they can set their theme.json spacingScale.steps to 0.
 		if ( 0 === $spacing_scale['steps'] ) {
-			return null;
+			return;
 		}
 
 		$spacing_sizes = static::compute_spacing_sizes( $spacing_scale );

src/wp-includes/class-wp-widget.php

@@ -138,7 +138,7 @@ public function update( $new_instance, $old_instance ) {
 	 * @since 2.8.0
 	 *
 	 * @param array $instance The settings for the particular instance of the widget.
-	 * @return string|void Default return is 'noform'.
+	 * @return string|null Default return is 'noform'. A subclass may opt to return null.
 	 */
 	public function form( $instance ) {
 		echo '<p class="no-options-widget">' . __( 'There are no options for this widget.' ) . '</p>';