T-Regx uses a variety of exceptions to provide proper flow control.
Additionally, T-Regx is composed of two sub-systems:
- SafeRegex (which handles low-level PHP/PCRE integration, while keeping the API intact)
- CleanRegex (high-level API, which provides modern approach and eliminates false positives and false negatives, being consequence of PCRE).
Above everything else, we wanted to avoid a situation where T-Regx users would catch
\Exception to silence everything that comes out of
This is potentially dangerous since, while doing that, it's possible to unknowingly silence/ignore other exceptions thrown near T-Regx call.
That's why every T-Regx exception extends a common interface exception:
RegexException, which you can use to shut T-Regx up :)
RegexException, for certain arguments and methods
\InvalidArgumentException is thrown, when arguments of invalid types or
arguments that are semantically inappropriate are used.
For example, when
only() is used with negative index:
So to really catch every, single possible exception, you would need to catch both
\InvalidArgumentException. Nothing else could slip by.
We decided to separate
\InvalidArgumentException because we understand that sometimes, regular expression
exceptions are wanted. For example, you might expect to use them against data which is unsafe. In that case, catching
is a proper control of that case.
However, we don't really believe passing
only() is ever a good idea, even when it comes from an unsafe place. Methods
only() should never be called with arguments like
-1, that's why this exception is not
RegexException, and it won't fall into the
proper handling. It's most likely a mistake that shouldn't happen, and the developer should handle it in other way (for example, never
only() be called with
in the first place).
We tried really hard to design an exception structure in such a way, so it makes sense to the users, and so it resembles the real interaction of these two systems. Here's what we came up with.
We don't encourage it (since
PregException unifies a broad family of exceptions), but should you wish to silence
preg:: methods, that's
the way to do it.
PregException actually represents a family of exceptions:
Utf8OffsetPregException; which T-Regx throws when
MalformedPatternException; which T-Regx throws on warnings/errors emitted by PHP
Utf8OffsetPregException; which T-Regx throws for invalid subject encoding or invalid unicode offset
InvalidReturnValueExceptionwhich T-Regx throws for invalid value type returned from
SuspectedReturnPregExceptionwhich T-Regx throws when preg functions return values indicating error, but nature of the error couldn't be determined by other means
Additionally, because CleanRegex is built on top of SafeRegex, any SafeRegex exceptions can also be thrown with CleanRegex methods.
For example, it's possible to induce catastrophic backtracking with
pattern(), in that case
PregException) will be thrown.
It doesn't work the other way, so SafeRegex will never throw
Similarly to how
PregException unifies exceptions thrown from preg functions,
PatternException unifies exceptions thrown from
Pattern::inject(). Because of that, we don't recommend catching
PatternException, unless you
actually need to handle every exception thrown from those methods.
- Inappropriately constructed pattern being used:
- Match expectations weren't met:
- Improper replacement attempted, or replacement expectations weren't met:
- Capturing groups being used inappropriately:
- Optionals being resolved to exception:
- Non-integer string being used as integer:
We don't encourage you to catch
PatternException because of its broad usages, so please only do so when you wish to silence absolutely
every exception thrown from
pattern() and other CleanRegex methods.
To summarize everything so far:
\InvalidArgumentExceptionis being thrown for obvious illegal arguments
PregExceptionis thrown by SafeRegex and CleanRegex, regarding low-level operations
PatternExceptionis thrown by CleanRegex regarding higher-API operations
PregException | PatternException
...and CleanRegex methods: