Merge pull request #525 from wpengine/hwp-previews-uninstall-cleanup

chore(previews): Add uninstallation hook

Author: ahuseyn

.changeset/tall-wasps-bathe.md

@@ -0,0 +1,5 @@
+---
+"@wpengine/hwp-previews-wordpress-plugin": patch
+---
+
+Add optional data cleanup on uninstall via HWP_PREVIEWS_UNINSTALL_PLUGIN constant

docs/plugins/hwp-previews/index.md

@@ -17,6 +17,7 @@ This plugin bridges the preview gap in headless WordPress architectures, allowin
 * [Configuration](#configuration)
 * [Front-End Integration](#front-end-integration)
 * [Using With Faust.js](#using-with-faustjs)
+* [Uninstallation](#uninstallation)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
 
@@ -132,6 +133,18 @@ To implement previews from scratch, refer to your framework's documentation:
 
 HWP Previews automatically integrates with [Faust.js](https://faustjs.org/) when both plugins are active. See the [Integrate with Faust.js](how-to/integrate-with-faust/index.md) guide for details.
 
+## Uninstallation
+
+By default, HWP Previews preserves all settings when the plugin is deactivated to prevent accidental data loss.
+
+If you would like to remove all plugin settings and data, you must set the PHP constant before you uninstall the plugin:
+
+```php
+define( 'HWP_PREVIEWS_UNINSTALL_PLUGIN', true );
+```
+
+You can add this constant to your `wp-config.php` file if you want to enable automatic cleanup during uninstallation.
+
 ## Documentation
 
 ### How-to guides

plugins/hwp-previews/README.md

@@ -35,6 +35,7 @@
 - [Using With Faust.js](#using-with-faustjs)
 - [Extending the Functionality](#extending-the-functionality)
 - [Testing](#testing)
+- [Uninstallation](#uninstallation)
 
 ## Overview
 
@@ -171,6 +172,18 @@ See the [Actions & Filters documentation](ACTIONS_AND_FILTERS.md) for a comprehe
 
 See [Testing.md](TESTING.md) for details on how to test the plugin.
 
+## Uninstallation
+
+By default, HWP Previews preserves all settings when the plugin is deactivated to prevent accidental data loss.
+
+If you would like to remove all plugin settings and data, you must set the PHP constant before you uninstall the plugin:
+
+```php
+define( 'HWP_PREVIEWS_UNINSTALL_PLUGIN', true );
+```
+
+You can add this constant to your `wp-config.php` file if you want to enable automatic cleanup during uninstallation.
+
 ## Screenshots
 
 <details>

plugins/hwp-previews/tests/wpunit/Core/UninstallTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare( strict_types=1 );
+
+namespace HWP\Previews\Tests\Core;
+
+use lucatume\WPBrowser\TestCase\WPTestCase;
+
+/**
+ * Test class for the uninstall callback.
+ */
+class UninstallTest extends WPTestCase {
+
+	public function test_uninstall_file_exists(): void {
+		$uninstall_file = dirname( __DIR__, 3 ) . '/uninstall.php';
+		$this->assertFileExists( $uninstall_file, 'uninstall.php file should exist' );
+	}
+
+	public function test_option_can_be_deleted(): void {
+		// Test that delete_option works (simulating what uninstall.php does).
+		$option_key = HWP_PREVIEWS_SETTINGS_KEY;
+		$test_data  = [ 'test' => 'data' ];
+
+		update_option( $option_key, $test_data );
+		$this->assertEquals( $test_data, get_option( $option_key ) );
+
+		delete_option( $option_key );
+		$this->assertFalse( get_option( $option_key ) );
+	}
+
+	public function test_uninstall_action_hook_exists(): void {
+		// Verify the action hook can be registered.
+		$called = false;
+
+		add_action( 'hwp_previews_after_uninstall', function () use ( &$called ) {
+			$called = true;
+		} );
+
+		do_action( 'hwp_previews_after_uninstall' );
+
+		$this->assertTrue( $called, 'hwp_previews_after_uninstall action should fire' );
+	}
+}
+

plugins/hwp-previews/uninstall.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * Uninstall HWP Previews
+ *
+ * Deletes all plugin data when the plugin is uninstalled,
+ * only if HWP_PREVIEWS_UNINSTALL_PLUGIN constant is defined.
+ *
+ * @package HWP\Previews
+ */
+
+declare(strict_types=1);
+
+// If uninstall not called from WordPress, then exit.
+if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
+	exit;
+}
+
+// Only proceed if the uninstall constant is defined.
+if ( ! defined( 'HWP_PREVIEWS_UNINSTALL_PLUGIN' ) || ! HWP_PREVIEWS_UNINSTALL_PLUGIN ) {
+	return;
+}
+
+// Define constants if not already defined.
+if ( ! defined( 'HWP_PREVIEWS_SETTINGS_KEY' ) ) {
+	define( 'HWP_PREVIEWS_SETTINGS_KEY', 'hwp_previews_settings' );
+}
+
+// Delete plugin settings.
+delete_option( HWP_PREVIEWS_SETTINGS_KEY );
+
+// Fire action for extensibility.
+do_action( 'hwp_previews_after_uninstall' );
+