From 6198504e2f09904af1255a670efa59c9c58fb845 Mon Sep 17 00:00:00 2001
From: Huzaifa Al Mesbah <huzaifah4m@gmail.com>
Date: Sat, 21 Feb 2026 09:40:08 +0600
Subject: [PATCH] Docs: Explicitly return `null` when documented instead of
 `void` in filesystem and category functions.

The @return tags for these functions indicate they may return `null`.
This fixes "Missing return argument" warnings that PHPStan (level 1) and
IDEs report when a bare `return;` is used in a function documented to
return a typed value including `null`.

Affected functions:
- `WP_Filesystem()` in wp-admin/includes/file.php
- `delete_plugins()` in wp-admin/includes/plugin.php (2 occurrences)
- `delete_theme()` in wp-admin/includes/theme.php (2 occurrences)
- `get_category_by_path()` in wp-includes/category.php

No functional change. Follows the approach used in changeset 61281.
See #64238.
---
 src/wp-admin/includes/file.php   | 2 +-
 src/wp-admin/includes/plugin.php | 4 ++--
 src/wp-admin/includes/theme.php  | 4 ++--
 src/wp-includes/category.php     | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/wp-admin/includes/file.php b/src/wp-admin/includes/file.php
index 09d080da2dd6e..99dc03c6cd656 100644
--- a/src/wp-admin/includes/file.php
+++ b/src/wp-admin/includes/file.php
@@ -2187,7 +2187,7 @@ function WP_Filesystem( $args = false, $context = false, $allow_relaxed_file_own
 		$abstraction_file = apply_filters( 'filesystem_method_file', ABSPATH . 'wp-admin/includes/class-wp-filesystem-' . $method . '.php', $method );
 
 		if ( ! file_exists( $abstraction_file ) ) {
-			return;
+			return null;
 		}
 
 		require_once $abstraction_file;
diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 460874ca52181..fae10f1a679a4 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -926,7 +926,7 @@ function delete_plugins( $plugins, $deprecated = '' ) {
 			require_once ABSPATH . 'wp-admin/admin-footer.php';
 			exit;
 		}
-		return;
+		return null;
 	}
 
 	if ( ! WP_Filesystem( $credentials ) ) {
@@ -941,7 +941,7 @@ function delete_plugins( $plugins, $deprecated = '' ) {
 			require_once ABSPATH . 'wp-admin/admin-footer.php';
 			exit;
 		}
-		return;
+		return null;
 	}
 
 	if ( ! is_object( $wp_filesystem ) ) {
diff --git a/src/wp-admin/includes/theme.php b/src/wp-admin/includes/theme.php
index 8fa5d06a16a3b..ef5793b7dd118 100644
--- a/src/wp-admin/includes/theme.php
+++ b/src/wp-admin/includes/theme.php
@@ -40,7 +40,7 @@ function delete_theme( $stylesheet, $redirect = '' ) {
 			require_once ABSPATH . 'wp-admin/admin-footer.php';
 			exit;
 		}
-		return;
+		return null;
 	}
 
 	if ( ! WP_Filesystem( $credentials ) ) {
@@ -55,7 +55,7 @@ function delete_theme( $stylesheet, $redirect = '' ) {
 			require_once ABSPATH . 'wp-admin/admin-footer.php';
 			exit;
 		}
-		return;
+		return null;
 	}
 
 	if ( ! is_object( $wp_filesystem ) ) {
diff --git a/src/wp-includes/category.php b/src/wp-includes/category.php
index d1c43274d704b..8fb6b1c5479ba 100644
--- a/src/wp-includes/category.php
+++ b/src/wp-includes/category.php
@@ -144,7 +144,7 @@ function get_category_by_path( $category_path, $full_match = true, $output = OBJ
 	);
 
 	if ( empty( $categories ) ) {
-		return;
+		return null;
 	}
 
 	foreach ( $categories as $category ) {