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


README

T-Regx

Build status Integration tests 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f537461626c652d76302e31332e382d627269676874677265656e2e7376673f7374796c653d706f706f7574 68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d302d627269676874677265656e2e737667

T-Regx | Regular Expressions library

PHP regular expressions brought up to modern standards.

See documentation at t-regx.com.

last commit commit activity Unit tests Repository size FQN PRs Welcome

PHP Version PHP Version PHP Version PHP Version PHP Version PHP Version

  1. Installation
  2. API
  3. Documentation
  4. T-Regx fiddle - Try online
  5. Overview
  6. Comparison
  7. License

Installation

Installation for PHP 7.1 and later (PHP 8 as well):

composer require rawr/t-regx

API

You, choose the interface:

  • I choose to keep PHP methods (but protected from errors):

    Scroll to see - preg::match_all(), preg::replace_callback(), preg::split()

  • I choose the modern regex API:

    Scroll to see - pattern()->test(), pattern()->match(), pattern()->replace()

For legacy projects, we suggest preg::match_all(), for standard projects, we suggest pattern().

Current work in progress

Current development priorities, regarding release of 1.0:

  • Separate SafeRegex and CleanRegex into to two packages, so users can choose what they want #103
  • Add documentation to each T-Regx public method #17 [in progress]
  • Release 1.0
  • Revamp of t-regx.com documentation [in progress]

Documentation

Full API documentation is available at t-regx.com. List of changes is available in ChangeLog.md.

Try it online, in your browser!

Open T-Regx fiddle and start playing around.

Why T-Regx stands out?

💡 See documentation at t-regx.com

  • No change in API!

    • You can use T-Regx safe features and exception-based error handling, without changing your API.

      Simply swap preg_match() to preg::match(), and your method is safe! Arguments and return types remain the same.

  • Prepared patterns

    Using user data (for example with preg_quote()) isn't always safe with PCRE, as well as just not being that convenient to use. T-Regx provides Pattern::inject(), designed specifically for handling potentially unsafe data. Pattern::mask() allows converting user-supplied masks into full-fledged patterns safely.

  • Working with the developer

  • Automatic delimiters for your pattern

    Surrounding slashes or tildes (/pattern/ or ~patttern~) are not compulsory.

  • Converting Warnings/Errors to Exceptions

    • Detects malformed patterns in preg_() (which is impossible with preg_last_error()).
    • Notices, warnings 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, chainable interface
    • SRP methods
    • UTF-8 support out-of-the-box
    • 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.

What's better

Ugly api

or

Pretty api

Sponsors

About coverage

We achived 100% coverage in T-Regx something about a year ago. We developed our library with the most rigorous TDD we could achieve, and got to 97% pretty easily. Then we used coverage to find the cases that weren't covered, and written unit tests, interaction tests and feature tests for those. And we didn't do that to bump the coverege, no, we did that to ensure the contracts and behaviours in the application, and most importantly, to reduce bugs. We think we did well.

But now that we had 100% coverage, it became useless. I mean, yes, it was 100% but what could we do with it? When we had less than 100% at least we could use it to find places which aren't covered, we knew we squrewed up and had to look for more behaviorus and contracts to test. Now that we have 100%, we can't use it anymore. It became useless.

In order to make coverage usable again, we excluded feautre tests and integration tests from the coverage reports. The tests are still being run by us during the development, and they still run in the CI, but we're ignoring it in the coverage. Only unit tests are covered by the coverage now. The second we did that, the coverage dropped to 40%. That's good, it gives us two things! First, it lets us know that not only everything is covered by feature tests and integration tests, but also more than half of the library is covered in unit tests. Secondly, now we exactly know what parts of the application aren't covered by unit tests. We can use it! Now, the coverage can actually help us again. When we cover more cases with unit tests and reach 100% again, then sadly, coverage will cease to be a useful tool for good, at which point we'll probably dismiss using it.

  • Integration tests Integration tests
  • Unit tests Unit tests

T-Regx is developed thanks to

JetBrains

License

T-Regx is MIT licensed.