Merge pull request #1036 from 10up/feature/deprecate-legacy-settings

Added Admin Notice for Legacy Settings Deprecation

Author: dkotter

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file, per [the Ke
 
 ## [Unreleased] - TBD
 
+### Deprecated
+
+- The legacy settings screen (enabled via the `classifai_use_legacy_settings_panel` filter) is now formally deprecated and scheduled for removal in a future release. An admin notice will be displayed when this filter is active. Please migrate to the new React-based settings experience (props [@zamanq](https://github.com/zamanq), [@jeffpaul](https://github.com/jeffpaul) via [#1036](https://github.com/10up/classifai/pull/1036)).
+
 ## [3.7.1] - 2026-01-12
 
 **Note that this release bumps the WordPress minimum from 6.7 to 6.8.**

includes/Classifai/Admin/Notifications.php

@@ -50,6 +50,7 @@ public function maybe_render_notices() {
 		$this->thresholds_update_notice();
 		$this->v3_migration_completed_notice();
 		$this->render_embeddings_notice();
+		$this->render_legacy_settings_deprecation_notice();
 		$this->render_notices();
 	}
 
@@ -277,6 +278,46 @@ public function render_embeddings_notice() {
 		<?php
 	}
 
+	/**
+	 * Render a deprecation notice when the legacy settings filter is active.
+	 *
+	 * @since x.x.x
+	 */
+	public function render_legacy_settings_deprecation_notice() {
+		// Only show if the legacy settings filter is active.
+		if ( ! should_use_legacy_settings_panel() ) {
+			return;
+		}
+
+		$key = 'legacy_settings_deprecation';
+
+		// Don't show the notice if the user has already dismissed it.
+		if ( get_user_meta( get_current_user_id(), "classifai_dismissed_{$key}", true ) ) {
+			return;
+		}
+		?>
+
+		<div class="notice notice-warning is-dismissible classifai-dismissible-notice" data-notice="<?php echo esc_attr( $key ); ?>">
+			<p>
+				<strong><?php esc_html_e( 'ClassifAI Legacy Settings Deprecation Notice', 'classifai' ); ?></strong>
+			</p>
+			<p>
+				<?php
+				echo wp_kses_post(
+					sprintf(
+						/* translators: %1$s: filter name, %2$s: documentation URL */
+						__( 'The legacy settings screen is deprecated and will be removed in a future release. You are currently using the <code>%1$s</code> filter to enable it. Please migrate to the new React-based settings experience and remove this filter from your code. <a href="%2$s" target="_blank" rel="noopener noreferrer">Learn more about the new settings</a>.', 'classifai' ),
+						'classifai_use_legacy_settings_panel',
+						'https://10up.github.io/classifai/advanced-docs/useful-snippets#use-legacy-settings'
+					)
+				);
+				?>
+			</p>
+		</div>
+
+		<?php
+	}
+
 	/**
 	 * Print out a script to dismiss a notice.
 	 *

readme.txt

@@ -60,6 +60,9 @@ Please report security bugs found in the source code of the undefined plugin thr
 
 == Upgrade Notice ==
 
+= x.x.x =
+**Note that the legacy settings screen (enabled via the `classifai_use_legacy_settings_panel` filter) is now formally deprecated and scheduled for removal in a future release. Please migrate to the new React-based settings experience.**
+
 = 3.3.0 =
 **Note that this release bumps the WordPress minimum from 6.5 to 6.6.**
 

wp-hooks-docs/docs/03.advanced-docs/01.useful-snippets.md

@@ -536,13 +536,19 @@ function my_feature_enqueue_admin_assets( $hook_suffix ) {
 add_action( 'admin_enqueue_scripts', 'my_feature_enqueue_admin_assets' );
 ```
 
-## Use Legacy settings
-ClassifAI 3.2.0 introduces React-based settings and deprecates the PHP-based settings pages. If you have customizations in the legacy settings and would like to continue using the legacy settings panel, you can enable this by using the `classifai_use_legacy_settings_panel` filter hook.
+## Use Legacy settings (Deprecated)
 
-However, please note that legacy settings will be completely removed in future releases. We recommend updating your customizations to use the React-based settings panel. If you encounter any issues, feel free to report them on our [GitHub repository](https://github.com/10up/classifai/).
+:::warning Deprecation Notice
+**The legacy settings screen is deprecated and scheduled for removal.** The `classifai_use_legacy_settings_panel` filter will be removed in an upcoming release, followed by the complete removal of all legacy settings code. Please migrate to the new React-based settings experience as soon as possible.
+:::
 
-Add the following snippet to your theme's `functions.php` file or a custom plugin.
+ClassifAI 3.2.0 introduced React-based settings and deprecated the PHP-based settings pages. If you have customizations in the legacy settings and are still using the legacy settings panel via the `classifai_use_legacy_settings_panel` filter hook, you should plan to migrate immediately.
+
+**Important:** New features and providers added since version 3.2.0 are only available in the new settings experience. The legacy screen is effectively dead code and no longer receives updates.
+
+If you encounter any issues migrating to the new settings, please report them on our [GitHub repository](https://github.com/10up/classifai/).
 
 ```php
+// DEPRECATED: This filter will be removed in a future release.
 add_filter( 'classifai_use_legacy_settings_panel', '__return_true' );
 ```