Add --old and --new flags to support strings starting with hyphens

[Copilot]

Fix for Search-Replace Command with Hyphenated Words

The issue is that WP-CLI's argument parser treats strings starting with -- as flags/options instead of positional arguments. This prevents users from searching for strings like "--old-word".

Solution

Added two new optional flags --old=<value> and --new=<value> that can be used instead of positional arguments when the search/replacement strings start with --.

The implementation provides flexible usage: you can mix one flag with one positional argument, but cannot use both flags along with positional arguments to avoid confusion.

Changes Made

1. Added new flags: --old and --new as optional alternatives to positional arguments
2. Updated argument handling:
   • Checks for flags individually, falling back to positional arguments
   • Prevents confusing scenarios where both flags are used with positional arguments
   • Allows flexible mixing (e.g., --old='value' with positional new)
   • Validates that values are non-empty strings
3. Improved error messages: Added context-aware error messages explaining workarounds when arguments are missing
4. Added documentation: Updated docblock with flag descriptions and usage examples
5. Added comprehensive tests: Created Behat test scenarios covering all edge cases:
   • Double-hyphen strings with flags
   • Missing arguments
   • Only --old flag without --new (errors)
   • Only --new flag without --old (errors)
   • Both flags with positional args (errors)
   • Empty strings via flags (errors)
   • Single-hyphen strings (works with positional args)
   • Flexible mixing of one flag with one positional arg

Example Usage

# Old way (doesn't work for strings starting with --)
wp search-replace "--old-word" "new-word"  # Error: unknown --old-word parameter

# New way (works with the new flags)
wp search-replace --old='--old-word' --new='new-word'

# Traditional usage still works
wp search-replace 'foo' 'bar'

# Flexible mixing is allowed
wp search-replace --old='--problem' 'solution'

# Single hyphens work with positional args
wp search-replace '-word' '-replacement'

Backward Compatibility

The change is fully backward compatible. Users can still use positional arguments as before.

Testing

• ✅ All linting checks pass
• ✅ Code style (PHPCS) checks pass
• ✅ Static analysis (PHPStan) passes
• ✅ No security vulnerabilities detected
• ✅ Comprehensive Behat test scenarios added covering all edge cases

Original prompt

---

This section details on the original issue you should resolve

<issue_title>I can not replace a word with several hyphens in its name</issue_title>
<issue_description>I use: wp search-replace "--old-word" "new word"

Error: unknown --old-word parameter</issue_description>

<agent_instructions>See #150 / https://gist.github.com/danielbachhuber/6c398217cff94e8a23a94b6b23aca3aa for a previous attempt</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes I can not replace a word with several hyphens in its name #132

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.