fix: make the manual retry actually retry the migration

With the overwrite guard in place, "Retry migration" did nothing whenever
settings were already stored: the step skipped its work, the migration counted
as succeeded and the notice disappeared, which is indistinguishable from
"Keep the current settings" and not what the button promised.

A retry the user asked for now clears `antispam_bee_options` first, so the
legacy settings are migrated again for real. The guard keeps protecting the
automatic retries, which must never discard a configuration nobody asked them
to touch.

The notice wording follows the state it is describing: with settings stored the
action reads "Discard the current settings and migrate again" and says what it
replaces, and the introduction no longer claims the plugin runs on its defaults
when it does not.

Author: 2ndkauboy

src/Admin/MigrationFailureNotice.php

@@ -67,10 +67,13 @@ public static function render(): void {
 			esc_html__( 'Antispam Bee could not migrate your settings.', 'antispam-bee' )
 		);
 
-		printf(
-			'<p>%s</p>',
-			esc_html__( 'The plugin is currently running with its default settings. Your previous settings have not been lost — they are still stored in the database and will be applied as soon as the migration succeeds.', 'antispam-bee' )
-		);
+		if ( PluginUpdate::has_stored_settings() ) {
+			$intro = __( 'The plugin is running with the settings currently stored. Your previous settings have not been lost — they are still in the database, unmigrated.', 'antispam-bee' );
+		} else {
+			$intro = __( 'The plugin is currently running with its default settings. Your previous settings have not been lost — they are still stored in the database and will be applied as soon as the migration succeeds.', 'antispam-bee' );
+		}
+
+		printf( '<p>%s</p>', esc_html( $intro ) );
 
 		if ( '' !== $state['message'] ) {
 			printf(
@@ -79,17 +82,32 @@ public static function render(): void {
 			);
 		}
 
+		/*
+		 * The wording has to follow what the button actually does. Once settings are
+		 * stored — because the user gave up and configured the plugin by hand — a retry
+		 * can only get the old settings back by replacing them, and saying "retry" while
+		 * quietly leaving them in place would be a lie: the migration would skip its work
+		 * and simply report success.
+		 */
+		if ( PluginUpdate::has_stored_settings() ) {
+			$retry_label = __( 'Discard the current settings and migrate again', 'antispam-bee' );
+			$explanation = __( 'Migrating again replaces the settings currently stored with the result of migrating your previous ones. Choose “Keep the current settings” to stop retrying and leave your settings exactly as they are.', 'antispam-bee' );
+		} else {
+			$retry_label = __( 'Migrate again', 'antispam-bee' );
+			$explanation = __( 'Choose “Keep the current settings” to stop retrying for good and configure the plugin yourself.', 'antispam-bee' );
+		}
+
 		printf(
 			'<p><a class="button button-primary" href="%s">%s</a> <a class="button" href="%s">%s</a></p>',
 			esc_url( $retry_url ),
-			esc_html__( 'Retry migration', 'antispam-bee' ),
+			esc_html( $retry_label ),
 			esc_url( $dismiss_url ),
 			esc_html__( 'Keep the current settings', 'antispam-bee' )
 		);
 
 		printf(
 			'<p class="description">%s</p>',
-			esc_html__( 'Retrying never overwrites settings you have already saved. Choose “Keep the current settings” to stop retrying for good and configure the plugin yourself.', 'antispam-bee' )
+			esc_html( $explanation )
 		);
 
 		echo '</div>';
@@ -104,7 +122,7 @@ public static function render(): void {
 	public static function handle_retry(): void {
 		self::authorize( self::RETRY_ACTION );
 
-		delete_option( PluginUpdate::FAILURE_OPTION_NAME );
+		PluginUpdate::reset_for_retry();
 
 		self::redirect_back();
 	}

src/Handlers/PluginUpdate.php

@@ -184,6 +184,31 @@ private static function maybe_update_database(): void {
 		update_option( self::DB_VERSION_OPTION_NAME, self::get_plugin_version() );
 	}
 
+	/**
+	 * Whether the plugin already has settings of its own stored.
+	 *
+	 * @return bool Whether `antispam_bee_options` holds a configuration.
+	 */
+	public static function has_stored_settings(): bool {
+		$stored = get_option( Settings::OPTION_NAME, null );
+
+		return is_array( $stored ) && ! empty( $stored );
+	}
+
+	/**
+	 * Throw away the stored settings so the next run migrates the legacy ones again.
+	 *
+	 * The automatic retries deliberately never touch a stored configuration — see the
+	 * guard in the 3.0.0 step. A retry the user asked for is the opposite situation:
+	 * they are looking at a notice that says their old settings were not migrated and
+	 * are choosing to have them back, so the settings standing in the way have to go,
+	 * or the retry would silently do nothing at all.
+	 */
+	public static function reset_for_retry(): void {
+		delete_option( Settings::OPTION_NAME );
+		delete_option( self::FAILURE_OPTION_NAME );
+	}
+
 	/**
 	 * Record the database as migrated without running the migration.
 	 *
@@ -299,10 +324,10 @@ protected static function run_migration_steps( string $version_from_db ): void {
 			 * over either would throw away their configuration. The write below is the step's
 			 * last action, so a run cut short left nothing behind and a present array is always
 			 * one of those two. A stored value that is not an array is corrupt, not a
-			 * configuration, and is replaced.
+			 * configuration, and is replaced. A retry the user explicitly asked for clears
+			 * the option first, so this guard only ever holds back the automatic retries.
 			 */
-			$existing_options = get_option( Settings::OPTION_NAME, null );
-			if ( is_array( $existing_options ) && ! empty( $existing_options ) ) {
+			if ( self::has_stored_settings() ) {
 				return;
 			}
 

tests/Unit/Handlers/PluginUpdateTest.php

@@ -438,6 +438,44 @@ public function test_existing_options_are_not_overwritten(): void {
 		);
 	}
 
+	/**
+	 * A retry the user asked for clears the stored settings, so the migration really runs.
+	 *
+	 * Without this the guard that protects the automatic retries would make the manual one
+	 * skip its work and report success, which is the opposite of what the button promises.
+	 *
+	 * @return void
+	 */
+	public function test_resetting_for_a_retry_clears_the_stored_settings(): void {
+		$this->stub_options(
+			[
+				'antispam_bee'                   => [ 'regexp_check' => 1 ],
+				'antispam_bee_options'           => [ 'comment' => [ 'rule_asb_regexp_active' => '' ] ],
+				'antispambee_db_version'         => '1.02',
+				'antispambee_db_update_failures' => [
+					'version'  => '3.0.0-beta.1',
+					'attempts' => PluginUpdate::MAX_UPDATE_ATTEMPTS,
+					'message'  => 'Migration exploded',
+					'time'     => 1,
+				],
+			]
+		);
+
+		PluginUpdate::reset_for_retry();
+
+		$this->assertContains( Settings::OPTION_NAME, $this->deleted_options );
+		$this->assertContains( PluginUpdate::FAILURE_OPTION_NAME, $this->deleted_options );
+
+		PluginUpdate::maybe_run_plugin_updated_logic();
+
+		$this->assertSame(
+			'on',
+			$this->written_options[ Settings::OPTION_NAME ]['comment']['rule_asb_regexp_active'],
+			'The legacy settings are migrated again instead of being skipped.'
+		);
+		$this->assertSame( '3.0.0-beta.1', $this->written_options[ PluginUpdate::DB_VERSION_OPTION_NAME ] );
+	}
+
 	/**
 	 * Marking the database as migrated stops the retries without touching the settings.
 	 *