Code Modernization: Rename parameters that use reserved keywords in wp-admin/includes/class-plugin-upgrader.php.

While using reserved PHP keywords as parameter name labels is allowed, in the context of function calls using named parameters in PHP 8.0+, this will easily lead to confusion. To avoid that, it is recommended not to use reserved keywords as function parameter names.

This commit renames the `$return` variable in `Plugin_Upgrader` class methods to `$response` and updates the documentation accordingly.

Follow-up to [47409], [52946], [52996].

Props jrf, aristath, poena, justinahinon, SergeyBiryukov.
See #55327.

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

Author: SergeyBiryukov

src/wp-admin/includes/class-plugin-upgrader.php

@@ -505,19 +505,19 @@ public function plugin_info() {
 	 * @since 2.8.0
 	 * @since 4.1.0 Added a return value.
 	 *
-	 * @param bool|WP_Error $return Upgrade offer return.
-	 * @param array         $plugin Plugin package arguments.
-	 * @return bool|WP_Error The passed in $return param or WP_Error.
+	 * @param bool|WP_Error $response The installation response before the installation has started.
+	 * @param array         $plugin   Plugin package arguments.
+	 * @return bool|WP_Error The original `$response` parameter or WP_Error.
 	 */
-	public function deactivate_plugin_before_upgrade( $return, $plugin ) {
+	public function deactivate_plugin_before_upgrade( $response, $plugin ) {
 
-		if ( is_wp_error( $return ) ) { // Bypass.
-			return $return;
+		if ( is_wp_error( $response ) ) { // Bypass.
+			return $response;
 		}
 
 		// When in cron (background updates) don't deactivate the plugin, as we require a browser to reactivate it.
 		if ( wp_doing_cron() ) {
-			return $return;
+			return $response;
 		}
 
 		$plugin = isset( $plugin['plugin'] ) ? $plugin['plugin'] : '';
@@ -530,7 +530,7 @@ public function deactivate_plugin_before_upgrade( $return, $plugin ) {
 			deactivate_plugins( $plugin, true );
 		}
 
-		return $return;
+		return $response;
 	}
 
 	/**
@@ -540,33 +540,33 @@ public function deactivate_plugin_before_upgrade( $return, $plugin ) {
 	 *
 	 * @since 5.4.0
 	 *
-	 * @param bool|WP_Error $return Upgrade offer return.
-	 * @param array         $plugin Plugin package arguments.
-	 * @return bool|WP_Error The passed in $return param or WP_Error.
+	 * @param bool|WP_Error $response The installation response before the installation has started.
+	 * @param array         $plugin   Plugin package arguments.
+	 * @return bool|WP_Error The original `$response` parameter or WP_Error.
 	 */
-	public function active_before( $return, $plugin ) {
-		if ( is_wp_error( $return ) ) {
-			return $return;
+	public function active_before( $response, $plugin ) {
+		if ( is_wp_error( $response ) ) {
+			return $response;
 		}
 
 		// Only enable maintenance mode when in cron (background update).
 		if ( ! wp_doing_cron() ) {
-			return $return;
+			return $response;
 		}
 
 		$plugin = isset( $plugin['plugin'] ) ? $plugin['plugin'] : '';
 
 		// Only run if plugin is active.
 		if ( ! is_plugin_active( $plugin ) ) {
-			return $return;
+			return $response;
 		}
 
 		// Change to maintenance mode. Bulk edit handles this separately.
 		if ( ! $this->bulk ) {
 			$this->maintenance_mode( true );
 		}
 
-		return $return;
+		return $response;
 	}
 
 	/**
@@ -576,33 +576,33 @@ public function active_before( $return, $plugin ) {
 	 *
 	 * @since 5.4.0
 	 *
-	 * @param bool|WP_Error $return Upgrade offer return.
-	 * @param array         $plugin Plugin package arguments.
-	 * @return bool|WP_Error The passed in $return param or WP_Error.
+	 * @param bool|WP_Error $response The installation response after the installation has finished.
+	 * @param array         $plugin   Plugin package arguments.
+	 * @return bool|WP_Error The original `$response` parameter or WP_Error.
 	 */
-	public function active_after( $return, $plugin ) {
-		if ( is_wp_error( $return ) ) {
-			return $return;
+	public function active_after( $response, $plugin ) {
+		if ( is_wp_error( $response ) ) {
+			return $response;
 		}
 
 		// Only disable maintenance mode when in cron (background update).
 		if ( ! wp_doing_cron() ) {
-			return $return;
+			return $response;
 		}
 
 		$plugin = isset( $plugin['plugin'] ) ? $plugin['plugin'] : '';
 
-		// Only run if plugin is active
+		// Only run if plugin is active.
 		if ( ! is_plugin_active( $plugin ) ) {
-			return $return;
+			return $response;
 		}
 
 		// Time to remove maintenance mode. Bulk edit handles this separately.
 		if ( ! $this->bulk ) {
 			$this->maintenance_mode( false );
 		}
 
-		return $return;
+		return $response;
 	}
 
 	/**

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

@@ -477,14 +477,14 @@ public function install_package( $args = array() ) {
 		$this->skin->feedback( 'installing_package' );
 
 		/**
-		 * Filters the install response before the installation has started.
+		 * Filters the installation response before the installation has started.
 		 *
 		 * Returning a value that could be evaluated as a `WP_Error` will effectively
 		 * short-circuit the installation, returning that value instead.
 		 *
 		 * @since 2.8.0
 		 *
-		 * @param bool|WP_Error $response   Response.
+		 * @param bool|WP_Error $response   Installation response.
 		 * @param array         $hook_extra Extra arguments passed to hooked filters.
 		 */
 		$res = apply_filters( 'upgrader_pre_install', true, $args['hook_extra'] );