Allow plugins and themes perform extra checks upon install/upgrade via filter

[LeonidasMilossis]

Currently, if a plugin (or a theme) wants to perform custom checks upon plugin install/upgrade, they need to either hook into the existing upgrader_source_selection filter or extend the Plugin_Upgrader class, which is suboptimal as it leads to code duplication and/or processes being repeated on every install/upgrade.

Ideally, we can have a more specific filter for more granularity in the process.

For example, say a plugin wants to check against a custom plugin header (potentially added via the extra_plugin_headers filter). By having a filter at the end of the Plugin_Upgrader::check_package() (or the respective one from Theme_Upgrader), after all the core checks have been passed, we can allow plugin authors to just add additional checks depending on their needs.

That filter will allow plugins to hook into it and return a WP_Error like the checks above it, to prevent installs/upgrade when a custom check fails.

All that would be especially useful for plugin add-ons that require a minimum installed version of their main plugin to be active before installed/upgraded.

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

[LeonidasMilossis]

With the above PR, the following filters are introduced:

• plugin_upgrader_checked_package
• theme_upgrader_checked_package

That way, a plugin can extend the checks performed by core upon plugin install, by hooking into the new filter, in order to check the minimum required version of the main plugin whenever an add-on is installed/upgraded, like:

<?php
add_filter( 'plugin_upgrader_checked_package', [ $this, 'check_requirement' ], 10, 2 );

public function check_requirement( $source, $info ) {
        $requires_xyz = ! empty( $info['Requires XYZ'] ) ? $info['Requires XYZ'] : false;
        if ( $requires_xyz === false ) {
                return $source;
        }

        if ( version_compare( XYZ_VERSION, $requires_xyz, '>=' ) ) {
                return $source;
        }

        $error = sprintf(
                __( 'The XYZ version on your site is %1$s, however the uploaded plugin requires %2$s.', 'xyz-addon' ),
                XYZ_VERSION,
                esc_html( $requires_xyz )
        );

        return new WP_Error(
                'incompatible_xyz_required_version',
                __( 'The package could not be installed because it\'s not supported by the currently installed XYZ version.', 'xyz-addon' ),
                $error
        );
}

[afercia]

Seems a good use case for two new filters to me.

Question: should the two new filters follow the naming convention of the hooks already present in the Plugin_Upgrader and Theme_Upgrader classes? They have the same names, not prefixed by plugin or theme. Then, a third param is passed to the hooks to determine whether the package type is 'plugin' or 'theme'. See:

• upgrader_overwrote_package
• upgrader_process_complete

Looking at the current patch, I'm wondering if there should be any sort of guardrails on the $source that's returned from the new filter to ensure it's either a WP_Error or a (string) $path and that path is in the WP_CONTENT_DIR, WP_PLUGINS_DIR, or whatever path we'd want this constrained to. @afragen and I discussed this a bit ad WCUS CD.

Extra props @afragen.

Personally, I'd rather not guard against $source being a part of any specific path, which would limit the third-party author's flexibility. The filter is added to grant them that flexibility, is there a reason I miss to restrain that?

[davidbaumwald]

I'd still like to have this reviewed by other committers and maintainers to see if there's any issue with doing this and what, if any, considerations should be made in the patch.

With 6.7 Beta 1 releasing in a few hours, this is being moved to 6.8 given recent momentum towards a resolution.

If any committer feels the remaining work can be resolved in time for Beta 1 and wishes to assume ownership, feel free to update the milestone accordingly.