Start with SafeRegex
Here are the absolute basics you need to get familiar with, before we can learn T-Regx.
Overview - T-Regx duality
When you add T-Regx to your project, you can actually choose the API, with which you are most comfortable.
SafeRegex
- the wrapper on PCRE (making thepreg_
methods throw exceptions).CleanRegex
- the higher-level API, build on top ofSafeRegex
.
You can work with either or both them in your project - they're both part of T-Regx.
We suggest, after installing T-Regx, to use SafeRegex everywhere you can (to protect yourself against obvious errors),
and then gradually migrate from preg::
(SafeRegex) to pattern()
(CleanRegex).
About SafeRegex
With SafeRegex, you can safely replace every preg_
method with preg::
. It handles any possible preg_
error:
- runtime errors (malformed subject, malformed utf8),
preg_last_error()
codes. - preg compile errors, preg syntax errors, warnings/notices with
error_get_last()
. - invalid input arguments, invalid callback return values.
- Additionally, sometimes certain arguments (like
false
,null
) or other unexpected parameters causepreg_
to misbehave in strange ways. In those cases, SafeRegex also throws exceptions. - Some arguments cause
preg_
methods to throw fatal errors. SafeRegex handles them as well with a proper exception, preventing fatal errors.
Anything! If something's not right with preg_
- SafeRegex will throw a proper exception, you can be sure of that).
You should replace this code in your project:
...with SafeRegex methods (which never return false
/null
and map errors to exceptions):
or just :)
You don't need !== false
anymore, because preg::match()
never returns error-indicating values like
false
, null
, ""
or -1
. Proper exception is throw in case of an error.
You don't need to call preg_last_error()
either, because in case of runtime errors/warnings, preg::
throws
proper exceptions as well!
Each preg_
method (like preg_replace()
, preg_split()
) has its own SafeRegex wrapper (e.g. preg::replace()
, preg::split()
, etc.).
What does SafeRegex do
In fact, you should replace every preg_match()
with preg::match()
, preg_replace()
with preg::replace()
, right away! It's very safe, since their APIs are exactly the same.
SafeRegex (preg::
methods) is an exact copy of preg_
methods, but with additional safety features built-in.
Most importantly:
- On error,
preg_match()
would returnfalse
, and you need to usepreg_last_error()
to see the error code.preg::match()
, on the other hand, will throw a proper exception, depending on the nature of the error. - When building a pattern, PHP would raise a compile-time warning/error, which is impossible to try/catch or react to.
SafeRegex will just throw
MalformedPatternException
. - When passing invalid arguments (
null
,[]
, objects) by accident into some PCRE methods, you might actually cause a fatal error, that terminates the application.preg::
methods in any of those case will just throwInvalidReturnValueException
. preg_quote()
quotes different characters on different PHP versions, whereaspreg::quote()
works consistently everywhere.- Most of
preg_()
methods ignore invalid arguments,preg::()
methods throw\InvalidArgumentException
in that case.
There are other safety features added by SafeRegex, like PHP bug fixes.
Mix and match
In Vanilla-PHP, if you mix and match multiple calls to preg
methods, like maybe calling preg_match()
,
preg_replace()
, and preg_split()
right after each other, it may be really difficult to figure out
which method was prone to error.
SafeRegex can always narrow down the error to the exact method to one particular call (even nested ones,
like malformed preg call inside preg_replace_callback()
):
Basically, SafeRegex can isolate the preg call to one method.
But don't worry! T-Regx doesn't touch set_error_handler()
nor set_exception_handler()
, you can be sure of that! :)
Word about exceptions
When using preg::...()
methods, any error-prone situation is handled with an exception. Not only will it
give you insight about the nature of the error (MalformedPattern
, CatastrophicBacktracking
, utf8 exceptions),
it will allow you to get even more details with the methods on the exception:
Final words
That's it about SafeRegex! Really!
SafeRegex method names, arguments, return types are exactly the same as vanilla PHP preg_
methods, so you only
need to change preg_
to preg::
and you're already protected against every compile-time or runtime warning/error/notice, magic value and other code-smells
present in PCRE. Every callback, flag, argument is copied 1:1. In terms of programming usage - they're identical. The
only difference is preg::
instead of preg_
.
In the next chapters, we'll talk about CleanRegex - the higher level API solving more complicated problems of PHP regular expressions, other than the complete lack of exceptions.