README

T-Regx | Regular Expressions library

PHP regular expressions brought up to modern standards.

You, choose the interface:

• I choose to keep PHP methods (but with exceptions, instead of warnings) (Scroll to see)
• I choose the modern regular expression API (Scroll to see)

See documentation at t-regx.com.

1. Installation
   • Composer
2. Documentation
3. 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

Documentation

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

Examples

Automatic delimiters

pattern('\d{3}')->test('123');  // true

💡 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:

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

// 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('sentence')
  ->findFirst('strtoupper')
  ->orElse(function (NotMatched $notMatched) {
    return "Match not found in " . $notMatched->subject();
  });

$result   // 'Match not found in sentence'

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

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
    • Warnings/errors don't interfere with each other
    • Preventing fatal errors (instead of catching them)
  • 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 PregException on warning/error.
  • In some cases, preg_() methods might fail, return false/null and NOT trigger a warning. Separate exception, SuspectedReturnPregException 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::! 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 (PregException $e) {
    $e->getMessage(); // `preg_replace_callback(): 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.

Supported PHP versions

Continuous integration builds are running for:

• PHP 7.1 (7.1.0, 7.1.12, 7.1.13, 7.1.27)
• PHP 7.2 (7.2.0, 7.2.15, 7.2.28)
• PHP 7.3 (7.3.0, 7.3.6, 7.3.15)
• PHP 7.4 (7.4.0, 7.4.3)
• PHP 8.0 (nightly)

What's better

or

T-Regx is developed thanks to

License

T-Regx is MIT licensed.