Add ability to filter WP_Upgrader packages before upgrade

[nofearinc]

Although #22378 adds a upgrader_pre_download filter which allows for denying a package for an update, there are cases where we would need to filter the package options or even trigger the upgrader_pre_download filter based on other arguments before that.

A good example would be changing the destination to a local file or an internal repository (like a CDN for plugins) for an internal network for bandwidth or speed purposes.

I'm adding a sample upgrader_package_options filter right before extracting the options in the run() function which is the central point and the last step in the stack for this after calling functions like install() or upgrade() have been fired from different places.

[DrewAPicture]

You'll also need ​hook documentation here.

[nofearinc]

Updated hook docs

[nofearinc]

Fix tabs used for two comment arguments

[chrisjean]

Refresh of the 27754.3.patch based on 4.3-alpha-32330.

[chrisjean]

I refreshed the patch.

I'm personally interested in this update since without this filter, many functions hardwire clear_destination to false. This results in difficulties when users attempt to upgrade existing plugins or themes by supplying a zip file.

With this filter, more advanced install and upgrade features can be implemented without having to create custom implementations of the various upgrader classes just for the purpose of customizing these arguments.

[aaroncampbell]

.4 but from root of develop

[aaroncampbell]

Looks like a useful filter that doesn't seem to be able to be handled elsewhere.

[nacin]

If @dd32 is OK with this, I am too.

[dd32]

The filter opens the possibility for plugins to do a lot of stuff they shouldn't, but plugins can already break things in amazing ways :) So it looks fine to me.

As for the use-case of using a local CDN for update packages, it feels like they would be better served by a caching proxy, but understand why that's not a ideal solution to many.

[dd32]

In 32783:

Updats: Add a filter for the options params for the update being performed.
Props nofearinc. Fixes #27754