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}')->test('123');

💡 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

// or use map()
pattern('\d{3}')->match('My phone is 456-232-123')->map('strlen');        // [3, 3, 3]

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

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('W.ll.by')
    ->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

Handle unsafe data or user input, in a modern, safe way (no more preg_quote()). Think of it as SQL Prepared Statements, but for regexps ;)

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

or

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

or even

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

Above patterns 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(), Pattern::bind() and Pattern::inject()

Optional matches

Not sure if your pattern is matched or not?

$result = pattern('word')->match($text)
  ->findFirst('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

  • Errors:
    • 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
    • Checks and clears errors and warnings, to verify your regexp match/replace.
  • Strings:
    • 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.

• 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, instead of a Fatal Error.

Ways of using T-Regx

// Static method style
use TRegx\CleanRegex\Pattern;

Pattern::of('[A-Z][a-z]+')->matches('Foo Bar');

// Global function style
pattern('[A-Z][a-z]+')->matches('Foo Bar');

// Old-school pattern
use TRegx\CleanRegex\Pattern;

Pattern::pcre('/[A-Z][a-z]+/i')->matches('Foo Bar');

💡 See more about entry points and pattern().

Safe regexps without changing your API?

Would you like to protect yourself from any notices, errors,fatal errors and warnings; and use exceptions instead?

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 and fatals.

Supported PHP versions

Continuous integration builds are running for:

• 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 (nightly)

What's better

or

T-Regx is developed thanks to

License

T-Regx is MIT licensed.