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
4. Overview
   • Why T-Regx stands out?
   • Ways of using T-Regx
   • Converting warnings to Exceptions
5. What's better?
6. Supported PHP versions
7. Comparison

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

$s = 'My phone is 456-232-123';

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

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

pattern('\d{3}')->match($s)->first('str_split');   // ['4', '5', '6']
pattern('\d{3}')->match($s)->first('strlen')       // 3

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

Replacing

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

// 'P. Sh__man, 42 Wall__y w__'

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

// 'P. ShERman, 42 Wallaby way'

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

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

• Working with the developer

  • Not even touching your error handlers in any way
  • Converts all PCRE notices/error/warnings to exceptions
  • Tracking offset and subjects while replacing strings
  • Fixing error with multi-byte offset (utf-8 safe)

• Written with clean API

  • Descriptive interface
  • SRP methods, UTF-8 support
  • No varargs, No flags, No boolean arguments, No nested arrays, No Reflection used

• 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.

Ways of using T-Regx

// Facade style
use TRegx\CleanRegex\Pattern;

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

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

// Separate API for preg_*() methods, that catches warnings and throws Exceptions
preg::match('/\w+/', $subject);
preg::match_all('/\w+/', $subject);
preg::replace('/\w+/', $replacement, $subject);
preg::replace_callback('/\w+/', $callback, $subject);
// all preg_ methods

💡 See more about entry points and pattern().

SafeRegex

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
}

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.3, PHP 7.0.31 (oldest and most recent)
• PHP 7.1.12, PHP 7.1.13, PHP 7.1.21
• PHP 7.2.9 (newest)

What's better

or