feat: add flag --replace-keys to handle replacing string array key values

[AlextheYounga]

Attempts to address #137 by adding an opt-in --replace-keys flag so string keys in serialized arrays can be replaced when needed.

wp search-replace currently traverses serialized values but skips array keys, which prevents some real-world migrations (e.g. sidebar keys, URL-keyed plugin options) from being updated. By default, existing behavior is unchanged: array keys are still ignored unless --replace-keys is explicitly provided.

What changed

• Added new command option:
  • --replace-keys: enables replacing string keys in serialized arrays.
• Wired the flag through command execution into SearchReplacer.
• Updated recursive replacement logic to:
  • replace array values as before
  • optionally replace string keys when --replace-keys is enabled
• Added acceptance coverage in Behat for:
  • no-flag baseline (keys remain unchanged)
  • basic key replacement
  • nested key replacement
  • key + value replacement
  • key-collision behavior
  • regex + replace-keys behavior

Testing

Ran targeted Behat scenarios for replace-keys behavior and edge cases:

• Search and replace serialized array keys with --replace-keys
• Search and replace nested serialized array keys with --replace-keys
• Search and replace key and value with --replace-keys
• Search and replace colliding serialized array keys with --replace-keys

🫡

[gemini-code-assist]

Code Review

This pull request introduces a new --replace-keys flag to the search-replace command, enabling string replacement within serialized array keys. The changes include updates to the command logic, the SearchReplacer class, and new Behat test scenarios. Feedback highlights a potential issue with in-place array modification during iteration which could cause data loss, and a breaking change in the SearchReplacer constructor signature that affects backward compatibility.

[gemini-code-assist]

Modifying the array in-place while iterating over its keys can lead to incorrect results and data loss. If a key is replaced with a name that exists later in the original array, the value associated with that new key will be overwritten before it is processed. Furthermore, the loop will eventually reach that new key and process the already-replaced value a second time.

To fix this, consider building a new array for the transformed data instead of modifying $data in-place. This ensures each original key-value pair is processed exactly once and correctly handles scenarios like key swaps.

Example fix:

$new_data = [];
foreach ( $data as $key => $value ) {
    $new_value = $this->run_recursively( $value, false, $recursion_level + 1, $visited_data );
    $new_key   = $key;
    if ( $this->replace_keys && is_string( $key ) ) {
        $new_key = $this->run_recursively( $key, false, $recursion_level + 1, $visited_data );
    }
    $new_data[ $new_key ] = $new_value;
}
$data = $new_data;

[gemini-code-assist]

The addition of the $replace_keys parameter in the middle of the constructor's argument list is a breaking change for the SearchReplacer class's public API. Any existing code calling this constructor with positional arguments (e.g., to set $regex or $logging) will now pass those values to the wrong parameters. It is recommended to append new parameters to the end of the argument list to maintain backward compatibility.

public function __construct( $from, $to, $recurse_objects = false, $regex = false, $regex_flags = '', $regex_delimiter = '/', $logging = false, $regex_limit = -1, $replace_keys = false ) {

[gemini-code-assist]

If the SearchReplacer constructor signature is updated to append $replace_keys at the end (to maintain backward compatibility), this call should be updated accordingly.

$replacer   = new SearchReplacer( $old, $new, $this->recurse_objects, $this->regex, $this->regex_flags, $this->regex_delimiter, false, $this->regex_limit, $this->replace_keys );

[gemini-code-assist]

If the SearchReplacer constructor signature is updated to append $replace_keys at the end (to maintain backward compatibility), this call should be updated accordingly.

$replacer = new SearchReplacer( $old, $new, $this->recurse_objects, $this->regex, $this->regex_flags, $this->regex_delimiter, null !== $this->log_handle, $this->regex_limit, $this->replace_keys );

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!