Changeset 62179 for trunk

Timestamp:

03/30/2026 06:01:58 AM (7 months ago)

Author:

westonruter

Message:

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

Replace void in union return types with null or remove it where the function always returns a value or dies, across 8 files in wp-admin/includes. Adds explicit return null; statements where functions previously fell through without a return value.

Additionally:

• Adds @return never for media_send_to_editor() and removes misleading return from its callers.
• Removes void from return types where the function always returns a value or exits: write_post(), WP_Importer::set_blog(), WP_Importer::set_user().
• Replaces mixed|void with a specific array shape for WP_Site_Health::perform_test().

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

Follow-up to r62178, r62177, r61766, r61719.

Props apermo, xate, westonruter, mukesh27, desrosj.
Fixes #64702.

Location:

trunk/src/wp-admin/includes

Files:

• class-wp-importer.php (modified) (2 diffs)
• class-wp-privacy-requests-table.php (modified) (2 diffs)
• class-wp-site-health.php (modified) (1 diff)
• dashboard.php (modified) (2 diffs)
• file.php (modified) (2 diffs)
• media.php (modified) (4 diffs)
• plugin.php (modified) (2 diffs)
• post.php (modified) (2 diffs)

trunk/src/wp-admin/includes/class-wp-importer.php

@@ -136 +136 @@
 
         /**
-         * @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 Blog ID on success. Exits on failure.
          */
         public function set_blog( $blog_id ) {
@@ -178 +184 @@
         /**
          * @param int $user_id
-         * @return int|void
+         * @return int
          */
         public function set_user( $user_id ) {

trunk/src/wp-admin/includes/class-wp-privacy-requests-table.php

@@ -436 +436 @@
          *
          * @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.
          */
@@ -466 +466 @@
 
                 echo '</span>';
+                return null;
         }
 

trunk/src/wp-admin/includes/class-wp-site-health.php

@@ -168 +168 @@
          *
          * @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 ) {

trunk/src/wp-admin/includes/dashboard.php

@@ -1649 +1649 @@
  * @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() {
@@ -1710 +1710 @@
         </div>
         <?php
+        return null;
 }
 

trunk/src/wp-admin/includes/file.php

@@ -735 +735 @@
  * @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 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() ) {
@@ -754 +754 @@
                         wp_die( __( 'Sorry, that file cannot be edited.' ) );
         }
+        return null;
 }
 

trunk/src/wp-admin/includes/media.php

@@ -270 +270 @@
  *
  * @param string $html
+ * @return never
  */
 function media_send_to_editor( $html ) {
@@ -754 +755 @@
  * @since 2.5.0
  *
- * @return null|array|void Array of error messages keyed by attachment ID, null or void on success.
+ * @return null|array Array of error messages keyed by attachment ID, null on success, or exit.
  */
 function media_upload_form_handler() {
@@ -875 +876 @@
                 $html = apply_filters( 'media_send_to_editor', $html, $send_id, $attachment );
 
-                return media_send_to_editor( $html );
+                media_send_to_editor( $html );
         }
 
@@ -977 +978 @@
                 }
 
-                return media_send_to_editor( $html );
+                media_send_to_editor( $html );
         }
 

trunk/src/wp-admin/includes/plugin.php

@@ -1297 +1297 @@
  *
  * @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 ) {
@@ -1351 +1351 @@
                 do_action( "uninstall_{$file}" );
         }
+        return null;
 }
 

trunk/src/wp-admin/includes/post.php

@@ -983 +983 @@
  * @since 2.0.0
  *
- * @return int|void Post ID on success, void on failure.
+ * @return int Post ID on success. Dies on failure.
  */
 function write_post() {
@@ -989 +989 @@
         if ( is_wp_error( $result ) ) {
                 wp_die( $result->get_error_message() );
-        } else {
-                return $result;
-        }
+        }
+
+        return $result;
 }