Skip to main content

Introduction to T-Regx

Documentation for version: 0.41.2

T-Regx provides clean API for regular expressions, as well as solving more complicated issues with PHP regex (like eliminating false positives, validating groups) and including features utterly missing in PHP: Prepared patterns, pattern lists, built-in alteration and more, as well as removing uncertainty with false negatives and false positives.

Entry points#

We have multiple entry methods to create Pattern, each with its own use case:

  • Standard pattern - Pattern::of('\d+')
  • Prepared patterns - to safely use user input in patterns (see Prepared Patterns)
  • Pattern lists - Pattern::list(['\d+', '[a-z]+']) to use many patterns at once
  • Literal string value - Pattern::literal('[]?') (identical to Pattern::of('\[\]\?'))

Additionally, compatibility API remains available, which accepts delimiters

  • Compatibility legacy - PcrePattern::of('/\d+/m') to use vanilla patterns

Additionally, helper pattern() is available as a shorthand for Pattern::of().

Standard pattern#

use TRegx\CleanRegex\Pattern;
Pattern::of('[A-Z][a-z]+')->test($subject);

Additionally, as a convenience method, pattern() global function is just an alias for Pattern::of().

pattern('/[A-Z]#[a-z]+')->test($subject);

T-Regx prepared patterns#

With Pattern::inject(), placeholder @ is being bound the figures passed as the second argument of Pattern::inject().

use TRegx\CleanRegex\Pattern;
/**
* Example of prepared patterns
*/
$pattern = Pattern::inject('^\d+:@$', [$_GET['user']]);
/**
* Test your pattern against subject "14:mark"
*/
$pattern->test('14:mark'); // true, if $_GET['user'] == 'mark'

You can learn more about prepared patterns in Prepared Patterns.

Pattern lists in T-Regx#

Using Pattern::list() results an instance of PatternList, which contains the list of the patterns. PatternList exposes multiple methods which act on the list of patterns. It is preferable to call PatternList.testAny() instead of calling Pattern.test() in a loop, since PatterList will use performance optimisations.

<?php
/**
* @var PatternList $patternList
*/
$patternList = Pattern::list([
'\d+',
'[a-z]+'
]);
/**
* Check if any of the pattern matches the subject
*/
$patternList->testAny($_GET['input']);

Pattern:list() also accepts instances of Pattern. Any T-Regx method that instantiates Pattern can be used with Pattern::list().

<?php
/**
* @var PatternList $patternList
*/
$patternList = Pattern::list([
'\d+',
Pattern::of('\d+'),
Pattern::inject(':?@', ['value']),
PcrePattern::of('/[a-z]+/')
]);

Passing string into Pattern::list() is the same as passing that very same string in Pattern::of() before adding it to the list.

PatternList cannot contain other instances of PatternList.

You can learn more about Pattern::list() in Multiple patterns.

Deliberate delimiters#

If pattern() or Pattern::of() is used with a delimited pattern, then characters "/" will simply be treated literally

<?php
pattern('/[A-Z]/'); // matches characters "/", a letter and "/"

Compatibility patterns#

Delimited patterns are still supported for completeness with flags, with PcrePattern::of(). Both versions are equal with each other.

$pattern = Pattern::of('[A-Z]+', 'im');
$pattern = PcrePattern::of('/[A-Z]+/im');
$pattern->test($subject)

They are particularly useful when T-Regx is used with other libraries, which return delimited regular expressions. If the Pattern is instantiated with PcrePattern, then it behaves exactly as the input regular expression would. There are certain fixed that T-Regx performs on the input, but they are kept to a minimal proportion.

An example of such change could be token \c\, which works fine with PcrePattern/Pattern, but fails with preg_match().

Last updated on