From 82c92853152457b1133fba44b0e88cb4a4dfb1c3 Mon Sep 17 00:00:00 2001
From: Alex Younger <thealexyounger@proton.me>
Date: Sat, 9 May 2026 20:16:51 -0500
Subject: [PATCH 1/2] test: add tests for new file search replace command

This change migrates tests from the php-search-replace repository
for testing various file edge-cases. Using actual sql files proved
a necessary step that prevents running into oddities with how php
handles strings. There may be a better way around that problem, but
I never found it, and it seems a better test to use actual sql files
since that is the exact behavior of the command.
---
 tests/FileSearchReplacerTest.php              | 327 ++++++++++++++++++
 .../serialized/different-lengths.expected.sql |   1 +
 .../serialized/different-lengths.input.sql    |   1 +
 .../serialized/double-encoded.expected.sql    |   1 +
 .../serialized/double-encoded.input.sql       |   1 +
 .../serialized/emoji-from.expected.sql        |   1 +
 .../Fixtures/serialized/emoji-from.input.sql  |   1 +
 .../Fixtures/serialized/emoji-to.expected.sql |   1 +
 tests/Fixtures/serialized/emoji-to.input.sql  |   1 +
 .../escaped-delimiters.expected.sql           |   1 +
 .../serialized/escaped-delimiters.input.sql   |   1 +
 .../serialized/heavy-escaping.expected.sql    |   1 +
 .../serialized/heavy-escaping.input.sql       |   1 +
 .../serialized/http-to-https.expected.sql     |   1 +
 .../serialized/http-to-https.input.sql        |   1 +
 .../long-different-lengths.expected.sql       |   1 +
 .../long-different-lengths.input.sql          |   1 +
 .../multiple-occurrences.expected.sql         |   1 +
 .../serialized/multiple-occurrences.input.sql |   1 +
 .../mydumper-delimiters.expected.sql          |   1 +
 .../serialized/mydumper-delimiters.input.sql  |   1 +
 .../non-serialized-mixed.expected.sql         |   1 +
 .../serialized/non-serialized-mixed.input.sql |   1 +
 .../serialized/null-bytes.expected.sql        |   1 +
 .../Fixtures/serialized/null-bytes.input.sql  |   1 +
 .../overlapping-non-serialized.expected.sql   |   1 +
 .../overlapping-non-serialized.input.sql      |   1 +
 .../serialized/serialized-css.expected.sql    |   1 +
 .../serialized/serialized-css.input.sql       |   1 +
 .../serialized/skip-updated.expected.sql      |   1 +
 .../serialized/skip-updated.input.sql         |   1 +
 31 files changed, 357 insertions(+)
 create mode 100644 tests/FileSearchReplacerTest.php
 create mode 100644 tests/Fixtures/serialized/different-lengths.expected.sql
 create mode 100644 tests/Fixtures/serialized/different-lengths.input.sql
 create mode 100644 tests/Fixtures/serialized/double-encoded.expected.sql
 create mode 100644 tests/Fixtures/serialized/double-encoded.input.sql
 create mode 100644 tests/Fixtures/serialized/emoji-from.expected.sql
 create mode 100644 tests/Fixtures/serialized/emoji-from.input.sql
 create mode 100644 tests/Fixtures/serialized/emoji-to.expected.sql
 create mode 100644 tests/Fixtures/serialized/emoji-to.input.sql
 create mode 100644 tests/Fixtures/serialized/escaped-delimiters.expected.sql
 create mode 100644 tests/Fixtures/serialized/escaped-delimiters.input.sql
 create mode 100644 tests/Fixtures/serialized/heavy-escaping.expected.sql
 create mode 100644 tests/Fixtures/serialized/heavy-escaping.input.sql
 create mode 100644 tests/Fixtures/serialized/http-to-https.expected.sql
 create mode 100644 tests/Fixtures/serialized/http-to-https.input.sql
 create mode 100644 tests/Fixtures/serialized/long-different-lengths.expected.sql
 create mode 100644 tests/Fixtures/serialized/long-different-lengths.input.sql
 create mode 100644 tests/Fixtures/serialized/multiple-occurrences.expected.sql
 create mode 100644 tests/Fixtures/serialized/multiple-occurrences.input.sql
 create mode 100644 tests/Fixtures/serialized/mydumper-delimiters.expected.sql
 create mode 100644 tests/Fixtures/serialized/mydumper-delimiters.input.sql
 create mode 100644 tests/Fixtures/serialized/non-serialized-mixed.expected.sql
 create mode 100644 tests/Fixtures/serialized/non-serialized-mixed.input.sql
 create mode 100644 tests/Fixtures/serialized/null-bytes.expected.sql
 create mode 100644 tests/Fixtures/serialized/null-bytes.input.sql
 create mode 100644 tests/Fixtures/serialized/overlapping-non-serialized.expected.sql
 create mode 100644 tests/Fixtures/serialized/overlapping-non-serialized.input.sql
 create mode 100644 tests/Fixtures/serialized/serialized-css.expected.sql
 create mode 100644 tests/Fixtures/serialized/serialized-css.input.sql
 create mode 100644 tests/Fixtures/serialized/skip-updated.expected.sql
 create mode 100644 tests/Fixtures/serialized/skip-updated.input.sql

diff --git a/tests/FileSearchReplacerTest.php b/tests/FileSearchReplacerTest.php
new file mode 100644
index 00000000..3ae01c3b
--- /dev/null
+++ b/tests/FileSearchReplacerTest.php
@@ -0,0 +1,327 @@
+<?php
+
+use WP_CLI\FileSearchReplacer;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+
+class FileSearchReplacerTest extends TestCase {
+
+	private FileSearchReplacer $replacer;
+
+	protected function setUp(): void {
+		$this->replacer = new FileSearchReplacer();
+	}
+
+	/**
+	 * @param array<int, array{from:string,to:string}> $replacements
+	 */
+	#[DataProvider( 'provideSerializedFixtures' )]
+	public function testProcessLineMatchesGoImplementation(
+		string $inputFixture,
+		string $expectedFixture,
+		array $replacements,
+	): void {
+		$input    = file_get_contents( $inputFixture );
+		$expected = file_get_contents( $expectedFixture );
+
+		self::assertNotFalse( $input );
+		self::assertNotFalse( $expected );
+
+		self::assertSame( $expected, $this->replacer->process_line( $input, $replacements ) );
+	}
+
+	/**
+	 * @return array<string, array{string,string,array<int, array{from:string,to:string}>}>
+	 */
+	public static function provideSerializedFixtures(): array {
+		$base                        = __DIR__ . '/Fixtures/serialized';
+		$doubleEncodedFrom           = <<<'TXT'
+		http:\\/\\/example\\.com
+		TXT;
+		$doubleEncodedTo             = <<<'TXT'
+		http:\\/\\/example2\\.com
+		TXT;
+		$doubleEncodedSerializedFrom = <<<'TXT'
+		\\s=\\shttp_get\(\'http:\\/\\/example\\.com
+		TXT;
+		$doubleEncodedSerializedTo   = <<<'TXT'
+		\\s=\\shttp_get\(\'http:\\/\\/example2\\.com
+		TXT;
+		$heavyEscapingFrom           = <<<'TXT'
+		\\c\\d\\e
+		TXT;
+		$heavyEscapingTo             = <<<'TXT'
+		\\x
+		TXT;
+
+		return [
+			'http to https'                               => [
+				$base . '/http-to-https.input.sql',
+				$base . '/http-to-https.expected.sql',
+				[
+					[
+						'from' => 'http://automattic.com',
+						'to'   => 'https://automattic.com',
+					],
+				],
+			],
+			'multiple occurrences on line'                => [
+				$base . '/multiple-occurrences.input.sql',
+				$base . '/multiple-occurrences.expected.sql',
+				[
+					[
+						'from' => 'http://automattic.com',
+						'to'   => 'https://automattic.com',
+					],
+				],
+			],
+			'skip already replaced value'                 => [
+				$base . '/skip-updated.input.sql',
+				$base . '/skip-updated.expected.sql',
+				[
+					[
+						'from' => 'http://automattic.com',
+						'to'   => 'https://automattic.com',
+					],
+				],
+			],
+			'emoji from'                                  => [
+				$base . '/emoji-from.input.sql',
+				$base . '/emoji-from.expected.sql',
+				[
+					[
+						'from' => 'http://🖖.com',
+						'to'   => 'https://spock.com',
+					],
+				],
+			],
+			'emoji to'                                    => [
+				$base . '/emoji-to.input.sql',
+				$base . '/emoji-to.expected.sql',
+				[
+					[
+						'from' => 'https://spock.com',
+						'to'   => 'http://🖖.com',
+					],
+				],
+			],
+			'null characters'                             => [
+				$base . '/null-bytes.input.sql',
+				$base . '/null-bytes.expected.sql',
+				[
+					[
+						'from' => 'EnvironmentObject',
+						'to'   => 'Yeehaw',
+					],
+				],
+			],
+			'different lengths'                           => [
+				$base . '/different-lengths.input.sql',
+				$base . '/different-lengths.expected.sql',
+				[
+					[
+						'from' => 'hello',
+						'to'   => 'goodbye',
+					],
+				],
+			],
+			'longer replacements'                         => [
+				$base . '/long-different-lengths.input.sql',
+				$base . '/long-different-lengths.expected.sql',
+				[
+					[
+						'from' => 'bbbbbbbbbb',
+						'to'   => 'ccccccccccccccc',
+					],
+				],
+			],
+			'serialized css'                              => [
+				$base . '/serialized-css.input.sql',
+				$base . '/serialized-css.expected.sql',
+				[
+					[
+						'from' => 'https://uss-enterprise.com',
+						'to'   => 'https://ncc-1701-d.space',
+					],
+				],
+			],
+			'double encoded string'                       => [
+				$base . '/double-encoded.input.sql',
+				$base . '/double-encoded.expected.sql',
+				[
+					[
+						'from' => $doubleEncodedFrom,
+						'to'   => $doubleEncodedTo,
+					],
+				],
+			],
+			'non serialized section with serialized data' => [
+				$base . '/non-serialized-mixed.input.sql',
+				$base . '/non-serialized-mixed.expected.sql',
+				[
+					[
+						'from' => 'example',
+						'to'   => 'example2',
+					],
+					[
+						'from' => $doubleEncodedFrom,
+						'to'   => $doubleEncodedTo,
+					],
+				],
+			],
+			'heavy escaping'                              => [
+				$base . '/heavy-escaping.input.sql',
+				$base . '/heavy-escaping.expected.sql',
+				[
+					[
+						'from' => $heavyEscapingFrom,
+						'to'   => $heavyEscapingTo,
+					],
+				],
+			],
+			'escaped delimiters'                          => [
+				$base . '/escaped-delimiters.input.sql',
+				$base . '/escaped-delimiters.expected.sql',
+				[
+					[
+						'from' => 'hello',
+						'to'   => 'helloworld',
+					],
+				],
+			],
+			'mydumper delimiters'                         => [
+				$base . '/mydumper-delimiters.input.sql',
+				$base . '/mydumper-delimiters.expected.sql',
+				[
+					[
+						'from' => 'hello',
+						'to'   => 'helloworld',
+					],
+				],
+			],
+			'overlapping replacements without serialization' => [
+				$base . '/overlapping-non-serialized.input.sql',
+				$base . '/overlapping-non-serialized.expected.sql',
+				[
+					[
+						'from' => 'http:',
+						'to'   => 'https:',
+					],
+					[
+						'from' => '//automattic.com',
+						'to'   => '//automattic.org',
+					],
+				],
+			],
+		];
+	}
+
+	public function testProcessLineWithEmptyReplacementsReturnsOriginal(): void {
+		$line = 'plain text line';
+		self::assertSame( $line, $this->replacer->process_line( $line, [] ) );
+	}
+
+	public function testProcessLineRejectsInvalidReplacements(): void {
+		$this->expectException( RuntimeException::class );
+		$this->replacer->process_line( 'anything', [ [ 'from' => 'only-from' ] ] );
+	}
+
+	public function testReplaceInFileProcessesEntireContents(): void {
+		$input  = tempnam( sys_get_temp_dir(), 'sql-src-' );
+		$output = tempnam( sys_get_temp_dir(), 'sql-out-' );
+
+		self::assertNotFalse( $input );
+		self::assertNotFalse( $output );
+
+		$fixture = <<<'SQL'
+		s:21:\"http://automattic.com\";
+		http://example.com
+
+		SQL;
+
+		file_put_contents( $input, $fixture );
+
+		$this->replacer->replace_in_file(
+			$input,
+			$output,
+			[
+				[
+					'from' => 'http://automattic.com',
+					'to'   => 'https://automattic.com',
+				],
+				[
+					'from' => 'http://example.com',
+					'to'   => 'https://example.com',
+				],
+			]
+		);
+
+		$result = file_get_contents( $output );
+
+		$expected = <<<'SQL'
+		s:22:\"https://automattic.com\";
+		https://example.com
+
+		SQL;
+
+		self::assertSame( $expected, $result );
+
+		@unlink( $input );
+		@unlink( $output );
+	}
+
+	public function testFixturesMatchGoBinaryOutput(): void {
+		$input    = $this->extractSqlFixture( __DIR__ . '/Fixtures/wpbreakstufflocalhost.sql.zip' );
+		$expected = $this->extractSqlFixture( __DIR__ . '/Fixtures/wpbreakstufflol.sql.zip' );
+
+		$output = tempnam( sys_get_temp_dir(), 'sql-fixture-' );
+		self::assertNotFalse( $output );
+
+		try {
+			$this->replacer->replace_in_file(
+				$input,
+				$output,
+				[
+					[
+						'from' => 'wp.breakstuff.localhost',
+						'to'   => 'wp.breakstuff.lol',
+					],
+				]
+			);
+
+			self::assertFileEquals( $expected, $output );
+		} finally {
+			@unlink( $input );
+			@unlink( $expected );
+			@unlink( $output );
+		}
+	}
+
+	private function extractSqlFixture( string $zip_path ): string {
+		if ( ! is_file( $zip_path ) ) {
+			throw new RuntimeException( sprintf( 'Fixture "%s" does not exist.', $zip_path ) );
+		}
+
+		$zip = new \ZipArchive();
+		if ( $zip->open( $zip_path ) !== true ) {
+			throw new RuntimeException( sprintf( 'Unable to open fixture "%s".', $zip_path ) );
+		}
+
+		$contents = $zip->getFromIndex( 0 );
+		$zip->close();
+
+		if ( false === $contents ) {
+			throw new RuntimeException( sprintf( 'Unable to read contents of fixture "%s".', $zip_path ) );
+		}
+
+		$temp_path = tempnam( sys_get_temp_dir(), 'sql-fixture-' );
+		if ( false === $temp_path ) {
+			throw new RuntimeException( 'Unable to create temporary fixture file.' );
+		}
+
+		file_put_contents( $temp_path, $contents );
+
+		return $temp_path;
+	}
+}
diff --git a/tests/Fixtures/serialized/different-lengths.expected.sql b/tests/Fixtures/serialized/different-lengths.expected.sql
new file mode 100644
index 00000000..95555792
--- /dev/null
+++ b/tests/Fixtures/serialized/different-lengths.expected.sql
@@ -0,0 +1 @@
+s:13:\"goodbye-world\";
diff --git a/tests/Fixtures/serialized/different-lengths.input.sql b/tests/Fixtures/serialized/different-lengths.input.sql
new file mode 100644
index 00000000..ccd4e6ce
--- /dev/null
+++ b/tests/Fixtures/serialized/different-lengths.input.sql
@@ -0,0 +1 @@
+s:11:\"hello-world\";
diff --git a/tests/Fixtures/serialized/double-encoded.expected.sql b/tests/Fixtures/serialized/double-encoded.expected.sql
new file mode 100644
index 00000000..b800d219
--- /dev/null
+++ b/tests/Fixtures/serialized/double-encoded.expected.sql
@@ -0,0 +1 @@
+s:38:\"\\s=\\shttp_get\\(\'http:\\/\\/example2\\.com\";
diff --git a/tests/Fixtures/serialized/double-encoded.input.sql b/tests/Fixtures/serialized/double-encoded.input.sql
new file mode 100644
index 00000000..413cfd97
--- /dev/null
+++ b/tests/Fixtures/serialized/double-encoded.input.sql
@@ -0,0 +1 @@
+s:37:\"\\s=\\shttp_get\\(\'http:\\/\\/example\\.com\";
diff --git a/tests/Fixtures/serialized/emoji-from.expected.sql b/tests/Fixtures/serialized/emoji-from.expected.sql
new file mode 100644
index 00000000..0ec528f1
--- /dev/null
+++ b/tests/Fixtures/serialized/emoji-from.expected.sql
@@ -0,0 +1 @@
+s:17:\"https://spock.com\";
diff --git a/tests/Fixtures/serialized/emoji-from.input.sql b/tests/Fixtures/serialized/emoji-from.input.sql
new file mode 100644
index 00000000..d5069b15
--- /dev/null
+++ b/tests/Fixtures/serialized/emoji-from.input.sql
@@ -0,0 +1 @@
+s:15:\"http://🖖.com\";
diff --git a/tests/Fixtures/serialized/emoji-to.expected.sql b/tests/Fixtures/serialized/emoji-to.expected.sql
new file mode 100644
index 00000000..d5069b15
--- /dev/null
+++ b/tests/Fixtures/serialized/emoji-to.expected.sql
@@ -0,0 +1 @@
+s:15:\"http://🖖.com\";
diff --git a/tests/Fixtures/serialized/emoji-to.input.sql b/tests/Fixtures/serialized/emoji-to.input.sql
new file mode 100644
index 00000000..0ec528f1
--- /dev/null
+++ b/tests/Fixtures/serialized/emoji-to.input.sql
@@ -0,0 +1 @@
+s:17:\"https://spock.com\";
diff --git a/tests/Fixtures/serialized/escaped-delimiters.expected.sql b/tests/Fixtures/serialized/escaped-delimiters.expected.sql
new file mode 100644
index 00000000..815b7c98
--- /dev/null
+++ b/tests/Fixtures/serialized/escaped-delimiters.expected.sql
@@ -0,0 +1 @@
+('s:39:\"\";\";\";\";\";\\\";\\\";\\\"; helloworld \\\\\";\\\\\";\";')
diff --git a/tests/Fixtures/serialized/escaped-delimiters.input.sql b/tests/Fixtures/serialized/escaped-delimiters.input.sql
new file mode 100644
index 00000000..b7a806a3
--- /dev/null
+++ b/tests/Fixtures/serialized/escaped-delimiters.input.sql
@@ -0,0 +1 @@
+('s:34:\"\";\";\";\";\";\\\";\\\";\\\"; hello \\\\\";\\\\\";\";')
diff --git a/tests/Fixtures/serialized/heavy-escaping.expected.sql b/tests/Fixtures/serialized/heavy-escaping.expected.sql
new file mode 100644
index 00000000..4ff835d9
--- /dev/null
+++ b/tests/Fixtures/serialized/heavy-escaping.expected.sql
@@ -0,0 +1 @@
+s:14:\"\\a\\b\\x\\f\\g\\h\";\";
diff --git a/tests/Fixtures/serialized/heavy-escaping.input.sql b/tests/Fixtures/serialized/heavy-escaping.input.sql
new file mode 100644
index 00000000..3f006e6b
--- /dev/null
+++ b/tests/Fixtures/serialized/heavy-escaping.input.sql
@@ -0,0 +1 @@
+s:18:\"\\a\\b\\c\\d\\e\\f\\g\\h\";\";
diff --git a/tests/Fixtures/serialized/http-to-https.expected.sql b/tests/Fixtures/serialized/http-to-https.expected.sql
new file mode 100644
index 00000000..0ef2d229
--- /dev/null
+++ b/tests/Fixtures/serialized/http-to-https.expected.sql
@@ -0,0 +1 @@
+s:22:\"https://automattic.com\";
diff --git a/tests/Fixtures/serialized/http-to-https.input.sql b/tests/Fixtures/serialized/http-to-https.input.sql
new file mode 100644
index 00000000..f6bb5dd0
--- /dev/null
+++ b/tests/Fixtures/serialized/http-to-https.input.sql
@@ -0,0 +1 @@
+s:21:\"http://automattic.com\";
diff --git a/tests/Fixtures/serialized/long-different-lengths.expected.sql b/tests/Fixtures/serialized/long-different-lengths.expected.sql
new file mode 100644
index 00000000..1d656cd5
--- /dev/null
+++ b/tests/Fixtures/serialized/long-different-lengths.expected.sql
@@ -0,0 +1 @@
+s:25:\"aaaaacccccccccccccccaaaaa\";
diff --git a/tests/Fixtures/serialized/long-different-lengths.input.sql b/tests/Fixtures/serialized/long-different-lengths.input.sql
new file mode 100644
index 00000000..1fb6aadf
--- /dev/null
+++ b/tests/Fixtures/serialized/long-different-lengths.input.sql
@@ -0,0 +1 @@
+s:20:\"aaaaabbbbbbbbbbaaaaa\";
diff --git a/tests/Fixtures/serialized/multiple-occurrences.expected.sql b/tests/Fixtures/serialized/multiple-occurrences.expected.sql
new file mode 100644
index 00000000..81ad5d72
--- /dev/null
+++ b/tests/Fixtures/serialized/multiple-occurrences.expected.sql
@@ -0,0 +1 @@
+('s:22:\"https://automattic.com\";'),('s:22:\"https://automattic.com\";')
diff --git a/tests/Fixtures/serialized/multiple-occurrences.input.sql b/tests/Fixtures/serialized/multiple-occurrences.input.sql
new file mode 100644
index 00000000..8653e697
--- /dev/null
+++ b/tests/Fixtures/serialized/multiple-occurrences.input.sql
@@ -0,0 +1 @@
+('s:21:\"http://automattic.com\";'),('s:21:\"http://automattic.com\";')
diff --git a/tests/Fixtures/serialized/mydumper-delimiters.expected.sql b/tests/Fixtures/serialized/mydumper-delimiters.expected.sql
new file mode 100644
index 00000000..c6f5301d
--- /dev/null
+++ b/tests/Fixtures/serialized/mydumper-delimiters.expected.sql
@@ -0,0 +1 @@
+("s:39:\"\";\";\";\";\";\\\";\\\";\\\"; helloworld \\\\\";\\\\\";\";")
diff --git a/tests/Fixtures/serialized/mydumper-delimiters.input.sql b/tests/Fixtures/serialized/mydumper-delimiters.input.sql
new file mode 100644
index 00000000..84be1010
--- /dev/null
+++ b/tests/Fixtures/serialized/mydumper-delimiters.input.sql
@@ -0,0 +1 @@
+("s:34:\"\";\";\";\";\";\\\";\\\";\\\"; hello \\\\\";\\\\\";\";")
diff --git a/tests/Fixtures/serialized/non-serialized-mixed.expected.sql b/tests/Fixtures/serialized/non-serialized-mixed.expected.sql
new file mode 100644
index 00000000..87c34b8e
--- /dev/null
+++ b/tests/Fixtures/serialized/non-serialized-mixed.expected.sql
@@ -0,0 +1 @@
+('example2'),('s:38:\"\\s=\\shttp_get\\(\'http:\\/\\/example2\\.com\";')
diff --git a/tests/Fixtures/serialized/non-serialized-mixed.input.sql b/tests/Fixtures/serialized/non-serialized-mixed.input.sql
new file mode 100644
index 00000000..ec1f0de8
--- /dev/null
+++ b/tests/Fixtures/serialized/non-serialized-mixed.input.sql
@@ -0,0 +1 @@
+('example'),('s:37:\"\\s=\\shttp_get\\(\'http:\\/\\/example\\.com\";')
diff --git a/tests/Fixtures/serialized/null-bytes.expected.sql b/tests/Fixtures/serialized/null-bytes.expected.sql
new file mode 100644
index 00000000..c77f2654
--- /dev/null
+++ b/tests/Fixtures/serialized/null-bytes.expected.sql
@@ -0,0 +1 @@
+s:19:\"\0Yeehaw\0wp_site_url\";
diff --git a/tests/Fixtures/serialized/null-bytes.input.sql b/tests/Fixtures/serialized/null-bytes.input.sql
new file mode 100644
index 00000000..1dde485e
--- /dev/null
+++ b/tests/Fixtures/serialized/null-bytes.input.sql
@@ -0,0 +1 @@
+s:30:\"\0EnvironmentObject\0wp_site_url\";
diff --git a/tests/Fixtures/serialized/overlapping-non-serialized.expected.sql b/tests/Fixtures/serialized/overlapping-non-serialized.expected.sql
new file mode 100644
index 00000000..e7bfe666
--- /dev/null
+++ b/tests/Fixtures/serialized/overlapping-non-serialized.expected.sql
@@ -0,0 +1 @@
+https://automattic.org
diff --git a/tests/Fixtures/serialized/overlapping-non-serialized.input.sql b/tests/Fixtures/serialized/overlapping-non-serialized.input.sql
new file mode 100644
index 00000000..e7b50e5a
--- /dev/null
+++ b/tests/Fixtures/serialized/overlapping-non-serialized.input.sql
@@ -0,0 +1 @@
+http://automattic.com
diff --git a/tests/Fixtures/serialized/serialized-css.expected.sql b/tests/Fixtures/serialized/serialized-css.expected.sql
new file mode 100644
index 00000000..23577912
--- /dev/null
+++ b/tests/Fixtures/serialized/serialized-css.expected.sql
@@ -0,0 +1 @@
+a:2:{s:3:\"key\";s:5:\"value\";s:3:\"css\";s:206:\"body { color: #123456;\r\nborder-bottom: none; }\r\ndiv.bg { background: url('https://ncc-1701-d.space/wp-content/uploads/main-bg.gif');\r\n  background-position: left center;\r\n    background-repeat: no-repeat; }\";}
diff --git a/tests/Fixtures/serialized/serialized-css.input.sql b/tests/Fixtures/serialized/serialized-css.input.sql
new file mode 100644
index 00000000..e4c6c55c
--- /dev/null
+++ b/tests/Fixtures/serialized/serialized-css.input.sql
@@ -0,0 +1 @@
+a:2:{s:3:\"key\";s:5:\"value\";s:3:\"css\";s:208:\"body { color: #123456;\r\nborder-bottom: none; }\r\ndiv.bg { background: url('https://uss-enterprise.com/wp-content/uploads/main-bg.gif');\r\n  background-position: left center;\r\n    background-repeat: no-repeat; }\";}
diff --git a/tests/Fixtures/serialized/skip-updated.expected.sql b/tests/Fixtures/serialized/skip-updated.expected.sql
new file mode 100644
index 00000000..22f917d7
--- /dev/null
+++ b/tests/Fixtures/serialized/skip-updated.expected.sql
@@ -0,0 +1 @@
+('s:22:\"https://automattic.com\";'),('s:21:\"https://a8c.com\";')
diff --git a/tests/Fixtures/serialized/skip-updated.input.sql b/tests/Fixtures/serialized/skip-updated.input.sql
new file mode 100644
index 00000000..fc57c39c
--- /dev/null
+++ b/tests/Fixtures/serialized/skip-updated.input.sql
@@ -0,0 +1 @@
+('s:21:\"http://automattic.com\";'),('s:21:\"https://a8c.com\";')

From dedb2051776eb5629222b16e28ce1fe29d8844a0 Mon Sep 17 00:00:00 2001
From: Alex Younger <thealexyounger@proton.me>
Date: Sat, 9 May 2026 20:19:39 -0500
Subject: [PATCH 2/2] feat: add `file` subcommand for SQL file processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces a new `file` subcommand that performs search/replace directly
on SQL dump files (or streams) using a WP-CLI-compliant port of
Automattic's go-search-replace algorithm.
This complements the existing database-centric `search-replace` command
by providing a text-level engine that correctly handles serialized PHP
strings and updates their length markers — including when the search
string appears as an array key.

Usage:
  wp search-replace file <old> <new> [<input.sql> [<output.sql>]]
  wp search-replace file --old=<old> --new=<new> input.sql output.sql
  wp search-replace file old new --in-place dump.sql
  cat dump.sql | wp search-replace file old new - -

Supported flags:
  --old, --new    Alternative to positional arguments (for strings
                  starting with '--')
  --in-place      Edit the input file in place
  --dry-run       Preview changes without writing output
  --verbose       Show per-line processing information

The implementation follows existing project conventions:
- `FileSearchReplacer` and `Serialized_Replace_Result` live under the
  `WP_CLI` namespace with proper PHPCS exclusions in phpcs.xml.dist
- All error handling uses exceptions (CLI layer converts to WP_CLI::error)
- Full `composer test` passes (production code is zero-warning)
- 19 unit tests pass, including large fixture parity tests against
  the original go-search-replace binary

Refs:
  https://github.com/AlextheYounga/php-search-replace
  https://github.com/Automattic/go-search-replace
---
 phpcs.xml.dist                           |   8 +
 search-replace-command.php               |   1 +
 src/Search_Replace_File_Command.php      | 271 ++++++++++++++++++
 src/WP_CLI/FileSearchReplacer.php        | 337 +++++++++++++++++++++++
 src/WP_CLI/Serialized_Replace_Result.php |  41 +++
 5 files changed, 658 insertions(+)
 create mode 100644 src/Search_Replace_File_Command.php
 create mode 100644 src/WP_CLI/FileSearchReplacer.php
 create mode 100644 src/WP_CLI/Serialized_Replace_Result.php

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index c58a9fd8..3866aa40 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -12,6 +12,7 @@
 
 	<!-- What to scan. -->
 	<file>.</file>
+	<exclude-pattern>tests/FileSearchReplacerTest\.php</exclude-pattern>
 
 	<!-- Show progress. -->
 	<arg value="p"/>
@@ -60,9 +61,16 @@
 	<!-- Exclude existing classes and namespaces from the prefix rule as it would break BC to prefix them now. -->
 	<rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound">
 		<exclude-pattern>*/src/Search_Replace_Command\.php$</exclude-pattern>
+		<exclude-pattern>*/src/Search_Replace_File_Command\.php$</exclude-pattern>
 	</rule>
+
+	<!-- The test file is a direct port of the go-search-replace test suite. -->
+	<exclude-pattern>*/tests/FileSearchReplacerTest\.php$</exclude-pattern>
+
 	<rule ref="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedNamespaceFound">
 		<exclude-pattern>*/src/WP_CLI/SearchReplacer\.php$</exclude-pattern>
+		<exclude-pattern>*/src/WP_CLI/FileSearchReplacer\.php$</exclude-pattern>
+		<exclude-pattern>*/src/WP_CLI/Serialized_Replace_Result\.php$</exclude-pattern>
 	</rule>
 
 	<!-- Allow for some MySQL native non-snake-case properties.
diff --git a/search-replace-command.php b/search-replace-command.php
index bd2ad0e9..d12d65b5 100644
--- a/search-replace-command.php
+++ b/search-replace-command.php
@@ -10,3 +10,4 @@
 }
 
 WP_CLI::add_command( 'search-replace', 'Search_Replace_Command' );
+WP_CLI::add_command( 'search-replace file', 'Search_Replace_File_Command' );
diff --git a/src/Search_Replace_File_Command.php b/src/Search_Replace_File_Command.php
new file mode 100644
index 00000000..66c6b54f
--- /dev/null
+++ b/src/Search_Replace_File_Command.php
@@ -0,0 +1,271 @@
+<?php
+/**
+ * Search and replace within a SQL file using the go-search-replace algorithm.
+ */
+class Search_Replace_File_Command extends WP_CLI_Command {
+
+	/**
+	 * Search and replace within a SQL file.
+	 *
+	 * This command uses the same algorithm as Automattic's go-search-replace utility.
+	 * It operates directly on SQL text (including serialized PHP strings) and correctly
+	 * updates serialized string length markers. This makes it especially useful for
+	 * processing database dumps without needing a live database connection.
+	 *
+	 * ## OPTIONS
+	 *
+	 * [<old>]
+	 * : A string to search for within the SQL file.
+	 *
+	 * [<new>]
+	 * : Replace instances of the first string with this new string.
+	 *
+	 * [<input-file>]
+	 * : Path to the input SQL file. Use '-' to read from STDIN. If omitted, defaults to STDIN.
+	 *
+	 * [<output-file>]
+	 * : Path to write the transformed SQL. Use '-' to write to STDOUT. If omitted and --in-place is not used, defaults to STDOUT.
+	 *
+	 * [--old=<value>]
+	 * : An alternative way to specify the search string. Use this when the search string starts with '--'.
+	 *
+	 * [--new=<value>]
+	 * : An alternative way to specify the replacement string. Use this when the replacement string starts with '--'.
+	 *
+	 * [--in-place]
+	 * : Edit the input file in place. Cannot be used together with an explicit output file.
+	 *
+	 * [--dry-run]
+	 * : Run the replacement and show what would change, but do not write any output.
+	 *
+	 * [--verbose]
+	 * : Show additional information during processing.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # Basic usage with files
+	 *     $ wp search-replace file example.com newdomain.com dump.sql updated.sql
+	 *
+	 *     # Read from STDIN and write to STDOUT
+	 *     $ cat dump.sql | wp search-replace file example.com newdomain.com - -
+	 *
+	 *     # In-place edit
+	 *     $ wp search-replace file example.com newdomain.com dump.sql --in-place
+	 *
+	 *     # Using --old and --new flags
+	 *     $ wp search-replace file --old='--old-value' --new='--new-value' dump.sql
+	 *
+	 * @param array<string> $args Positional arguments.
+	 * @param array{'old'?: string, 'new'?: string, 'in-place'?: bool, 'dry-run'?: bool, 'verbose'?: bool} $assoc_args Associative arguments.
+	 */
+	public function __invoke( $args, $assoc_args ) {
+		// Support --old and --new flags as an alternative to positional arguments.
+		$old_flag = \WP_CLI\Utils\get_flag_value( $assoc_args, 'old' );
+		$new_flag = \WP_CLI\Utils\get_flag_value( $assoc_args, 'new' );
+
+		$both_flags_provided = null !== $old_flag && null !== $new_flag;
+		$has_positional_args = ! empty( $args );
+
+		if ( $both_flags_provided && $has_positional_args ) {
+			\WP_CLI::error( 'Cannot use both positional arguments and --old/--new flags. Please use one method or the other.' );
+		}
+
+		$old = null !== $old_flag ? $old_flag : array_shift( $args );
+		$new = null !== $new_flag ? $new_flag : array_shift( $args );
+
+		if ( null === $old || null === $new || '' === $old ) {
+			$missing = [];
+			if ( null === $old || '' === $old ) {
+				$missing[] = '<old>';
+			}
+			if ( null === $new ) {
+				$missing[] = '<new>';
+			}
+			$error_msg = count( $missing ) === 2
+				? 'Please provide both <old> and <new> arguments.'
+				: sprintf( 'Please provide the %s argument.', $missing[0] );
+
+			$error_msg .= "\n\nNote: If your search or replacement string starts with '--', use the flag syntax instead:"
+				. "\n  wp search-replace file --old='--text' --new='replacement' input.sql output.sql";
+
+			\WP_CLI::error( $error_msg );
+		}
+
+		$in_place = \WP_CLI\Utils\get_flag_value( $assoc_args, 'in-place', false );
+		$dry_run  = \WP_CLI\Utils\get_flag_value( $assoc_args, 'dry-run', false );
+		$verbose  = \WP_CLI\Utils\get_flag_value( $assoc_args, 'verbose', false );
+
+		$input_file  = array_shift( $args );
+		$output_file = array_shift( $args );
+
+		if ( null === $input_file ) {
+			$input_file = '-';
+		}
+
+		if ( null === $output_file ) {
+			$output_file = $in_place ? $input_file : '-';
+		}
+
+		if ( $in_place && $input_file !== $output_file ) {
+			\WP_CLI::error( 'Cannot specify an output file when using --in-place.' );
+		}
+
+		if ( '-' === $input_file && $in_place ) {
+			\WP_CLI::error( 'Cannot use --in-place when reading from STDIN.' );
+		}
+
+		$replacer = new \WP_CLI\FileSearchReplacer();
+
+		$replacements = [
+			[
+				'from' => $old,
+				'to'   => $new,
+			],
+		];
+
+		if ( $dry_run ) {
+			$this->do_dry_run( $replacer, $input_file, $replacements, $verbose );
+			return;
+		}
+
+		$this->do_replace( $replacer, $input_file, $output_file, $replacements, $verbose );
+	}
+
+	/**
+	 * Perform a dry-run (read input, process, but do not write).
+	 *
+	 * @param array<int, array{from:string,to:string}> $replacements
+	 */
+	private function do_dry_run( \WP_CLI\FileSearchReplacer $replacer, string $input_file, array $replacements, bool $verbose ): void {
+		$input_handle = $this->open_input( $input_file );
+
+		$total_lines        = 0;
+		$changed_lines      = 0;
+		$total_replacements = 0;
+
+		while ( true ) {
+			$line = fgets( $input_handle );
+			if ( false === $line ) {
+				break;
+			}
+			++$total_lines;
+			$processed = $replacer->process_line( $line, $replacements );
+
+			if ( $processed !== $line ) {
+				++$changed_lines;
+				// Count how many times old appears in the original line
+				$old                 = $replacements[0]['from'];
+				$total_replacements += substr_count( $line, $old );
+			}
+
+			if ( $verbose ) {
+				\WP_CLI::line( sprintf( 'Line %d: %s', $total_lines, $processed !== $line ? 'changed' : 'unchanged' ) );
+			}
+		}
+
+		if ( '-' !== $input_file ) {
+			fclose( $input_handle );
+		}
+
+		\WP_CLI::success(
+			sprintf(
+				'Dry run complete. %d lines processed, %d lines would change, %d total replacements.',
+				$total_lines,
+				$changed_lines,
+				$total_replacements
+			)
+		);
+	}
+
+	/**
+	 * Perform the actual replacement and write output.
+	 *
+	 * @param array<int, array{from:string,to:string}> $replacements
+	 */
+	private function do_replace( \WP_CLI\FileSearchReplacer $replacer, string $input_file, string $output_file, array $replacements, bool $verbose ): void {
+		$input_handle  = $this->open_input( $input_file );
+		$output_handle = $this->open_output( $output_file );
+
+		$total_lines        = 0;
+		$changed_lines      = 0;
+		$total_replacements = 0;
+
+		while ( true ) {
+			$line = fgets( $input_handle );
+			if ( false === $line ) {
+				break;
+			}
+			++$total_lines;
+			$processed = $replacer->process_line( $line, $replacements );
+
+			fwrite( $output_handle, $processed );
+
+			if ( $processed !== $line ) {
+				++$changed_lines;
+				$old                 = $replacements[0]['from'];
+				$total_replacements += substr_count( $line, $old );
+			}
+
+			if ( $verbose ) {
+				\WP_CLI::line( sprintf( 'Line %d: %s', $total_lines, $processed !== $line ? 'changed' : 'unchanged' ) );
+			}
+		}
+
+		if ( '-' !== $input_file ) {
+			fclose( $input_handle );
+		}
+		if ( '-' !== $output_file ) {
+			fclose( $output_handle );
+		}
+
+		$success_msg = 1 === $total_replacements
+			? 'Made 1 replacement.'
+			: sprintf( 'Made %d replacements.', $total_replacements );
+
+		\WP_CLI::success( $success_msg );
+	}
+
+	/**
+	 * Open an input handle (file or STDIN).
+	 *
+	 * @return resource
+	 */
+	private function open_input( string $input_file ) {
+		if ( '-' === $input_file ) {
+			$handle = fopen( 'php://stdin', 'rb' );
+			if ( false === $handle ) {
+				\WP_CLI::error( 'Unable to open STDIN for reading.' );
+			}
+			return $handle;
+		}
+
+		$handle = @fopen( $input_file, 'rb' );
+		if ( false === $handle ) {
+			$error = error_get_last();
+			\WP_CLI::error( sprintf( 'Unable to open input file "%s" for reading: %s.', $input_file, $error['message'] ?? 'unknown error' ) );
+		}
+		return $handle;
+	}
+
+	/**
+	 * Open an output handle (file or STDOUT).
+	 *
+	 * @return resource
+	 */
+	private function open_output( string $output_file ) {
+		if ( '-' === $output_file ) {
+			$handle = fopen( 'php://stdout', 'wb' );
+			if ( false === $handle ) {
+				\WP_CLI::error( 'Unable to open STDOUT for writing.' );
+			}
+			return $handle;
+		}
+
+		$handle = @fopen( $output_file, 'wb' );
+		if ( false === $handle ) {
+			$error = error_get_last();
+			\WP_CLI::error( sprintf( 'Unable to open output file "%s" for writing: %s.', $output_file, $error['message'] ?? 'unknown error' ) );
+		}
+		return $handle;
+	}
+}
diff --git a/src/WP_CLI/FileSearchReplacer.php b/src/WP_CLI/FileSearchReplacer.php
new file mode 100644
index 00000000..406fc6dc
--- /dev/null
+++ b/src/WP_CLI/FileSearchReplacer.php
@@ -0,0 +1,337 @@
+<?php
+
+namespace WP_CLI;
+
+/**
+ * Port of Automattic's go-search-replace serialized string fixer.
+ * Works directly on SQL dump text without requiring a live database.
+ */
+class FileSearchReplacer {
+
+	/**
+	 * Run replacements against a SQL file and write the result to another file.
+	 *
+	 * @param string $input_path  Path to the input SQL file.
+	 * @param string $output_path Path to the output SQL file.
+	 * @param array  $replacements Array of replacement pairs.
+	 */
+	public function replace_in_file( $input_path, $output_path, $replacements ) {
+		$normalized = $this->normalize_replacements( $replacements );
+		if ( empty( $normalized ) ) {
+			if ( $input_path === $output_path ) {
+				return;
+			}
+			if ( ! copy( $input_path, $output_path ) ) {
+				throw new \RuntimeException( sprintf( 'Unable to copy "%s" to "%s".', $input_path, $output_path ) );
+			}
+			return;
+		}
+
+		$input = @fopen( $input_path, 'rb' );
+		if ( false === $input ) {
+			throw new \RuntimeException( sprintf( 'Unable to open "%s" for reading.', $input_path ) );
+		}
+
+		$output = @fopen( $output_path, 'wb' );
+		if ( false === $output ) {
+			fclose( $input );
+			throw new \RuntimeException( sprintf( 'Unable to open "%s" for writing.', $output_path ) );
+		}
+
+		$line = fgets( $input );
+		while ( false !== $line ) {
+			fwrite( $output, $this->process_line( $line, $normalized ) );
+			$line = fgets( $input );
+		}
+
+		$remainder = stream_get_contents( $input );
+		if ( false !== $remainder && '' !== $remainder ) {
+			fwrite( $output, $this->process_line( $remainder, $normalized ) );
+		}
+
+		fclose( $input );
+		fclose( $output );
+	}
+
+	/**
+	 * Replace strings inside a line or chunk of SQL text.
+	 *
+	 * @param string $line         The line to process.
+	 * @param array  $replacements Replacement pairs.
+	 * @return string
+	 */
+	public function process_line( $line, $replacements ) {
+		if ( '' === $line ) {
+			return '';
+		}
+
+		$normalized = $this->normalize_replacements( $replacements );
+		if ( empty( $normalized ) ) {
+			return $line;
+		}
+
+		return $this->fix_line( $line, $normalized );
+	}
+
+	/**
+	 * Normalize and validate replacement array.
+	 *
+	 * @param array $replacements Raw replacements.
+	 * @return array
+	 */
+	private function normalize_replacements( $replacements ) {
+		$normalized = array();
+		foreach ( $replacements as $replacement ) {
+			if ( ! is_array( $replacement ) || ! isset( $replacement['from'], $replacement['to'] ) ) {
+				throw new \RuntimeException( 'Replacements must be arrays with "from" and "to" keys.' );
+			}
+
+			$from = (string) $replacement['from'];
+			$to   = (string) $replacement['to'];
+
+			if ( '' === $from ) {
+				continue;
+			}
+
+			$normalized[] = array(
+				'from' => $from,
+				'to'   => $to,
+			);
+		}
+
+		return $normalized;
+	}
+
+	/**
+	 * Fix a line containing serialized data.
+	 *
+	 * @param string $line_part    The line chunk.
+	 * @param array  $replacements Normalized replacements.
+	 * @return string
+	 */
+	private function fix_line( $line_part, $replacements ) {
+		$rebuilt = '';
+
+		while ( '' !== $line_part ) {
+			try {
+				$result = $this->fix_line_with_serialized_data( $line_part, $replacements );
+			} catch ( \Exception $exception ) {
+				$rebuilt  .= $line_part;
+				break;
+			}
+
+			$rebuilt  .= $result->pre . $result->serialized_portion;
+			$line_part = $result->post;
+
+			if ( '' === $line_part ) {
+				break;
+			}
+		}
+
+		return $rebuilt;
+	}
+
+	/**
+	 * Core logic that finds and rebuilds serialized strings.
+	 *
+	 * @param string $line_part    Line chunk.
+	 * @param array  $replacements Replacements.
+	 * @return Serialized_Replace_Result
+	 */
+	private function fix_line_with_serialized_data( $line_part, $replacements ) {
+		$prefix = $this->find_serialized_prefix( $line_part );
+
+		if ( null === $prefix ) {
+			return new Serialized_Replace_Result(
+				$this->replace_by_part( $line_part, $replacements ),
+				'',
+				''
+			);
+		}
+
+		$pre = substr( $line_part, 0, $prefix['start'] );
+		$pre = $this->replace_by_part( $pre, $replacements );
+
+		$original_byte_size  = (int) $prefix['raw_length'];
+		$content_start_index = $prefix['content_start'];
+
+		$current_content_index = $content_start_index;
+		$content_byte_count    = 0;
+		$content_end_index     = 0;
+		$next_slice_index      = null;
+		$next_slice_found      = false;
+		$max_index             = strlen( $line_part ) - 1;
+
+		while ( $current_content_index < strlen( $line_part ) ) {
+			if ( $current_content_index + 2 > $max_index ) {
+				throw new \RuntimeException( 'faulty serialized data: out-of-bound index access detected' );
+			}
+
+			$char       = $line_part[ $current_content_index ];
+			$second_char = $line_part[ $current_content_index + 1 ];
+			$third_char  = $line_part[ $current_content_index + 2 ];
+
+			if ( '\\' === $char && $content_byte_count < $original_byte_size ) {
+				$unescaped = $this->get_unescaped_bytes_if_escaped( substr( $line_part, $current_content_index, 2 ) );
+				$content_byte_count += strlen( $unescaped );
+				$current_content_index += 2;
+				continue;
+			}
+
+			if ( '\\' === $char && '"' === $second_char && ';' === $third_char && $content_byte_count >= $original_byte_size ) {
+				$next_slice_index = $current_content_index + 3;
+				$content_end_index = $current_content_index - 1;
+				$next_slice_found = true;
+				break;
+			}
+
+			if ( $content_byte_count > $original_byte_size ) {
+				throw new \RuntimeException( 'faulty serialized data: calculated byte count does not match given data size' );
+			}
+
+			$content_byte_count++;
+			$current_content_index++;
+		}
+
+		if ( ! $next_slice_found || null === $next_slice_index ) {
+			throw new \RuntimeException( 'faulty serialized data: end of serialized data not found' );
+		}
+
+		$content = substr( $line_part, $content_start_index, $content_end_index - $content_start_index + 1 );
+		$content = $this->replace_by_part( $content, $replacements );
+		$content_length = strlen( $this->unescape_content( $content ) );
+
+		$escaped_quote = '\"';
+		$rebuilt_serialized_string = 's:' . $content_length . ':' . $escaped_quote . $content . $escaped_quote . ';';
+
+		return new Serialized_Replace_Result(
+			$pre,
+			$rebuilt_serialized_string,
+			substr( $line_part, $next_slice_index )
+		);
+	}
+
+	/**
+	 * Apply replacements to a non-serialized part.
+	 *
+	 * @param string $part         The part to replace in.
+	 * @param array  $replacements Replacements.
+	 * @return string
+	 */
+	private function replace_by_part( $part, $replacements ) {
+		foreach ( $replacements as $replacement ) {
+			$part = str_replace( $replacement['from'], $replacement['to'], $part );
+		}
+
+		return $part;
+	}
+
+	/**
+	 * Locate a serialized string prefix.
+	 *
+	 * @param string $line_part Line chunk.
+	 * @return array|null
+	 */
+	private function find_serialized_prefix( $line_part ) {
+		$length = strlen( $line_part );
+
+		for ( $index = 0; $index < $length - 4; $index++ ) {
+			if ( 's' !== $line_part[ $index ] || ':' !== $line_part[ $index + 1 ] ) {
+				continue;
+			}
+
+			$digit_start = $index + 2;
+			if ( $digit_start >= $length || ! ctype_digit( $line_part[ $digit_start ] ) ) {
+				continue;
+			}
+
+			$digit_end = $digit_start;
+			while ( $digit_end < $length && ctype_digit( $line_part[ $digit_end ] ) ) {
+				$digit_end++;
+			}
+
+			if ( $digit_end >= $length || ':' !== $line_part[ $digit_end ] ) {
+				continue;
+			}
+
+			if ( $digit_end + 2 >= $length ) {
+				break;
+			}
+
+			if ( '\\' !== $line_part[ $digit_end + 1 ] || '"' !== $line_part[ $digit_end + 2 ] ) {
+				continue;
+			}
+
+			$raw_length = substr( $line_part, $digit_start, $digit_end - $digit_start );
+
+			return array(
+				'start'         => $index,
+				'raw_length'    => $raw_length,
+				'content_start' => $digit_end + 3,
+			);
+		}
+
+		return null;
+	}
+
+	/**
+	 * Convert an escaped sequence to its real character.
+	 *
+	 * @param string $pair Two-character escape sequence.
+	 * @return string
+	 */
+	private function get_unescaped_bytes_if_escaped( $pair ) {
+		if ( '' === $pair || '\\' !== $pair[0] ) {
+			return $pair;
+		}
+
+		$map = array(
+			'\\' => '\\',
+			"'"  => "'",
+			'"'  => '"',
+			'n'  => "\n",
+			'r'  => "\r",
+			't'  => "\t",
+			'b'  => "\x08",
+			'f'  => "\f",
+			'0'  => '0',
+		);
+
+		$second = isset( $pair[1] ) ? $pair[1] : '';
+
+		if ( '' !== $second && isset( $map[ $second ] ) ) {
+			return $map[ $second ];
+		}
+
+		return $pair;
+	}
+
+	/**
+	 * Unescape an entire content string.
+	 *
+	 * @param string $escaped Escaped content.
+	 * @return string
+	 */
+	private function unescape_content( $escaped ) {
+		$unescaped = '';
+		$length    = strlen( $escaped );
+		$index     = 0;
+
+		while ( $index < $length ) {
+			if ( '\\' === $escaped[ $index ] && $index + 1 < $length ) {
+				$pair     = substr( $escaped, $index, 2 );
+				$converted = $this->get_unescaped_bytes_if_escaped( $pair );
+				if ( 1 === strlen( $converted ) ) {
+					$unescaped .= $converted;
+					$index     += 2;
+					continue;
+				}
+			}
+
+			$unescaped .= $escaped[ $index ];
+			$index++;
+		}
+
+		return $unescaped;
+	}
+}
diff --git a/src/WP_CLI/Serialized_Replace_Result.php b/src/WP_CLI/Serialized_Replace_Result.php
new file mode 100644
index 00000000..49e5efce
--- /dev/null
+++ b/src/WP_CLI/Serialized_Replace_Result.php
@@ -0,0 +1,41 @@
+<?php
+
+namespace WP_CLI;
+
+/**
+ * Simple value object returned by FileSearchReplacer when processing serialized data.
+ */
+final class Serialized_Replace_Result {
+
+	/**
+	 * Text before the serialized portion.
+	 *
+	 * @var string
+	 */
+	public $pre;
+
+	/**
+	 * The rebuilt serialized portion (with updated length if needed).
+	 *
+	 * @var string
+	 */
+	public $serialized_portion;
+
+	/**
+	 * Text after the serialized portion.
+	 *
+	 * @var string
+	 */
+	public $post;
+
+	/**
+	 * @param string $pre                Text before the serialized portion.
+	 * @param string $serialized_portion The rebuilt serialized portion.
+	 * @param string $post               Text after the serialized portion.
+	 */
+	public function __construct( $pre, $serialized_portion, $post ) {
+		$this->pre                = $pre;
+		$this->serialized_portion = $serialized_portion;
+		$this->post               = $post;
+	}
+}