=== Geared URL Replacer ===
Tags: search replace, database, migration, url, maintenance
Requires at least: 6.8
Tested up to: 7.0
Stable tag: 1.0.2
Requires PHP: 8.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Preview and safely replace complete stored URLs that match a partial URL rule.

== Description ==

Geared URL Replacer gives administrators a review-first workflow for changing stored URLs without running direct SQL replacements.

Create a match rule, choose a replacement and scope, then run the mandatory dry run. The report shows proposed changes before the Apply step becomes available.

= Safety-focused workflow =

* Matches complete URL values rather than arbitrary text fragments.
* Supports contains, starts with, ends with, exact URL, domain, and path rules.
* Filters internal, external, absolute, or relative URLs.
* Previews every supported change in a resumable dry run.
* Preserves HTML, block markup, JSON, and serialized PHP structures.
* Excludes protected fields such as GUIDs, credentials, sessions, caches, and plugin-owned data.
* Creates a protected rollback snapshot before each verified write.
* Restores only fields that still match the value written by the plugin, so later edits are preserved.
* Uses bounded, resumable batches for scanning, applying, and rolling back.

= Supported locations =

Default and optional scopes include posts, pages, public custom post types, post metadata, navigation menus, widgets, ordinary options, terms, comments, users, revisions, and explicitly selected safe custom tables.

= Important backup notice =

Rollback snapshots are recovery evidence for this plugin's changes. They are not a complete database backup. Create and verify an independent database backup before applying replacements or starting a rollback.

= Accessibility =

The administrator interface follows WordPress admin patterns, supports keyboard navigation, provides visible focus, associates labels with controls, and announces changing progress and status messages.

== Installation ==

1. Upload the `geared-url-replacer` folder to `/wp-content/plugins/`, or install the ZIP from Plugins > Add New.
2. Activate Geared URL Replacer.
3. Open Tools > Geared URL Replacer.
4. Create and verify an independent database backup.
5. Build a rule, select the scope, and complete the mandatory dry run.
6. Review the report before confirming Apply.

Network activation is intentionally blocked. On multisite, activate the plugin separately on each site where it is needed.

== Frequently Asked Questions ==

= Does a dry run change my content? =

No. A dry run reads eligible fields and stores a protected report in the plugin's own tables. It does not write to source content.

= Does the plugin replace arbitrary text? =

No. It conservatively identifies complete URL values. Ambiguous plain text and malformed structures are skipped or reported instead of being changed.

= Can I undo a replacement? =

The plugin stores a protected snapshot before each verified write. Rollback restores a field only when its current value still exactly matches the value written by the replacement. Later edits are left untouched and reported.

= Is rollback a substitute for a database backup? =

No. Always create and verify an independent database backup before applying or rolling back changes.

= Does the plugin send site data to an external service? =

No. Processing occurs on the WordPress site. The plugin does not call a remote service, load remote assets, track usage, or add advertising.

= Which users can run replacements? =

Only administrators with the `manage_options` capability can access the workflow and its protected reports.

= Why was a field skipped? =

The field may be protected, unsupported, malformed, changed after the dry run, or no longer match the reviewed proposal. The report records a privacy-safe reason.

= What happens when I uninstall the plugin? =

Protected job, report, and rollback data is preserved by default. To remove it during uninstall, enable destructive uninstall in Settings before deleting the plugin. This choice is irreversible.

== Screenshots ==

1. The dashboard summarizes the protected workflow and retained rollback storage.
2. The five-step wizard begins with a complete-URL match rule and generated examples.
3. The mandatory dry-run report lists proposed changes and safety outcomes before Apply unlocks.
4. Apply requires review, change, and independent-backup confirmations.
5. Rollback restores only eligible values while preserving later edits.
6. Settings control rollback retention, cleanup, and optional destructive uninstall.

== Privacy ==

Geared URL Replacer processes site content locally and does not send content, URLs, reports, telemetry, or personal data to an external service.

Dry-run reports and rollback snapshots can contain excerpts or original stored values. They are kept in protected plugin-owned database tables and are available only to administrators. Ordinary logs redact sensitive values.

By default, rollback snapshots are retained for seven days and plugin data is preserved during uninstall. Administrators can choose one-day, seven-day, thirty-day, or manual retention; run cleanup; delete snapshots; delete completed job history; and explicitly opt into destructive uninstall.

== Support ==

Use the WordPress.org support forum for setup questions and reproducible defects after the plugin is published. Include the WordPress, PHP, and plugin versions plus the visible error code.

Do not post private URLs, credentials, nonces, cookies, database exports, protected report contents, or rollback snapshots in a public support topic. Report suspected security issues privately to the plugin owner.

== Changelog ==

= 1.0.2 =

* Renamed the plugin to Geared URL Replacer for the WordPress.org submission.
* Updated the public slug, text domain, namespaces, runtime prefixes, and listing assets.

= 1.0.1 =

* Initial public release.
* Added complete-URL matching, structure-preserving transformation, mandatory dry-run reporting, guarded replacement, and hash-protected rollback.
* Added resumable batches, protected-field exclusions, privacy-safe exports, retention controls, and multisite per-site activation.
* Added distinctive author-prefixed namespaces, constants, options, hooks, database tables, REST identifiers, and browser assets.

== Upgrade Notice ==

= 1.0.2 =

Renamed the plugin to Geared URL Replacer and updated the submission package. Create an independent database backup before applying replacements.
