Feature Request
Per our conversation here in 137, I would like to humbly ask about adding search-replace-file as an official WP-CLI command for performing PHP serialization-aware search and replace operations against Wordpress SQL dump files.
The implementation is available here:
https://github.com/AlextheYounga/search-replace-file-command
The basic usage is:
wp search-replace-file <old> <new> <input-file> <output-file>
Example:
wp search-replace-file example.com example.test dump.sql dump-updated.sql
As we discussed previously, this is intentionally a separate top-level command rather than a subcommand of wp search-replace, since wp search-replace already treats its first positional argument as the search value.
Background
This work originally came up in the discussion around search-replace-command#137, where another WordPress developer suggested reviewing and incorporating my PHP port of Automattic’s go-search-replace utility, which can be found here: php-search-replace.
I initially attempted to add the functionality to wp search-replace, but this was haphazardly, and after discussing it in PR #235, @swissspidy recommended turning it into a proper standalone WP-CLI command and then opening a separate discussion about whether it should become official.
Why this is useful
Automattic already maintains go-search-replace for this purpose. It can transform large SQL dump files while recalculating PHP serialized string lengths correctly.
The go-search-replace tool works perfectly fine, but WordPress developers generally work in PHP and already have WP-CLI installed. Requiring them to separately install and maintain a Go binary to perform a WordPress-specific database migration task adds unnecessary friction. This was a problem I faced, (I know very little about Go) and I have heard others mention as well when discussing Wordpress friction. I think this would be highly useful alongside the wp search-replace command.
A native WP-CLI command would make this workflow available anywhere WP-CLI already runs:
- Processing a database dump before importing it into another environment.
- Updating domains during migrations without modifying the source database.
- Preparing dumps in deployment or CI pipelines.
- Working with database exports when the original WordPress installation is unavailable.
- Performing replacements without loading the entire dump into memory.
It complements wp search-replace.. The existing command remains the right tool for modifying a live database (and I use it all the time). wp search-replace-file is for offline SQL dump transformation.
Implementation status
The command has been implemented as a standalone WP-CLI package using the structure and tooling of the official WP-CLI command repositories, using search-replace as a guide.
It currently includes:
- Literal, case-sensitive replacement.
- Serialization-aware PHP string-length recalculation.
- Support for
mysqldump- and mydumper-style escaping.
- Exact validation of declared serialized byte lengths.
- Correct handling of MySQL escapes including
\0, \Z, and unknown escape sequences.
- Rejection of malformed serialized data rather than silently producing questionable output.
- Protection against using the same file through relative paths, symlinks, or hard links.
- Refusal to overwrite existing output unless
--force is supplied.
- Temporary-file processing and atomic replacement of the destination.
- Detection of partial and failed writes.
- Preservation of existing output when parsing or writing fails.
- Unit and WP-CLI functional test coverage across supported PHP versions.
It also copies all test cases from the original go-search-replace implementation, ported to PHP.
I also found several edge cases inherited from the original Go algorithm. These included a serialized-length boundary condition and incorrect byte counting for MySQL’s \Z escape. Those cases are now covered by focused regression tests and corrected in this implementation. These were spotted by AI (GPT 5.6), and although I was skeptical, initial testing seems to prove GPT was correct here. I also found there was an almost identical PR up for the issue already, with a similar solution to the one we implemented in our code.
Proposal
Would the WP-CLI team be open to adopting this as an official WP-CLI package, or otherwise bringing it under the WP-CLI organization?
I am happy to adjust the command name, public interface, repository structure, documentation, or implementation details to match the project’s conventions. I can also transfer the existing repository or recreate the work in a repository provided by the WP-CLI organization, depending on the preferred contribution process, ideally in such a way that I may maintain credit for the contribution, of course. (It's a tough market out there, and being able to say that my code is used by potentially millions across the world is its own form of payment.)
I understand that becoming an official command and becoming bundled with WP-CLI may be separate decisions. My immediate request is to determine whether the team considers this functionality appropriate for an official WP-CLI package and, if so, what the preferred next step would be.
Feature Request
Per our conversation here in 137, I would like to humbly ask about adding
search-replace-fileas an official WP-CLI command for performing PHP serialization-aware search and replace operations against Wordpress SQL dump files.The implementation is available here:
https://github.com/AlextheYounga/search-replace-file-command
The basic usage is:
Example:
As we discussed previously, this is intentionally a separate top-level command rather than a subcommand of
wp search-replace, sincewp search-replacealready treats its first positional argument as the search value.Background
This work originally came up in the discussion around search-replace-command#137, where another WordPress developer suggested reviewing and incorporating my PHP port of Automattic’s go-search-replace utility, which can be found here: php-search-replace.
I initially attempted to add the functionality to
wp search-replace, but this was haphazardly, and after discussing it in PR #235, @swissspidy recommended turning it into a proper standalone WP-CLI command and then opening a separate discussion about whether it should become official.Why this is useful
Automattic already maintains
go-search-replacefor this purpose. It can transform large SQL dump files while recalculating PHP serialized string lengths correctly.The go-search-replace tool works perfectly fine, but WordPress developers generally work in PHP and already have WP-CLI installed. Requiring them to separately install and maintain a Go binary to perform a WordPress-specific database migration task adds unnecessary friction. This was a problem I faced, (I know very little about Go) and I have heard others mention as well when discussing Wordpress friction. I think this would be highly useful alongside the
wp search-replacecommand.A native WP-CLI command would make this workflow available anywhere WP-CLI already runs:
It complements
wp search-replace.. The existing command remains the right tool for modifying a live database (and I use it all the time).wp search-replace-fileis for offline SQL dump transformation.Implementation status
The command has been implemented as a standalone WP-CLI package using the structure and tooling of the official WP-CLI command repositories, using search-replace as a guide.
It currently includes:
mysqldump- andmydumper-style escaping.\0,\Z, and unknown escape sequences.--forceis supplied.It also copies all test cases from the original go-search-replace implementation, ported to PHP.
I also found several edge cases inherited from the original Go algorithm. These included a serialized-length boundary condition and incorrect byte counting for MySQL’s
\Zescape. Those cases are now covered by focused regression tests and corrected in this implementation. These were spotted by AI (GPT 5.6), and although I was skeptical, initial testing seems to prove GPT was correct here. I also found there was an almost identical PR up for the issue already, with a similar solution to the one we implemented in our code.Proposal
Would the WP-CLI team be open to adopting this as an official WP-CLI package, or otherwise bringing it under the WP-CLI organization?
I am happy to adjust the command name, public interface, repository structure, documentation, or implementation details to match the project’s conventions. I can also transfer the existing repository or recreate the work in a repository provided by the WP-CLI organization, depending on the preferred contribution process, ideally in such a way that I may maintain credit for the contribution, of course. (It's a tough market out there, and being able to say that my code is used by potentially millions across the world is its own form of payment.)
I understand that becoming an official command and becoming bundled with WP-CLI may be separate decisions. My immediate request is to determine whether the team considers this functionality appropriate for an official WP-CLI package and, if so, what the preferred next step would be.