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 814 (+44 into the body)

   Filters the package options before running an update.

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

   Filters the result of WP_Upgrader::install_package().

3. 3
   do_action( upgrader_process_complete )actionline 984 (+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.
• WP_Upgrader::unpack_package()Unpacks a compressed package file.
• WP_Upgrader::install_package()Install a package.

Source code

View on Trac ↗View on GitHub ↗

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