upgrader_clear_destination

Description

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

<?php
/**
 * Example function to hook into 'upgrader_clear_destination'.
 * This example checks if the cleared destination is a specific plugin directory
 * and, if so, prevents the clearing if a specific file exists within it,
 * simulating a scenario where an important file should not be removed.
 *
 * @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 mixed                    The original $removed value, or a WP_Error if the action is prevented.
 */
function my_prevent_clearing_specific_plugin_destination( $removed, $local_destination, $remote_destination, $hook_extra ) {
	// Define a specific plugin slug we want to protect.
	$protected_plugin_slug = 'my-important-plugin';
	$protected_file_name   = 'important-configuration.txt';

	// Check if the $remote_destination is within the plugins directory and matches our protected plugin.
	if ( strpos( $remote_destination, '/' . $protected_plugin_slug . '/' ) !== false ) {
		$destination_exists = false;
		// Use WP_Filesystem to check for the existence of the protected file.
		// Note: In a real scenario, you'd need to ensure $wp_filesystem is available.
		// For this example, we'll assume it's a global or passed in a more complex context.
		// A common way to get it is via WP_Filesystem_Base().
		global $wp_filesystem;
		if ( ! $wp_filesystem ) {
			// Attempt to get the filesystem instance if not already global.
			require_once ABSPATH . 'wp-admin/includes/file.php';
			$wp_filesystem = WP_Filesystem();
		}

		if ( $wp_filesystem && $wp_filesystem->exists( trailingslashit( $remote_destination ) . $protected_file_name ) ) {
			$destination_exists = true;
		}

		if ( $destination_exists ) {
			// If the protected file exists, prevent the clearing of the destination.
			// Return a WP_Error to signal the failure and the reason.
			return new WP_Error(
				'plugin_destination_protected',
				__( 'The destination for My Important Plugin cannot be cleared because an important configuration file exists.', 'your-text-domain' )
			);
		}
	}

	// If we're not protecting this destination, or the protected file doesn't exist,
	// return the original $removed value to allow the clearing process to continue.
	return $removed;
}

// Add the filter with a priority and specify the number of arguments accepted.
// We are accepting all 4 arguments: $removed, $local_destination, $remote_destination, $hook_extra.
add_filter( 'upgrader_clear_destination', 'my_prevent_clearing_specific_plugin_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

src/install-automator/vendor/uncanny-one-click-installer/includes/PluginSilentUpgrader.php:504

* @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.