regex-replace

The regex-replace operation rewrites part of a value using a pattern. You say what to find and what to put in its place, and every match is replaced.

Use it when you need to change a value rather than extract from it: inserting separators, stripping characters, reshaping an identifier.

How it works

Two parameters.

Pattern is the regular expression that finds what should be replaced. Write it without slashes around it, PalDock adds those.

Output is what replaces each match. Reference the pieces the pattern captured:

• $1, $2 and so on insert the first, second and further capturing groups
• $0 inserts the whole match

Pattern: (\d{6})(\d{4})
Output:  $1/$2
Value:   1234123456
Result:  123412/3456

The pattern makes two groups, six digits and four digits, and the output puts them back with a slash between them. Groups are numbered from left to right starting at one.

What happens when it does not work

• A pattern that matches nothing leaves the value exactly as it was. This is the safe case.

• A pattern that is not valid empties the field. A missing bracket, a stray modifier, and the result is nothing at all.

Those two look nothing alike in the data, which is useful: an unchanged value means your pattern was fine but did not apply, an empty one means the pattern itself is broken.

Writing the replacement

Prefer $1 over \1. Both work, but $1 is the recommended form and reads better.

Use ${1} when a digit follows the group number. ${1}1 is group one followed by the digit one, while $11 is read as group eleven.

To output a literal dollar sign followed by a number, escape it as \$1.

Writing the pattern

Write the raw expression with no slashes around it. If the value itself contains a slash, escape it inside the pattern.

For flags, put them inline at the start: (?i) for case insensitive, (?m) for multiline, (?s) to let the dot match newlines, (?u) for UTF-8.

Watch out for greedy matching. .* takes as much as it can, which is usually more than you meant. Use .*? when you want the shortest match, or describe the content precisely instead of using a wildcard at all.

Named groups work in the pattern, as (?P<name>\d{2}), but the replacement still refers to them by number.

Test the pattern first

Try it in regex101.com before pasting it in. You can see what matches, check the group numbering, and confirm the replacement does what you think.

This applies double if you had an AI write the pattern. They produce plausible expressions readily and correct ones less reliably, and here a wrong one either does nothing or empties the field.

Extracting rather than rewriting

regex-replace keeps the value and changes part of it. To pull a piece out and discard the rest, use first-regex-match.

Reference

See PHP: preg_replace and Pattern Modifiers.