Search & Replace

Search and replace across posts, meta and options.

kitloom/search-replace · admins: kitloom/search-replace-filament, kitloom/search-replace-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

Search & Replace

Search and replace across the site's tables, as Better Search Replace does it on WordPress: moving a site to another address, renaming a brand, fixing a link everywhere.

The admin is kitloom/search-replace-filament or kitloom/search-replace-nova (its own Search & Replace section).

A run

Pairs: "search for → replace with", applied in turn.
Tables: the declared ones the run is asked for; in each, every text column but the key.
Case-insensitive, off by default.
Replace GUIDs, off by default: a post's guid is its identity for feed readers, and WordPress says leave it.
Dry run, on by default: the report shows what would change and nothing is written; the same search then runs for real.

Serialized values are changed without unserializing them: strings get their new lengths, keys and property names stay, and objects of classes the application does not have survive. A serialized string inside a serialized value is walked too. % and _ in a search are characters, not a pattern.

The report: per table the rows and cells changed, the replacements made, and the first changes with their values before and after.

php

use Kitloom\SearchReplace\RunOptions;
use Kitloom\SearchReplace\SearchReplace;

$report = app(SearchReplace::class)->run(new RunOptions(
    [['search' => 'https://old.example', 'replace' => 'https://new.example']],
    ['posts', 'postmeta', 'options'],
    dryRun: false,
));

bash

php artisan search-replace https://old.example https://new.example            # a dry run
php artisan search-replace https://old.example https://new.example --run      # for real

Runs from the admin are kept in search_replace_runs with who ran them and the report, and performed on the queue when the application has one.

Revisions

Revisions are left alone: they are what the records were. A run for real first keeps each record it rewrites as it is, as a revision of a type that keeps them (kitloom/wp-schema's Revisions::baseline()), and the save after the run keeps the new one — so a run can be taken back record by record.

Tables

kitloom-search-replace.tables declares them by their models in the registry — the table and its prefix are the application's: posts, post meta, comments and their meta, terms, term taxonomy and meta, options, user meta. columns lists the columns instead of every text one, exclude leaves some out, false takes a table away. A module adds its own tables in its provider. Tables nobody declared — the application's users, sessions, jobs — are never touched.

AI agents

With kitloom/ai installed, an agent whose user has manage_search_replace counts a change first (search_replace_dry_run — the pairs, the tables, every allowed one by default; nothing is written, so a read-only key has it too), then makes exactly the change it counted (search_replace_run with the dry run's id — only a finished dry run that found something), and reads the history with each run's report (search_replace_runs). There is no undo but a run the other way, so the agent is told to show the dry run's report first. An agent searches the content tables only — posts, comments, terms and their meta: options and user meta hold what kitloom/ai keeps from agents (the locked settings, secrets, roles, second factors), so a search there would show it and a run would rewrite it. Those, and a module's own tables, are searched from the admin; a run an admin made over them shows an agent only its status, and an agent does not run it again. kitloom-search-replace.ai.register false — no search and replace tools.