fix(settings): add one-click internal state reset tool

[faisalahammad]

Summary

Add a one-click troubleshooting action in Imagify settings to reset stale internal optimization state without deleting user settings. This addresses recurring stuck optimization states caused by leftover transients, queue locks, and pending async jobs.

Fixes #1012

Problem

Users can hit persistent stuck optimization states (endless loading, stalled percentages, false quota-like state) even when server conditions are healthy. Current recovery is often plugin deactivate/reactivate or reinstall, which is disruptive.

Solution

Introduce a dedicated admin-post reset action and settings UI entry point that clears runtime state only: Imagify transients, stale background-process batches/locks, and pending Imagify Action Scheduler jobs. The reset is capability- and nonce-protected and keeps plugin settings intact.

Changes

inc/classes/class-imagify-admin-ajax-post.php

Before:

protected $post_only_actions = [
	'imagify_scan_custom_folders',
	'imagify_dismiss_ad',
];

After:

protected $post_only_actions = [
	'imagify_scan_custom_folders',
	'imagify_reset_internal_state',
	'imagify_dismiss_ad',
];

public function imagify_reset_internal_state_callback() {
	if ( ! imagify_get_context( 'wp' )->current_user_can( 'manage' ) ) {
		imagify_die();
		return;
	}

	imagify_check_nonce( 'imagify-reset-internal-state' );
	$result = imagify_reset_internal_state();
	imagify_maybe_redirect( is_wp_error( $result ) ? $result : __( 'Imagify internal state has been reset.', 'imagify' ) );
}

Why this works:
It provides a secure, explicit endpoint for the reset flow in wp-admin. Capability and nonce checks prevent unauthorized state resets, and existing redirect/notice plumbing provides immediate operator feedback.

inc/functions/admin.php

Before:

function imagify_maybe_redirect( $message = false, $args_or_url = [] ) {
	// redirect helper only
}

After:

function imagify_reset_internal_state() {
	// clear key Imagify transients/site transients
	// delete wildcard transient rows from options/sitemeta
	// delete imagify_optimize_media_batch_* and status rows
	// unschedule imagify_optimize_media / imagify_convert_next_gen actions
	// clear related cron hooks
}

Why this works:
It centralizes runtime-state cleanup into one deterministic routine while preserving user configuration. It also targets both transient APIs and DB-level leftovers (batch/status keys), covering the failure modes seen in stuck-state support cases.

Settings UI

Before:

// no explicit troubleshooting reset entry point on settings page

After:

<?php $this->print_template( 'part-settings-troubleshooting' ); ?>

views/part-settings-troubleshooting.php adds a nonce-protected button:

$reset_url = wp_nonce_url(
	self_admin_url( 'admin-post.php?action=imagify_reset_internal_state' ),
	'imagify-reset-internal-state'
);

Why this works:
It makes recovery available in a predictable place for admins without requiring reinstall/deactivation workflows.

Testing

Manual Testing

Test Case 1: UI visibility and action trigger

• Steps:

1. Open Imagify settings.
2. Locate the new Troubleshooting section.
3. Click “Reset internal state”.

• Result: Redirects back with success notice and no fatal errors.

Test Case 2: Settings preservation

• Steps:

1. Note current Imagify settings values.
2. Run reset action.
3. Re-open settings and compare values.

• Result: Settings remain unchanged.

Test Case 3: Post-reset behavior

• Steps:

1. Trigger optimization/bulk flow after reset.
2. Verify processing starts normally.

• Result: Flow proceeds as expected.

Automated Tests

$ vendor/bin/phpcs inc/classes/class-imagify-admin-ajax-post.php inc/functions/admin.php views/page-settings.php views/part-settings-troubleshooting.php
.... 4 / 4 (100%)

$ composer test-unit
OK, but incomplete, skipped, or risky tests!
Tests: 24, Assertions: 59, Risky: 5.

Build Artifact

For manual verification, I built an installable package:
imagify-fix-issue-1012-reset-internal-state.zip

Installation: WordPress Admin > Plugins > Add New > Upload Plugin

Screenshot