rawr/t-regx

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

Maintainers

Details

github.com/T-Regx/T-Regx

Source

Issues

Fund package maintenance!
Danon

v0.9.9 2020-04-25 00:14 UTC

This package is auto-updated.

Last update: 2020-07-10 16:35:35 UTC


README

T-Regx

68747470733a2f2f7472617669732d63692e6f72672f542d526567782f542d526567782e7376673f6272616e63683d6d6173746572 68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f542d526567782f542d526567782f62616467652e7376673f6272616e63683d6d6173746572 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f537461626c652d76302e392e392d627269676874677265656e2e7376673f7374796c653d706f706f7574 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d302d627269676874677265656e2e737667

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.

last commit commit activity Unit tests FQN PRs Welcome

PHP Version PHP Version PHP Version PHP Version PHP Version

  1. Installation
  2. Documentation
  3. Examples
  4. Overview
  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:
  • 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

Ugly api

or

Pretty api

T-Regx is developed thanks to

JetBrains

License

T-Regx is MIT licensed.