Add filter for results of `WP_Upgrader::install_package()`

[afragen]

Adding a filter to the result of install_package() in WP_Upgrader::install_package() allows for the capture and usage of error data resulting from the install_package() function.

The proposed filter additionally allows for a potential plugin/theme rollback in the event of an update failure due to copy_dir(), but more generally a failure during install_package(). A rollback feature for plugin/theme update failures was originally proposed in #51857.

A feature plugin ​Rollback Update Failure is available for testing utilizing this filter.

Adding a filter to the result of copy_dir() in WP_Upgrader::install_package() allows for the capture and usage of error data resulting from the copy_dir() function.

The proposed filter additionally allows for a potential plugin/theme rollback in the event of an update failure due to copy_dir(). A rollback feature for plugin/theme update failures was originally proposed in #51857.

A feature plugin ​Rollback Update Failure is available for testing utilizing this filter.

Trac ticket: https://core.trac.wordpress.org/ticket/52381

[afragen]

Moved filter to more general upgrader_install_complete after the install_package() process.

[hellofromTonya]

Update from today's core scrub: this ticket is ready for a code review and then it can be committed for 5.7 Beta 1.

[dd32]

Reviewing PR925, it took me quite some time to figure out exactly why it's wanted/required/needed.

Philosophically I feel that upgrader_pre_install and upgrader_post_install should've covered these, however the latter is only run on a successful call to install_package(), and that's written into a lot of existing code, so changing it's behaviour isn't really possible.

Adding a filter, potentially marked as temporary for a feature plugin, makes sense to me, but I'd probably just call it upgrader_install_package_result instead.

[afragen]

PR updated for upgrader_install_package_result

Yes, the idea with this filter is to pick up a failure of install_package() not a success as upgrader_post_install picks up.

[afragen]

PR updated, ready for commit

[SergeyBiryukov]

In 50151:

Upgrade/Install: Introduce a filter for the result of WP_Upgrader::install_package().

This allows for the capture and usage of error data from the method, to facilitate a potential plugin/theme rollback in the event of an update failure.

Props afragen, dd32.
Fixes #52381.