fix: prevent duplicate WP users on checkout retry (GH#903) (#911)

On checkout retry, the elseif guard at maybe_create_customer() returned
'email_exists' for ANY existing WP user with that email — including users
whose checkout had previously failed before the customer record was saved
(orphaned WP user). This blocked all retries for those users.

Changes:
1. inc/checkout/class-checkout.php — narrow the block to only fire when the
   existing WP user also has a customer record. When no customer record exists
   (orphaned/partial state), pass the existing user's ID to wu_create_customer()
   so it skips WP user creation and links the new customer to the existing user.

2. inc/functions/customer.php — sanitize the email before the get_user_by()
   duplicate check so both the check and the subsequent wpmu_create_user() call
   operate on the same normalized value, preventing format-based mismatches.

3. tests/WP_Ultimo/Functions/Customer_Functions_Test.php — two new tests:
   - test_create_customer_reuses_existing_wp_user_on_retry: confirms that
     wu_create_customer() reuses the pre-existing WP user and creates exactly
     one wp_users row for a given email.
   - test_create_customer_prevents_duplicate_customer_for_same_user: confirms
     that a second wu_create_customer() call for the same user_id does not
     create a second customer row.

Fixes #903

Author: superdav42

inc/checkout/class-checkout.php

@@ -1096,8 +1096,23 @@ protected function maybe_create_customer() {
 					'email'              => wp_get_current_user()->user_email,
 					'email_verification' => 'verified',
 				];
-			} elseif (isset($customer_data['email']) && get_user_by('email', $customer_data['email'])) {
-				return new \WP_Error('email_exists', __('The email address you entered is already in use.', 'ultimate-multisite'));
+			} elseif (isset($customer_data['email']) && ($existing_wp_user = get_user_by('email', $customer_data['email']))) {
+				/*
+				 * A WP user already exists with this email.
+				 *
+				 * Only block checkout when a customer record also exists for
+				 * that user — the email is genuinely in use. If no customer
+				 * exists yet, the previous checkout attempt created the WP
+				 * user but failed before saving the customer (partial /
+				 * orphaned state). Allow the retry to proceed by passing the
+				 * existing user's ID to wu_create_customer(), which will skip
+				 * WP user creation and link the new customer to it instead.
+				 */
+				if (wu_get_customer_by_user_id($existing_wp_user->ID)) {
+					return new \WP_Error('email_exists', __('The email address you entered is already in use.', 'ultimate-multisite'));
+				}
+
+				$customer_data['user_id'] = $existing_wp_user->ID;
 			}
 
 			/*

inc/functions/customer.php

@@ -142,6 +142,17 @@ function wu_create_customer($customer_data) {
 		]
 	);
 
+	/*
+	 * Sanitize the email early so the duplicate check and the
+	 * subsequent wpmu_create_user() / register_new_user() call both
+	 * operate on the same normalized value. Without this, subtle
+	 * format differences (e.g. trailing whitespace) can cause
+	 * get_user_by() to miss an existing user and create a duplicate.
+	 */
+	if ($customer_data['email']) {
+		$customer_data['email'] = sanitize_email($customer_data['email']);
+	}
+
 	$user = get_user_by('email', $customer_data['email']);
 
 	if ( ! $user) {

tests/WP_Ultimo/Functions/Customer_Functions_Test.php

@@ -248,4 +248,79 @@ public function test_get_customer_gateway_id_no_memberships(): void {
 
 		$this->assertEquals('', $result);
 	}
+
+	/**
+	 * Test wu_create_customer reuses existing WP user instead of creating a duplicate.
+	 *
+	 * Scenario: a previous checkout attempt created a WP user but failed before
+	 * saving the customer record (orphaned user). On retry, wu_create_customer()
+	 * must reuse the existing user rather than calling wpmu_create_user() again.
+	 */
+	public function test_create_customer_reuses_existing_wp_user_on_retry(): void {
+
+		$email   = 'retry-test-' . uniqid() . '@example.com';
+		$user_id = self::factory()->user->create(['user_email' => $email]);
+
+		// Confirm no customer exists for this user yet (simulates orphaned state).
+		$this->assertFalse(wu_get_customer_by_user_id($user_id));
+
+		// Now call wu_create_customer() with the same email.
+		$customer = wu_create_customer([
+			'email'           => $email,
+			'username'        => 'retryuser',
+			'password'        => 'Str0ngP@ss!',
+			'skip_validation' => true,
+		]);
+
+		$this->assertNotWPError($customer);
+		$this->assertInstanceOf(\WP_Ultimo\Models\Customer::class, $customer);
+
+		// The customer must be linked to the pre-existing WP user, not a new one.
+		$this->assertSame($user_id, $customer->get_user_id());
+
+		// Confirm only one WP user exists with this email.
+		$users_with_email = get_users(['search' => $email, 'search_columns' => ['user_email']]);
+		$this->assertCount(1, $users_with_email);
+	}
+
+	/**
+	 * Test wu_create_customer returns WP_Error when email belongs to a user
+	 * who already has a customer record (genuine email-in-use case).
+	 *
+	 * This is tested at the checkout layer (maybe_create_customer), but we also
+	 * verify wu_create_customer itself does not create a duplicate customer row.
+	 */
+	public function test_create_customer_prevents_duplicate_customer_for_same_user(): void {
+
+		$user_id = self::factory()->user->create();
+
+		// First customer creation for this user must succeed.
+		$first = wu_create_customer([
+			'user_id'         => $user_id,
+			'skip_validation' => true,
+		]);
+
+		$this->assertNotWPError($first);
+		$this->assertInstanceOf(\WP_Ultimo\Models\Customer::class, $first);
+
+		// A second call for the same user_id must not create a second customer row.
+		wu_create_customer([
+			'user_id'         => $user_id,
+			'skip_validation' => true,
+		]);
+
+		// wu_create_customer reuses the existing user; save() may return an error
+		// for the duplicate or the existing customer object — either is acceptable.
+		// What must NOT happen is a second customer row being saved.
+
+		// There should still be exactly one customer linked to this user.
+		$customers_for_user = array_filter(
+			wu_get_customers(),
+			function ($c) use ($user_id) {
+				return (int) $c->get_user_id() === (int) $user_id;
+			}
+		);
+
+		$this->assertCount(1, $customers_for_user);
+	}
 }