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 the
preg_methods throw exceptions).
CleanRegex- the higher-level API, build on top of
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
With SafeRegex, you can safely replace every
preg_ method with
preg::. It handles any possible
- runtime errors (malformed subject, malformed utf8),
- preg compile errors, preg syntax errors, warnings/notices with
- invalid input arguments, invalid callback return values.
- Additionally, sometimes certain arguments (like
null) or other unexpected parameters cause
preg_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
null and map errors to exceptions):
or just :)
You don't need
!== false anymore, because
preg::match() never returns error-indicating values like
-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,
proper exceptions as well!
preg_ method (like
preg_split()) has its own SafeRegex wrapper (e.g.
What does SafeRegex do
In fact, you should replace every
preg::replace(), right away! It's very safe, since their APIs are exactly the same.
preg:: methods) is an exact copy of
preg_ methods, but with additional safety features built-in.
- On error,
false, and you need to use
preg_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
- When passing invalid arguments (
, 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 throw
preg_quote()quotes different characters on different PHP versions, whereas
preg::quote()works consistently everywhere.
- Most of
preg_()methods ignore invalid arguments,
\InvalidArgumentExceptionin 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_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
Basically, SafeRegex can isolate the preg call to one method.
But don't worry! T-Regx doesn't touch
set_exception_handler(), you can be sure of that! :)
Word about exceptions
preg::...() methods, any error-prone situation is handled with an exception. Not only will it
give you insight about the nature of the error (
CatastrophicBacktracking, utf8 exceptions),
it will allow you to get even more details with the methods on the exception:
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:: 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
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.