chromed

Back Back Up Advanced Editor

<?php

namespace WPForms\Migrations;

use WPForms\Admin\Forms\Table\Facades\Columns;
use WPForms\Analytics\Analytics;
use WPForms\Helpers\DB;

/**
 * Analytics migration (Lite).
 *
 * Two-step migration shipped with 2.0.0:
 *
 * 1. Analytics table creation is handled by the self-healing custom-tables
 *    registry (WPForms\Helpers\DB::create_custom_tables()). The registry
 *    creates missing tables without dropping data, keeping this step idempotent
 *    across repeated migration runs and fresh installs alike. It does NOT align
 *    columns on tables that already exist — it skips them unchanged, so schema
 *    changes to an existing table need a dedicated migration.
 *
 * 2. Forms Overview saved-columns evolution: append the analytics columns to
 *    each user's saved column meta and remove the now-default-hidden
 *    Shortcode column. Without this, users who customized their column order
 *    before 2.0.0 would have to enable the new analytics columns manually
 *    via Screen Options.
 *
 * Idempotent: the custom-tables registry skips tables that already exist
 * (it does not alter them); the column-meta sweep skips users whose saved meta
 * already contains the analytics columns and has no retired columns to drop.
 *
 * @since 2.0.0
 */
class Upgrade2_0_0 extends UpgradeBase {

/**
	 * Forms Overview columns introduced in 2.0.0.
	 *
	 * @since 2.0.0
	 */
	private const NEW_OVERVIEW_COLUMNS = [
		'analytics_views',
		'analytics_interactions',
		'analytics_conversion',
	];

/**
	 * Forms Overview columns retired (default-hidden) in 2.0.0.
	 *
	 * Removed from saved user meta so the analytics columns become visible
	 * in the same row footprint by default. Users can re-enable Shortcode
	 * via Screen Options - the column itself is still registered.
	 *
	 * @since 2.0.0
	 */
	private const RETIRED_OVERVIEW_COLUMNS = [
		'shortcode',
	];

/**
	 * Anchor key used to position the new analytics columns inside saved meta.
	 *
	 * Inserts the new columns immediately after the Entries column when the
	 * user has it saved; otherwise appends them at the end of the list.
	 *
	 * @since 2.0.0
	 */
	private const OVERVIEW_INSERT_AFTER = 'entries';

/**
	 * Run the upgrade.
	 *
	 * @since 2.0.0
	 *
	 * @return bool|null true = completed, false = failed, null = background task in progress.
	 */
	public function run(): ?bool {

// Tables are created by the self-healing custom-tables registry. This
		// also covers fresh installs where this migration is version-gated out.
		DB::create_custom_tables( true );

// Skip the saved-meta sweep when the analytics feature is killed.
		// Tables remain dormant (not uninstalled), but the per-user column
		// reshuffle is an analytics-feature concern and must not run when the
		// feature is filtered off.
		if ( Analytics::is_enabled() ) {
			$this->migrate_overview_columns_user_meta();
		}

return true;
	}

/**
	 * Sweep every user with saved Forms Overview column meta and bring it in
	 * line with the 2.0.0 default visible set.
	 *
	 * Bounded operation - the meta key is set only for admin users who have
	 * customized columns via Screen Options or drag-and-drop. A direct
	 * usermeta query is cheaper and more PHPCS-friendly than `get_users()`
	 * with `meta_key`.
	 *
	 * @since 2.0.0
	 */
	private function migrate_overview_columns_user_meta(): void {

global $wpdb;

// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.SlowDBQuery.slow_db_query_meta_key
		$user_ids = $wpdb->get_col(
			$wpdb->prepare(
				"SELECT user_id FROM {$wpdb->usermeta} WHERE meta_key = %s",
				Columns::COLUMNS_USER_META_NAME
			)
		);

if ( empty( $user_ids ) ) {
			return;
		}

foreach ( $user_ids as $user_id ) {
			$this->migrate_overview_columns_for_user( (int) $user_id );
		}
	}

/**
	 * Apply the column-meta evolution to one user's saved meta.
	 *
	 * Skips users whose saved meta is empty or non-array. The pure helper
	 * `evolve_overview_columns()` returns the input unchanged when there is
	 * nothing to add and nothing to remove, keeping repeated migration runs
	 * idempotent at zero write cost.
	 *
	 * @since 2.0.0
	 *
	 * @param int $user_id User ID.
	 */
	private function migrate_overview_columns_for_user( int $user_id ): void {

$saved = get_user_meta( $user_id, Columns::COLUMNS_USER_META_NAME, true );

if ( ! is_array( $saved ) || empty( $saved ) ) {
			return;
		}

$migrated = self::evolve_overview_columns(
			$saved,
			self::NEW_OVERVIEW_COLUMNS,
			self::RETIRED_OVERVIEW_COLUMNS,
			self::OVERVIEW_INSERT_AFTER
		);

if ( $migrated === $saved ) {
			return;
		}

update_user_meta( $user_id, Columns::COLUMNS_USER_META_NAME, $migrated );
	}

/**
	 * Pure helper: drop retired keys, then insert new keys after the anchor.
	 *
	 * Extracted as a static method so it is unit-testable without hitting WP
	 * options/usermeta or the DB. Idempotent: a saved list that already
	 * contains every new key and no retired keys passes through unchanged.
	 *
	 * @since 2.0.0
	 *
	 * @param array  $saved        User's saved column keys (current order).
	 * @param array  $new_keys     Keys to introduce.
	 * @param array  $retired_keys Keys to remove (if present).
	 * @param string $insert_after Anchor key; new keys inserted right after it (appended if anchor absent).
	 *
	 * @return array Migrated column keys.
	 */
	public static function evolve_overview_columns( array $saved, array $new_keys, array $retired_keys, string $insert_after ): array {

// Drop retired keys, preserving order for everything else.
		$result = array_values(
			array_filter(
				$saved,
				static function ( $key ) use ( $retired_keys ) {

return ! in_array( $key, $retired_keys, true );
				}
			)
		);

// Filter the new keys down to those genuinely missing (idempotency).
		$to_insert = array_values(
			array_filter(
				$new_keys,
				static function ( $key ) use ( $result ) {

return ! in_array( $key, $result, true );
				}
			)
		);

if ( empty( $to_insert ) ) {
			return $result;
		}

$anchor_pos = array_search( $insert_after, $result, true );
		$splice_at  = $anchor_pos !== false ? (int) $anchor_pos + 1 : count( $result );

array_splice( $result, $splice_at, 0, $to_insert );

return $result;
	}
}