README

T-Regx | 正则表达式库

将PHP正则表达式提升到现代标准。

查看文档 - t-regx.com.

1. 安装
   • Composer
2. 示例
3. 文档
4. T-Regx fiddle - 在线尝试
5. API
   1. 对于标准项目 -pattern()
   2. 对于旧项目 - preg::match_all()
6. 概述
   1. 预定义模式
   2. 与开发者合作
   3. 干净的API
   4. 致命错误
   5. 干净代码
   6. 异常与错误
7. 比较
   1. 异常优于警告/错误
   2. 与开发者合作
   3. 使用干净的API编写
   4. Uncle Bob的“干净代码”哲学
8. 未来计划
9. 赞助商
10. 许可证

给我买杯咖啡！

安装

适用于PHP 7.1及以后版本（包括PHP 8）的安装

composer require rawr/t-regx

T-Regx只需要mb-string扩展。不需要其他依赖项或扩展。

示例

方法match()、test()和count()的示例。

$pattern = Pattern::of("ups"); // pattern("ups") also works
$matcher = $pattern->match('yay, ups');

foreach ($matcher as $detail) {
   $detail->text();    // (string) "ups";
   $detail->offset();  // (int) 0
}

if (!$matcher->test()) {
   echo "No occurrances found";
} else {
   echo "Found {$matcher->count()} occurrences";
}

文档

完整的API文档可在t-regx.com找到。变更列表可在ChangeLog.md中找到。

快速链接

• 简介 - https://t-regx.com/docs/introduction
  • 匹配概述 - https://t-regx.com/docs/match
  • 替换 - https://t-regx.com/docs/replace
  • 分割 - https://t-regx.com/docs/split
• 预定义模式 - https://t-regx.com/docs/prepared-patterns
  • 模板语法 - https://t-regx.com/docs/template-syntax
  • 模式列表 - https://t-regx.com/docs/pattern-list

在线尝试，在您的浏览器中！

打开T-Regx fiddle，在您的浏览器中开始尝试。 现在尝试！

API

选择接口

• 我选择现代正则表达式API

  滚动查看 - pattern()->test()，pattern()->match()，pattern()->replace()

• 我选择保留PHP方法（但会保护免受错误/警告的影响）

  滚动查看 - preg::match_all()，preg::replace_callback()，preg::split()

对于标准项目，我们建议使用pattern()。对于旧项目，我们建议使用preg::match_all()。

• 标准T-Regx

  $pattern = Pattern::of("ups"); // pattern("ups") also works
  $matcher = $pattern->match('yay, ups');
  
  if (!$matcher->test()) {
    echo "Unmatched subject :/";
  }
  
  foreach ($matcher as $detail) {
    $detail->text();    // (string) "ups";
    $detail->offset();  // (int) 0
  }
  
  $pattern->replace('well, ups')->with('heck') // (string) "well, heck";

• 旧版API

  try {
      preg::match_all('/?ups/', 'ups', $match, PREG_PATTERN_ORDER);
      echo $match[0][0];
  } catch (\TRegx\Exception\MalformedPatternException $exception) {
      echo "Invalid pattern";
  }

T-Regx为何脱颖而出？

💡 查看t-regx.com上的文档

• 预定义模式

  使用用户数据在PCRE中并不总是安全的（即使是使用preg_quote()），而且使用起来也不那么方便。T-Regx提供了针对构建包含不安全用户输入的模式的专业解决方案。选择Pattern::inject()以简单地将用户数据作为字面量包含在内。使用Pattern::mask()将用户提供的掩码转换为完整的模式，同时确保安全。使用Pattern::template()来构建更复杂的模式。

  function makePattern($name): Pattern {
    if ($name === null) {
      return Pattern::of("name[:=]empty");
    }
    return Pattern::inject("name[:=]@;", [$name]); // inject $name as @
  }
  
  $gibberish = "(my?name)";
  $pattern = makePattern($gibberish);
  
  $pattern->test('name=(my?name)'); // (bool) true

• 与开发者一起工作

  • 简单方法
    • T-Regx通过简单的方法暴露功能，这些方法返回int、string、string[]或bool，这些都不是可空的。如果您想对您的匹配项或模式做些什么，可能有一个方法可以做到这一点，它正好只做那件事。
  • 字符串
    • 使用多字节偏移量修复错误（UTF-8安全）.
    • 单独的方法用于位置
      • offset() - 返回匹配项在UTF-8字符中的位置
      • byteOffset() - 返回匹配项在字节中的位置，无论编码如何
  • 组

    • 当使用preg::match_all()时，我们收到一个数组，其中包含多个数组，然后是数组。相比之下，T-Regx返回一个组数组：Group[]。对象Group包含有关组的所有信息。

    • 组错误

      • 当使用无效的组名称get('!@#')时，T-Regx抛出\InvalidArgumentException。
      • 当尝试读取缺失的组时，T-Regx抛出NonexistentGroupException。
      • 当读取未匹配的组时，T-Regx抛出GroupNotMatchedException。

• 使用干净的API编写

  • 描述性、简单的接口
  • 开箱即用的Unicode支持
  • 没有使用反射，No (...varargs)，No (boolean arguments, true)，(No flags, 1)，[No [nested, [arrays]]]
  • T-Regx消除了PHP版本之间的不一致性

• 保护您免受致命错误的影响

  某些参数会导致preg_()方法出现致命错误，这会导致应用程序终止，并且无法捕获。T-Regx会预测给定的参数是否会导致致命错误，并将抛出一个可捕获的异常。

• T-Regx遵循Uncle Bob和“Clean Code”的哲学

  函数应该做一件事情，而且应该做好。函数应该做到您期望它做到的。

• 与其他工具和库兼容

  诚然，Pattern::of()接受未限定的模式（(Foo){3,4}}）与其他PHP库不兼容，这些库使用限定模式（/(Foo){3,4}/）工作，例如Laravel和路由。在这种情况下，使用接受普通标准PHP语法的PcrePattern::of()。

• 异常优于警告/错误

  • 与PHP方法不同，T-Regx不使用警告/通知/错误来处理意外输入

    try {
      preg::match_all('/([a3]+[a3]+)+3/', 'aaaaaaaaaaaaaaaaaaaa 3');
    } catch (\TRegx\SafeRegex\Exception\CatastrophicBacktrackingException $exception) {
      // caught
    }

  • 检测和抛出MalformedPatternException的malformed patterns。这不能用preg_last_error()捕获。

    try {
      preg::match('/?ups/', 'ups');
    } catch (\TRegx\Exception\MalformedPatternException $exception) {
      // caught
    }

  • 并非PHP中的每个错误都可以从preg_last_error()中读取，但是T-Regx为这些事件抛出专门的异常。

比较

或

正在进行中的工作

关于1.0版本发布的发展优先级

• 将SafeRegex和CleanRegex分开成两个包，以便用户可以选择他们需要的内容 #103
• 为每个T-Regx公共方法添加文档 #17 [进行中]
• 重新设计t-regx.com文档 [进行中]
• 发布1.0

赞助商

• Andreas Leathley - 开发SquirrelPHP
• BarxizePL - 感谢！

感谢以下贡献者开发T-Regx：

许可证

T-Regx采用MIT许可证。