pattern()->replace->callback(), some methods receive a callback that accepts
details object. These methods are:
The details can be used to get concise information about the matched occurrence, such as its value
"the whole match"), capturing groups and their UTF-8/raw offsets, limits, indexes, other matches as well as the
used subject (although it could also be pass as a closure parameter) and more.
For example, to read the offset at which the occurrence was matched, use
Detail details, you gain access to:
text()- value of a matched occurrence
isInt()which allow you to handle integers safely
subject()- subject against which the pattern was matched
index()- ordinal value of a matched occurrence
limit()- limit which was put on the matches
- offsets of matched values in the subject (UTF-8 safe):
- byte versions of the methods:
all()- other matched occurrences
- details about capturing groups, in the next chapter: Capturing groups
- User data - sharing custom data between callbacks
There are 6 similar ways to get the value of the matched occurrence.
or you can just accept
string in the callback signature.
All of them are redundant and equal to each other. Their redundancy comes from the fact the there are a few ways of
casting an object to string in PHP, casting
Detail to string is the same as getting
text() in T-Regx, and that the
whole match is also group
0 in regular expressions.
There's also UTF8-safe method
textLength() which, you guessed it, returns the length of a matched text.
true if, and only if, the matched occurrence is numeric. And by "numeric", we mean "real" numeric,
not PHP numeric:
- String values considered valid integers:
- Strings that aren't treated as valid integers:
The string is considered a valid integer if:
- contains only
0-9characters, and more than 1 of them (so
00is also a valid integer, but
- optionally starts with only one
- its numeric representation is:
- higher than
- lower than
- higher than
- doesn't contain any other characters
There are two methods regarding integers:
false depending on whether the matched occurrence is numeric.
returns said numeric occurrence as an integer, or throws
It's implemented with
filter_var(), but you can think of it as
/^-?\d+$/ with max/min values check.
To get the subject in your callback, use
This is equivalent to storing the subject in a variable and using it in your closure.
Detail.index() returns the ordinal number of a matched occurrence.
In this example, we'll modify every second word:
Detail.offset() can be used to get the offset of the matched occurrence in the subject.
Detail.offset() is multi-byte
character safe and returns offset in characters, whereas
Detail.byteOffset() returns the offset in bytes.
Here's what the numbers mean:
In other words,
offset() treats bytes
[226, 130, 172] as one multi-byte character (euro sign
€) and counts them as
byteOffset() would count them as three.
Detail.tail() simply returns the position of the last character in a matched occurrence.
Detail.byteTail() which returns the tail in bytes, instead of characters.
Detail has access to other matched occurrences:
Detail.all()- for whole matches (like
Detail.group().all()- for capturing groups (like
Even if you use
Detail.all() always returns unlimited occurrences.
Detail.group(string|int), you can easily retrieve capturing groups.
Just like with
Detail, retrieving matched occurrence value is done with
text() method or by casting it to
More about capturing groups can be found in the next section: Capturing groups.
To most users this functionality will occur as redundant - it's only use case are multiple calls to callbacks, for example
when using chained
filter()->map(). With user data, it's possible to perform an operation in
filter(), store its
value in user data, and then use the value in
map() without reference closure variables.