WP_Upgrader::run( array $options ): array|false|WP_Error

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$optionsarray

Array or string of arguments for upgrading/installing a package.

• $packagestringdefault: empty

  The full path or URI of the package to install.

• $destinationstringdefault: empty

  The full path to the destination folder.

• $clear_destinationbooldefault: false

  Whether to delete any files already in the destination folder.

• $clear_workingbooldefault: true

  Whether to delete the files from the working directory after copying them to the destination.

• $abort_if_destination_existsbooldefault: true

  Whether to abort the installation if the destination folder already exists. When true, $clear_destination should be false.

• $is_multibooldefault: false

  Whether this run is one of multiple upgrade/installation actions being performed in bulk. When true, the skin WP_Upgrader::header() and WP_Upgrader::footer() aren't called.

• $hook_extraarray

  Extra arguments to pass to the filter hooks called by WP_Upgrader::run().

Return value

array|false|WP_Error

The result from self::install_package() on success, otherwise a WP_Error, or false if unable to connect to the filesystem.

Performance profile

How much work a call to WP_Upgrader::run() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Expensive

Reaches an outbound HTTP request via wp_remote_post().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

26–188

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 237.

Plugin surface

3 hooks

Third-party callbacks on 'upgrader_package_options', 'upgrader_install_package_result', 'upgrader_process_complete' run inside this call, and their cost is not bounded by anything here.

Called by

0

Nothing in core calls this; the cost is only what you spend yourself.

What it touches

• hookthird-party callbacksapply_filters()called directly
• transienttransientget_site_transient()one call below WP_Upgrader::run()
• optionnetwork optionget_site_option()one call below WP_Upgrader::run()
• httpoutbound HTTP requestwp_remote_post()one call below WP_Upgrader::run()

Further down the call graph this can also reach cache, serialize and query. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 104 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Upgrader::run() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 3

3 hooks fire while WP_Upgrader::run() runs, in this order:

1. 1
   apply_filters( upgrader_package_options )filterline 818 (+44 into the body)

   Filters the package options before running an update.

2. 2
   apply_filters( upgrader_install_package_result )filterline 917 (+143 into the body)

   Filters the result of WP_Upgrader::install_package().

3. 3
   do_action( upgrader_process_complete )actionline 988 (+214 into the body)

   Fires when the upgrader process is complete.

Uses · 10

• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• wp_version_check()Checks WordPress version against the newest version.
• add_action()Adds a callback function to an action hook.
• do_action()Calls the callback functions that have been added to an action hook.
• WP_Upgrader::fs_connect()Connects to the filesystem.
• WP_Upgrader::download_package()Downloads a package for a WordPress core, plugin, theme, or translation upgrade.
• WP_Upgrader::unpack_package()Unpacks a compressed package file.
• WP_Upgrader::install_package()Install a package.

Source code

View on Trac ↗View on GitHub ↗

774	public function run( $options ) {775 776		$defaults = array(777			'package'                     => '', // Please always pass this.778			'destination'                 => '', // ...and this.779			'clear_destination'           => false,780			'clear_working'               => true,781			'abort_if_destination_exists' => true, // Abort if the destination directory exists. Pass clear_destination as false please.782			'is_multi'                    => false,783			'hook_extra'                  => array(), // Pass any extra $hook_extra args here, this will be passed to any hooked filters.784		);785 786		$options = wp_parse_args( $options, $defaults );787 788		/**789		 * Filters the package options before running an update.790		 *791		 * See also {@see 'upgrader_process_complete'}.792		 *793		 * @since 4.3.0794		 *795		 * @param array $options {796		 *     Options used by the upgrader.797		 *798		 *     @type string $package                     Package for update.799		 *     @type string $destination                 Update location.800		 *     @type bool   $clear_destination           Clear the destination resource.801		 *     @type bool   $clear_working               Clear the working resource.802		 *     @type bool   $abort_if_destination_exists Abort if the Destination directory exists.803		 *     @type bool   $is_multi                    Whether the upgrader is running multiple times.804		 *     @type array  $hook_extra {805		 *         Extra hook arguments.806		 *807		 *         @type string $action               Type of action. Default 'update'.808		 *         @type string $type                 Type of update process. Accepts 'plugin', 'theme', or 'core'.809		 *         @type bool   $bulk                 Whether the update process is a bulk update. Default true.810		 *         @type string $plugin               Path to the plugin file relative to the plugins directory.811		 *         @type string $theme                The stylesheet or template name of the theme.812		 *         @type string $language_update_type The language pack update type. Accepts 'plugin', 'theme',813		 *                                            or 'core'.814		 *         @type object $language_update      The language pack update offer.815		 *     }816		 * }817		 */818		$options = apply_filters( 'upgrader_package_options', $options );819 820		if ( ! $options['is_multi'] ) { // Call $this->header separately if running multiple times.821			$this->skin->header();822		}823 824		// Connect to the filesystem first.825		$res = $this->fs_connect( array( WP_CONTENT_DIR, $options['destination'] ) );826		// Mainly for non-connected filesystem.827		if ( ! $res ) {828			if ( ! $options['is_multi'] ) {829				$this->skin->footer();830			}831			return false;832		}833 834		$this->skin->before();835 836		if ( is_wp_error( $res ) ) {837			$this->skin->error( $res );838			$this->skin->after();839			if ( ! $options['is_multi'] ) {840				$this->skin->footer();841			}842			return $res;843		}844 845		/*846		 * Download the package. Note: If the package is the full path847		 * to an existing local file, it will be returned untouched.848		 */849		$download = $this->download_package( $options['package'], false, $options['hook_extra'] );850 851		/*852		 * Allow for signature soft-fail.853		 * WARNING: This may be removed in the future.

Changelog

Introduced in 2.8.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-admin/includes/class-wp-upgrader.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.