Changeset 61406

Timestamp:

12/24/2025 05:06:43 PM (8 months ago)

Author:

johnbillion

Message:

Upgrade/Install: Correct and improve various docblocks relating to upgrades.

See #64224

File:

• trunk/src/wp-admin/includes/class-wp-upgrader.php (modified) (5 diffs)

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

@@ -293 +293 @@
 
         /**
-         * Downloads a package.
+         * Downloads a package for a WordPress core, plugin, theme, or translation upgrade.
          *
          * @since 2.8.0
@@ -299 +299 @@
          * @since 5.5.0 Added the `$hook_extra` parameter.
          *
-         * @param string $package          The URI of the package. If this is the full path to an
-         *                                 existing local file, it will be returned untouched.
+         * @param string $package          The URI of the package. May be a remote URL or local file path. If this is the full
+         *                                 path to an existing local file, it will be returned untouched.
          * @param bool   $check_signatures Whether to validate file signatures. Default false.
          * @param array  $hook_extra       Extra arguments to pass to the filter hooks. Default empty array.
@@ -307 +307 @@
         public function download_package( $package, $check_signatures = false, $hook_extra = array() ) {
                 /**
-                 * Filters whether to return the package.
+                 * Filters whether to download a package for a WordPress core, plugin, theme, or translation upgrade.
+                 *
+                 * Return a non-false value to short-circuit the download and return that value instead.
                  *
                  * @since 3.7.0
                  * @since 5.5.0 Added the `$hook_extra` parameter.
                  *
-                 * @param bool        $reply      Whether to bail without returning the package.
-                 *                                Default false.
-                 * @param string      $package    The package file name.
-                 * @param WP_Upgrader $upgrader   The WP_Upgrader instance.
-                 * @param array       $hook_extra Extra arguments passed to hooked filters.
+                 * @param false|string|WP_Error $reply      Whether to short-circuit the download, the path to the downloaded package,
+                 *                                          or a WP_Error object. Default false.
+                 * @param string                $package    The package URI. May be a remote URL or local file path.
+                 * @param WP_Upgrader           $upgrader   The WP_Upgrader instance.
+                 * @param array                 $hook_extra Extra arguments passed to hooked filters.
                  */
                 $reply = apply_filters( 'upgrader_pre_download', false, $package, $this, $hook_extra );
@@ -520 +522 @@
                 $args = wp_parse_args( $args, $defaults );
 
-                // These were previously extract()'d.
                 $source            = $args['source'];
                 $destination       = $args['destination'];
@@ -593 +594 @@
                  * @since 4.4.0 The `$hook_extra` parameter became available.
                  *
-                 * @param string      $source        File source location.
-                 * @param string      $remote_source Remote file source location.
-                 * @param WP_Upgrader $upgrader      WP_Upgrader instance.
-                 * @param array       $hook_extra    Extra arguments passed to hooked filters.
+                 * @param string|WP_Error $source        File source location or a WP_Error object.
+                 * @param string          $remote_source Remote file source location.
+                 * @param WP_Upgrader     $upgrader      WP_Upgrader instance.
+                 * @param array           $hook_extra    Extra arguments passed to hooked filters.
                  */
                 $source = apply_filters( 'upgrader_source_selection', $source, $remote_source, $this, $args['hook_extra'] );