Cleanup script: Remove Basic User Avatars meta + files after PMPro migration.

cleanup-bua.php

<?php
/**
 * Cleanup script: Remove Basic User Avatars meta + files after PMPro migration.
 * Use the migration script first: https://gist.github.com/kimcoleman/f031b36f4a685eff315390ccc19889b1
 *
 * Run this as a WP-CLI command.
 * Save this code to a file cleanup-bua.php.
 * Put the file in your WordPress root directory (the same folder where wp-config.php lives).
 *
 * WP-CLI usage: wp eval-file cleanup-bua.php
 * Update the $dry_run value to "false" to run the actual cleanup.
 *
 */
$dry_run = true;

if ( $dry_run ) {
	WP_CLI::log( '--- DRY RUN MODE — no changes will be made ---' );
}

// Only clean up users who have basic_user_avatar meta.
$users = get_users( array(
	'meta_key'     => 'basic_user_avatar',
	'meta_compare' => 'EXISTS',
	'fields'       => 'ids',
	'number'       => -1,
) );

if ( empty( $users ) ) {
	WP_CLI::log( 'No users with basic_user_avatar meta found. Nothing to clean up.' );
	exit;
}

WP_CLI::log( sprintf( 'Found %d user(s) with basic_user_avatar meta.', count( $users ) ) );

$cleaned = 0;
$skipped = 0;

foreach ( $users as $user_id ) {
	// Safety check: only clean up if PMPro avatar migration succeeded.
	$pmpro_avatar = get_user_meta( $user_id, 'pmpro_avatar', true );
	if ( empty( $pmpro_avatar ) ) {
		WP_CLI::warning( sprintf( 'User %d: no pmpro_avatar found — skipping (migration may have failed).', $user_id ) );
		$skipped++;
		continue;
	}

	$basic_avatar = get_user_meta( $user_id, 'basic_user_avatar', true );
	$upload_dir   = wp_upload_dir();
	$base_url     = str_replace( 'https://', 'http://', $upload_dir['baseurl'] );

	// Delete all local files stored in the BUA meta (full + any sized variants).
	if ( is_array( $basic_avatar ) ) {
		foreach ( $basic_avatar as $key => $file_url ) {
			if ( empty( $file_url ) || ! is_string( $file_url ) ) {
				continue;
			}

			$clean_url = str_replace( 'https://', 'http://', strtok( $file_url, '?' ) );

			// Only attempt to delete files that live in our uploads directory.
			if ( strpos( $clean_url, $base_url ) !== 0 ) {
				WP_CLI::log( sprintf( 'User %d: skipping non-local file for key "%s": %s', $user_id, $key, $file_url ) );
				continue;
			}

			$relative_path = substr( $clean_url, strlen( $base_url ) );
			$file_path     = $upload_dir['basedir'] . $relative_path;

			if ( file_exists( $file_path ) ) {
				WP_CLI::log( sprintf( 'User %d: deleting file [%s] %s', $user_id, $key, $file_path ) );
				if ( ! $dry_run ) {
					unlink( $file_path );
				}
			} else {
				WP_CLI::log( sprintf( 'User %d: file already missing [%s] %s', $user_id, $key, $file_path ) );
			}
		}
	}

	// Delete the meta.
	WP_CLI::log( sprintf( 'User %d: removing basic_user_avatar meta.', $user_id ) );
	if ( ! $dry_run ) {
		delete_user_meta( $user_id, 'basic_user_avatar' );
	}

	$cleaned++;
}

WP_CLI::log( sprintf( 'Cleanup complete. Cleaned: %d | Skipped: %d', $cleaned, $skipped ) );