Filter Since 2.8.0 uncanny-automator-pro

upgrader_clear_destination

Filter whether the upgrader cleared the destination. Filters whether the upgrader successfully cleared the destination directory after an update.

add_filter( 'upgrader_clear_destination', $callback, 10, 4 );

Description

Fires after the upgrader attempts to clear a plugin or theme destination directory. Developers can use this filter to modify the success status or perform custom actions based on whether the destination was cleared, potentially returning a `WP_Error` on failure.

Usage

add_filter( 'upgrader_clear_destination', 'your_function_name', 10, 4 );

Parameters

$removed (mixed)
Whether the destination was cleared. true on success, WP_Error on failure
$local_destination (string)
The local package destination.
$remote_destination (string)
The remote package destination.
$hook_extra (array)
Extra arguments passed to hooked filters.

Return Value

The filtered value.

Examples

/**
 * Example function to hook into 'upgrader_clear_destination'.
 *
 * This function demonstrates how to intercept the clearing of a plugin's
 * destination directory during an upgrade process. It adds a custom check
 * to ensure that a critical file is not removed if it exists.
 *
 * @param mixed  $removed           Whether the destination was cleared. true on success, WP_Error on failure.
 * @param string $local_destination The local package destination.
 * @param string $remote_destination The remote package destination.
 * @param array  $hook_extra        Extra arguments passed to hooked filters.
 *
 * @return bool|WP_Error True if the destination was cleared (or if our custom logic allows it),
 *                       WP_Error if an error occurred or if our logic prevents clearing.
 */
function my_custom_upgrader_clear_destination( $removed, $local_destination, $remote_destination, $hook_extra ) {
	// If the destination was already cleared or an error occurred, pass it through.
	if ( true === $removed || is_wp_error( $removed ) ) {
		return $removed;
	}

	// Get the plugin slug from the hook_extra if available.
	// This assumes the hook_extra contains a 'plugin' key with the plugin slug.
	$plugin_slug = isset( $hook_extra['plugin'] ) ? $plugin_slug : '';

	// Define a critical file that should never be removed during an upgrade.
	$critical_file_path = trailingslashit( $local_destination ) . 'my-critical-file.php';

	// Check if the critical file exists in the current local destination.
	// We use WP_Filesystem directly here for consistency within the upgrader context.
	global $wp_filesystem;
	if ( $plugin_slug === 'my-special-plugin' && $wp_filesystem->exists( $critical_file_path ) ) {
		// If it's our special plugin and the critical file exists, prevent the destination from being cleared.
		// We return false to indicate that the destination was *not* cleared by this filter,
		// allowing the upgrader to handle the situation or potentially abort.
		// A more robust implementation might return a WP_Error with a specific message.
		return false;
	}

	// If our custom logic doesn't interfere, return the original $removed status.
	return $removed;
}
add_filter( 'upgrader_clear_destination', 'my_custom_upgrader_clear_destination', 10, 4 );

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

uncanny-automator-pro/src/core/admin/installer/includes/class-upgrader.php:503

* @param string $local_destination  The local package destination.
			 * @param string $remote_destination The remote package destination.
			 * @param array  $hook_extra         Extra arguments passed to hooked filters.
			 *
			 * @since 2.8.0
			 *
			 */
			$removed = apply_filters( 'upgrader_clear_destination', $removed, $local_destination, $remote_destination, $args['hook_extra'] );

			if ( is_wp_error( $removed ) ) {
				return $removed;
			}
		} elseif ( $args['abort_if_destination_exists'] && $wp_filesystem->exists( $remote_destination ) ) {
			// If we're not clearing the destination folder and something exists there already, Bail.
			// But first check to see if there are actually any files in the folder.
Scroll to Top