Changeset 61406

Timestamp:

12/24/2025 05:06:43 PM (3 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'] );