README

T-Regx | Powerful Regular Expressions library

The most advanced PHP regexp library. Clean, descriptive, fast wrapper functions enhancing PCRE methods.

Installation
- Composer
API
Quick Examples
Overview
Supported PHP versions
Comparison
License

Installation

Installation for PHP 7.1 and later:

composer require rawr/t-regx

💡 See documentation if you need to use earlier versions of PHP.

API

Full API documentation is available at t-regx.com.

Quick Examples

Automatic delimiters

These calls are identical:

pattern('\d{3}')->match()
pattern('/\d{3}/')->match()

💡 See more about automatic delimiters

Matching

pattern('\d{3}')->match('My phone is 456-232-123')->first();  // '456'
pattern('\d{3}')->match('My phone is 456-232-123')->all();    // ['456', '232', '123']
pattern('\d{3}')->match('My phone is 456-232-123')->only(2);  // ['456', '232']

You can pass any callable to the first() method:

pattern('\d{3}')->match('My phone is 456-232-123')->first('str_split');   // ['4', '5', '6']
pattern('\d{3}')->match('My phone is 456-232-123')->first('strlen')       // 3

💡 See more about first(), all() and only($limit).

Replacing

pattern('er|ab|ay')
    ->replace('P. Sherman, 42 Wallaby way')
    ->all()
    ->with('__$1__');

// 'P. Sh__$1__man, 42 Wall__$1__y w__$1__'

pattern('er|ab|ay')
    ->replace('P. Sherman, 42 Wallaby way')
    ->first()
    ->callback('strtoupper');

// 'P. ShERman, 42 Wallaby way'

💡 See more about replace()->with() / replace()->withReferences() and replace()->callback().

Prepared Patterns

Pattern::inject('(You|she) (are|is) @link (yours|hers)', [
    'link' => 'https://t-regx.com/docs/prepared-patterns'
]);

Above pattern can match both:

You are https://t-regx.com/docs/prepared-patterns hers
She is https://t-regx.com/docs/prepared-patterns yours

Check out prepared patterns with Pattern::prepare() and Pattern::inject()!

Optional matches

Not sure if your pattern is matched or not?

$result = pattern('word')->match($text)
  ->forFirst('strtoupper')
  ->orThrow(InvalidArgumentException::class);

$result   // 'WORD'

💡 See more about orThrow(), orElse(callback) or orReturn(var).

Overview

Why T-Regx stands out?

💡 See documentation at t-regx.com

Working with the developer
- Not even touching your error handlers in any way
- Converts all PCRE notices/error/warnings to exceptions
- Calling preg_last_error() after each call, to validate your method
- Tracking offset and subjects while replacing strings
- Fixing error with multi-byte offset (utf-8 safe)
Automatic delimiters for your pattern

Surrounding slashes or tildes (/pattern/ or ~patttern~) are not compulsory. T-Regx's smart delimiter will conveniently add one of many delimiters for you, if they're not already present.
Converting Warnings to Exceptions
- Warning or errors during preg:: are converted to exceptions.
- preg_() can never fail, because it throws SafeRegexException on warning/error.
- In some cases, preg_() methods might fail, return false/null and NOT trigger a warning. Separate exception, SuspectedReturnSafeRegexException is then thrown by T-Regx.
Written with clean API
- Descriptive interface
- SRP methods, UTF-8 support
- No Reflection used, No (...varargs), No (boolean arguments, true), (No flags, 1), [No [nested, [arrays]]]

Ways of using T-Regx

// Class static method style
use TRegx\CleanRegex\Pattern;

Pattern::of('[A-Z][a-z]+')->matches($subject)

// Global function style
pattern('[A-Z][a-z]+')->matches($subject)

💡 See more about entry points and pattern().

Safe regexps without changing your API?

Would you like to protect yourself from any notices, errors and warnings?

Just swap preg_ to preg:: and yay! All warnings and errors are converted to exceptions!

try {
    if (preg::match_all('/^https?:\/\/(www)?\./', $url) > 0) {
    }

    return preg::replace_callback('/(regexp/i', $myCallback, 'I very much like regexps');
}
catch (SafeRegexException $e) {
    $e->getMessage(); // `preg_replace_callback(): Compilation failed: missing ) at offset 7`
}

if (preg::match('/\s+/', $input) === false) {
    // Never happens
}

preg:: is an exact copy of preg_ methods, but catches all warnings, exceptions and calls preg_last_error() after each call.

The last line never happens, because if match failed (invalid regex syntax, malformed utf-8 subject, backtrack limit exceeded, any other error) - then SafeRegexException is thrown.

You can try/catch it, which is impossible with warnings.

Supported PHP versions

T-Regx has 2 production branches: master and master-php5.3. As you might expect, master is the most recent release. Ever so often master is being merged master-php5.3 and the most recent changes are also available for PHP 5.3+ - < 7.1.0.

master-php5.3 runs on PHP 5.3 - it just works
master runs on PHP 7.1.3 - withscalar params, nullable types, return type hints, PREG_EMPTY_AS_NULL, error_clear_last(), preg_replace_callback_array, etc.

Continuous integration builds are running for:

PHP 5.3.0, PHP 5.3.29 (oldest and most recent)
PHP 5.4.45 (newest)
PHP 5.5.38 (newest)
PHP 5.6.24 (newest)
PHP 7.0 (7.0.3, 7.0.31 - oldest and most recent)
PHP 7.1 (7.1.0, 7.1.12, 7.1.13, 7.1.21)
PHP 7.2 (7.2.0, 7.2.15)
PHP 7.3 (7.3.0, 7.3.1, 7.3.2, 7.3.0RC1, 7.3.3, 7.3.4, 7.3.5)
PHP 7.4
PHP 8.0

What's better

T-Regx is developed thanks to

License

T-Regx is MIT licensed.

rawr/t-regx

Maintainers

Details