Replace with a constant value

After replace(), you need to explicitly use one of first()/all()/only(int) methods, to express how many replacements should be done.

Specifying limits is done to relieve you from brain strain - so you can immediately recognize author's intentions.

Limits#

Using first()/all()/only(int) is semantically identical to passing $limit argument to preg_replace()/preg_replace_callback().

First occurrence - first()#

$subject = 'I like scandinavia: Sweden, Norway and Denmark';
pattern('[A-Z][a-z]+')->replace($subject)->first()->with('___');
'I like scandinavia: ___, Norway and Denmark'

All occurrences - all()#

$subject = 'I like scandinavia: Sweden, Norway and Denmark';
pattern('[A-Z][a-z]+')->replace($subject)->all()->with('___');
'I like scandinavia: ___, ___ and ___'

Limited occurrences - only()#

$subject = 'I like scandinavia: Sweden, Norway and Denmark';
pattern('[A-Z][a-z]+')->replace($subject)->only(2)->with('___');
'I like scandinavia: ___, ___ and Denmark'

Read on, to learn more about replacing with a callback.

Regular expression references#

Normally, had you passed a replacement to preg_replace(), that contains a backslash or a dollar sign followed by a number (eg. \1 or $2) - that reference would be replaced by a corresponding capturing group (or by an empty string, if the group wasn't matched).

preg::replace('/(\d+)cm/', '<$1>', 'I have 15cm and 192cm');
I have <15> and <192>

Resolving such references won't happen using with().

This is done to relieve you from the brain strain. A programmer should be able to merely replace a string with a constant value without cognitive load about possible \ or $ hiding somewhere.

pattern('(\d+)cm')->replace('I have 15cm and 192cm')->all()->with('<$1>');
I have <$1> and <$1>

You can be sure, what's put into with() will certainly be present unchanged in your final result.

Some replacement strings containing a backslash or a dollar sign (like file system paths, URL addresses or even user input) might interfere with logic and cause bugs that are very hard to find.

note

Neither of types of references are resolved: $12, \12 nor ${12}.

PHP-style intentional references#

If you, however, would like to intentionally use regular expression references and have validated your input against an unexpected \ or $ - feel free to use withReferences() which will resolve replacement references.

pattern('(\d+)cm')->replace('I have 15cm and 192cm')->all()->withReferences('<$1>');
I have <15> and <192>

However, this is not recommended. For that, try using replace()->by()->group() or replace()->callback().

The only valid use-cases for withReferences() is:

note

Using withReferences() is not recommended. Instead, try using with(), by()->map() or callback().

We don't encourage its usage, but we're keeping it nonetheless, to allow users to decide for themselves whether they want to use T-Regx API, or stay with PHP replace style.

Remove occurrence#

There are times when you'd like to simply remove the occurrence of a pattern from your subject. To do that, use pattern()->remove() instead of pattern()->replace():

pattern('[cm]m')->remove('I have 15cm and 192cm')->all();
I have 15 and 192

It's actually identical to calling replace()->with('') under the hood, but it's a bit shorter and more expressive.

Last updated on