README

T-Regx | Powerful Regular Expressions library

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

See documentation.

1. Installation
   • Composer
2. API
3. Quick Examples
   • Automatic delimiters
   • Matching
   • Replacing
   • Prepared Patterns
   • Optional matches
4. Overview
   • Why T-Regx stands out?
   • Ways of using T-Regx
   • Converting warnings to Exceptions
5. Supported PHP versions
6. Comparison
7. License

Installation

Installation for PHP 7.1 and later:

composer require rawr/t-regx

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().

💡 See also: replace()->by()->group() and replace()->by()->map().

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]]]

• Protects your from fatal errors

  • Certain arguments cause fatal errors with preg_() methods.
  • T-Regx will throw a catchable exception in those cases.

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

or

T-Regx is developed thanks to

License

T-Regx is MIT licensed.