Safely Bulk-Update Custom Fields in WordPress

<?php
/**
 * Plugin Name: TE Safe Batch Updater
 * Plugin URI:  https://techearl.com/wordpress-safe-batch-update-custom-fields
 * Description: A WP-CLI command for bulk custom-field updates with a dry run, backup gate, and change-only changelog.
 * Version:     1.0.0
 * Author:      Ishan Karunaratne
 * Author URI:  https://techearl.com
 * License:     GPL-2.0-or-later
 */

defined( 'ABSPATH' ) || exit;

if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
	return;
}

class TE_Safe_Batch_Command {

	/**
	 * Bulk-update a post-meta key across a post type, safely.
	 *
	 * ## OPTIONS
	 *
	 * --meta_key=<key>
	 * : The meta key to update.
	 *
	 * --value=<value>
	 * : The new value to set.
	 *
	 * [--post_type=<type>]
	 * : Post type to target. Default: post.
	 *
	 * [--live]
	 * : Actually write. Without this flag the command is a dry run.
	 *
	 * ## EXAMPLES
	 *     wp te-batch update_meta --meta_key=currency --value=USD
	 *     wp te-batch update_meta --meta_key=currency --value=USD --live
	 */
	public function update_meta( $args, $assoc ): void {
		$meta_key  = $assoc['meta_key'];
		$value     = $assoc['value'];
		$post_type = $assoc['post_type'] ?? 'post';
		$live      = isset( $assoc['live'] );

		$ids = get_posts( array(
			'post_type'      => $post_type,
			'post_status'    => 'any',
			'posts_per_page' => -1,
			'fields'         => 'ids',
			'no_found_rows'  => true,
		) );

		// Rail 2: a live run must back up the rows it will touch, first.
		if ( $live ) {
			$backup = te_safe_batch_backup( $ids, $meta_key );
			WP_CLI::log( "Backup written: {$backup}" );
		}

		$changes = array();
		foreach ( $ids as $id ) {
			$current = get_post_meta( $id, $meta_key, true );

			// Rail 3 + 4: skip rows already at the target. Idempotent, and it
			// keeps the changelog to genuine changes only.
			if ( (string) $current === (string) $value ) {
				continue;
			}

			$changes[] = array( 'id' => $id, 'old' => $current, 'new' => $value );

			if ( $live ) {
				update_post_meta( $id, $meta_key, $value );
			}
		}

		if ( empty( $changes ) ) {
			WP_CLI::success( 'Nothing to change. Every row already matches.' );
			return;
		}

		WP_CLI\Utils\format_items( 'table', array_slice( $changes, 0, 20 ), array( 'id', 'old', 'new' ) );

		$mode = $live ? 'updated' : 'WOULD update (dry run)';
		WP_CLI::success( sprintf( '%d rows %s. %d already matched.', count( $changes ), $mode, count( $ids ) - count( $changes ) ) );

		if ( ! $live ) {
			WP_CLI::log( 'Re-run with --live to apply. A backup is taken automatically before the first write.' );
		}
	}
}

WP_CLI::add_command( 'te-batch', 'TE_Safe_Batch_Command' );

/**
 * Rail 2: dump the current key/value for every target row to a timestamped
 * file before any write, so a bad run is always recoverable.
 */
function te_safe_batch_backup( array $ids, string $meta_key ): string {
	$rows = array();
	foreach ( $ids as $id ) {
		$rows[] = array( 'id' => $id, $meta_key => get_post_meta( $id, $meta_key, true ) );
	}
	$file = WP_CONTENT_DIR . '/te-batch-backup-' . $meta_key . '-' . gmdate( 'Ymd-His' ) . '.json';
	file_put_contents( $file, wp_json_encode( $rows ) );
	return $file;
}

public function test_dry_run_writes_nothing(): void {
	$post_id = self::factory()->post->create();
	update_post_meta( $post_id, 'currency', 'GBP' );

	// Dry run: no --live flag.
	( new TE_Safe_Batch_Command() )->update_meta( array(), array(
		'meta_key' => 'currency',
		'value'    => 'USD',
	) );

	$this->assertSame( 'GBP', get_post_meta( $post_id, 'currency', true ), 'Dry run must not write.' );
}

public function test_live_run_is_idempotent(): void {
	$post_id = self::factory()->post->create();
	update_post_meta( $post_id, 'currency', 'GBP' );

	$cmd = new TE_Safe_Batch_Command();
	$cmd->update_meta( array(), array( 'meta_key' => 'currency', 'value' => 'USD', 'live' => true ) );
	$cmd->update_meta( array(), array( 'meta_key' => 'currency', 'value' => 'USD', 'live' => true ) );

	$this->assertSame( 'USD', get_post_meta( $post_id, 'currency', true ) );
}