README

使用方法在 PHP 中流畅地创建正则表达式。这比编写普通的正则表达式更直观易懂。

安装

通过 Composer

composer require chriskonnertz/regex

从那时起，您可以通过运行 composer update 来获取此库的最新版本。

即使不使用 Composer，也可以使用此库，但此时必须注册一个 自动加载函数。

此库需要 PHP 7.0 或更高版本。

使用示例

以下是一个示例。它假设存在一个自动加载器。

$regEx = new ChrisKonnertz\RegEx\RegEx();

$regEx->addAnd('http')
      ->addOption('s')
      ->addAnd('://')
      ->addOption('www.')
      ->addWordChars()
      ->addAnd('.')
      ->addWordChars();
      
echo $regEx;

这将打印出 /(?:http)(?:s)?(?:\:\/\/)(?:www\.)?(?:\w+)(?:\.)(?:\w+)/ 并
与例如 https://www.example.org 匹配。这个正则表达式并不美观。然而，它是有效的。

请注意，特殊字符将被引号引用：123-456 将变为 123\-456。您可以通过调用 addRaw() 方法来避免这种行为。

更多示例

以下是如何创建嵌套正则表达式的示例

$regEx = new ChrisKonnertz\RegEx\RegEx();

$regEx->addRaw(new RangeEx('a-zA-Z'), '+');

echo $regEx;

这将打印出 [a-zA-Z]+（附带一些额外内容）。

重新使用 RegEx 对象是这样做的

$regEx = new ChrisKonnertz\RegEx\RegEx();

$regEx->addAnd('First test);
echo $regEx;

$rexEx->clear()->addAnd('Second test');
echo $regEx;

clear() 方法将重置 RegEx 对象，以便您可以重用它来构建新的正则表达式。

构建器方法

示例结果可能与实际输出不同。其中一些被简化，以便更容易理解。

addAnyChar

$regEx->addAnyChar();

添加一个部分表达式，该表达式期望任何单个字符（默认情况下不是“换行符”）。

结果正则表达式字符串的示例：.

匹配字符串的示例：a，1

addAnyChars

$regEx->addAnyChars();

添加一个部分表达式，该表达式期望 1..n 个任何字符（默认情况下不是“换行符”）。

结果正则表达式字符串的示例：.+

匹配字符串的示例：a，a1

addMaybeAnyChars

$regEx->addMaybeAnyChars();

添加一个部分表达式，该表达式期望 0..n 个任何字符（默认情况下不是“换行符”）。

结果正则表达式字符串的示例：.*

匹配字符串的示例：a，a1，空字符串

addDigit

$regEx->addDigit();

添加一个部分表达式，该表达式期望单个数字。等同于：[0-9]

结果正则表达式字符串的示例：\d

匹配字符串的示例：1，0

addDigits

$regEx->addDigits();

添加一个部分表达式，该表达式期望 1..n 个数字。等同于：[0-9]+

结果正则表达式字符串的示例：\d+

匹配字符串的示例：1，12

addMaybeDigits

$regEx->addMaybeDigits();

添加一个部分表达式，该表达式期望 0..n 个数字。等同于：[0-9]*

结果正则表达式字符串的示例：\d*

匹配字符串的示例：1，12，空字符串

addNonDigit

$regEx->addNonDigit();

添加一个部分表达式，该表达式期望一个非数字字符。等同于：[^0-9]

结果正则表达式字符串的示例：\D

匹配字符串的示例：a，-

addNonDigits

$regEx->addNonDigits();

添加一个部分表达式，该表达式期望 1..n 个非数字字符。等同于：[^0-9]+

结果正则表达式字符串的示例：\D+

匹配字符串的示例：a，ab

addMaybeNonDigits

$regEx->addMaybeNonDigits();

添加一个部分表达式，预期0..n个非数字字符。等同于：[^0-9]*

结果正则表达式的示例：\D*

匹配字符串的示例：a，ab，空字符串

addLetter

$regEx->addLetter();

添加一个部分表达式，预期一个字母。

结果正则表达式的示例：[a-zA-Z]

匹配字符串的示例：a，Z

addLetters

$regEx->addLetters();

添加一个部分表达式，预期1..n个字母。

结果正则表达式的示例：[a-zA-Z]+

匹配字符串的示例：a，aB

addMaybeLetters

$regEx->addMaybeLetters();

添加一个部分表达式，预期0..n个字母。

结果正则表达式的示例：[a-zA-Z]*

匹配字符串的示例：a，aB，空字符串

addWordChar

$regEx->addWordChar();

添加一个部分表达式，预期一个单词字符。这包括字母、数字和下划线。等同于：[a-zA-Z_0-9]

结果正则表达式的示例：\w

匹配字符串的示例：a，B，1

addWordChars

$regEx->addWordChars();

添加一个部分表达式，预期1..n个单词字符。这包括字母、数字和下划线。等同于：[a-zA-Z_0-9]+

结果正则表达式的示例：\w+

匹配字符串的示例：a，ab

addMaybeWordChars

$regEx->addMaybeWordChars();

添加一个部分表达式，预期0..n个单词字符。这包括字母、数字和下划线。等同于：[a-zA-Z_0-9]*

结果正则表达式的示例：\w*

匹配字符串的示例：a，ab，空字符串

addNonWordChar

$regEx->addNonWordChar();

添加一个部分表达式，预期一个不是单词字符的字符。这包括字母、数字和下划线。等同于：[^a-zA-Z_0-9]

结果正则表达式的示例：\W

匹配字符串的示例：-

addNonWordChars

$regEx->addNonWordChars();

添加一个部分表达式，预期1..n个不是单词字符的字符。这包括字母、数字和下划线。等同于：[^a-zA-Z_0-9]+

结果正则表达式的示例：\W+

匹配字符串的示例：-，-=

addMaybeNonWordChars

$regEx->addMaybeNonWordChars();

添加一个部分表达式，预期0..n个不是单词字符的字符。这包括字母、数字和下划线。等同于：[^a-zA-Z_0-9]*

结果正则表达式的示例：\W*

匹配字符串的示例：-，-=，空字符串

addWhiteSpaceChar

$regEx->addWhiteSpaceChar();

添加一个部分表达式，预期一个空白字符。这包括：空格、\f、\n、\r、\t和\v

结果正则表达式的示例：\s

匹配字符串的示例： （一个空格）

addWhiteSpaceChars

$regEx->addWhiteSpaceChars();

添加一个部分表达式，预期1..n个空白字符。这包括：空格、\f、\n、\r、\t和\v

结果正则表达式的示例：\s+

匹配字符串的示例： （一个空格）， （两个空格）

addMaybeWhiteSpaceChars

$regEx->addMaybeWhiteSpaceChars();

添加一个部分表达式，预期0..n个空白字符。这包括：空格、\f、\n、\r、\t和\v

结果正则表达式的示例：\s*

匹配字符串的示例： （一个空格）， （两个空格），空字符串

addTabChar

$regEx->addTabChar();

添加一个部分表达式，预期一个制表符。

结果正则表达式的示例：\t

匹配字符串的示例：\t

addTabChars

$regEx->addTabChars();

添加一个部分表达式，预期1..n个制表符。

结果正则表达式的示例：\t+

匹配字符串的示例：\t，\t\t

addMaybeTabChars

$regEx->addMaybeTabChars();

添加一个部分表达式，预期0..n个制表符。

结果正则表达式的示例：\t*

匹配字符串的示例：\t，\t\t，空字符串

addLineBreak

$regEx->addLineBreak();
$regEx->addLineBreak(PHP_EOL);

添加一个期望换行的部分表达式。默认情况下，将识别 \n 和 \r\n。您可以通过参数传递来定义特定的换行符模式。

结果正则表达式的示例： \r?\n

匹配字符串的示例： \n，\r\n

addLineBreaks

$regEx->addLineBreaks();
$regEx->addLineBreaks(PHP_EOL);

添加一个期望 1..n 行换行的部分表达式。默认情况下，将识别 \n 和 \r\n。您可以通过参数传递来定义特定的换行符模式。

结果正则表达式的示例： (\r?\n)+

匹配字符串的示例： \n，\n\n

addMaybeLineBreaks

$regEx->addMaybeLineBreaks();
$regEx->addMaybeLineBreaks(PHP_EOL);

添加一个期望 0..n 行换行的部分表达式。默认情况下，将识别 \n 和 \r\n。您可以通过参数传递来定义特定的换行符模式。

结果正则表达式的示例： (\r?\n)*

匹配字符串的示例： \n，\n\n，空字符串

addLineBeginning

$regEx->addLineBeginning();

添加一个期望行开头的部分表达式。换行符标记行的开始。

结果正则表达式的示例： ^

addLineEnd

$regEx->addLineEnd();

添加一个期望行结束的部分表达式。换行符标记行的结束。

结果正则表达式的示例： $

addRange

$regEx->addRange('a-z', '123', '\-');

将一个或多个范围添加到整体正则表达式，并用“范围”表达式包装。可用的范围： a-z，A-Z，0-9 注意：此表达式不会自动引用其内部部分。

结果正则表达式的示例： [a-z123\-]

匹配字符串的示例： a，1，-

此方法使用 RangeEx 表达式类。

addInvertedRange

$regEx->addInvertedRange('a-z', '123', '\-');

将一个或多个范围添加到整体正则表达式，并用反转的“范围”表达式包装。可用的范围： a-z，A-Z，0-9 注意：此表达式不会自动引用其内部部分。

结果正则表达式的示例： [^a-z123\-]

匹配字符串的示例： A，4，=

此方法使用 RangeEx 表达式类。

addAnd

$regEx->addAnd('ht')->addAnd('tp');

将一个或多个部分表达式添加到整体正则表达式，并用“与”表达式包装。此表达式要求其所有部分都存在于测试的字符串中。

结果正则表达式的示例： http

匹配字符串的示例： http

RegEx 类有一个构造函数，它是 addAnd 方法的别名：new RegEx('ab') 将生成与 regEx->andAdd('ab') 相同的正则表达式。

此方法使用 AndEx 表达式类。

addOr

$regEx->addOr('http', 'https');

将至少两个部分表达式添加到整体正则表达式，并用“或”表达式包装。此表达式要求其部分之一存在于测试的字符串中。

结果正则表达式的示例： http|https

匹配字符串的示例： http，https

此方法使用 OrEx 表达式类。

addOption

$regEx->addAnd('http')->addAnd('s');

将一个或多个部分表达式添加到整体正则表达式，并用“可选”表达式包装。此表达式的部分可能或可能不存在于测试的字符串中。

结果正则表达式的示例： https(s)?

匹配字符串的示例： http，https

此方法使用 OptionEx 表达式类。

addRepetition

$regEx->addRepetition(0, 1, "ab"); // Produces "ab?" and matches "ab" and empty string
$regEx->addRepetition(1, 1, "ab"); // Produces "ab" and matches "ab"
$regEx->addRepetition(1, 2, "ab"); // Produces "ab{1,2}" and matches "ab" and "abab".
$regEx->addRepetition(0, RepetitionEx::INFINITE, "ab"); // Produces "ab*" and matches 0..n "ab"
$regEx->addRepetition(1, RepetitionEx::INFINITE, "ab"); // Produces "ab+" and matches 1..n "ab"
$regEx->addRepetition(2, RepetitionEx::INFINITE, "ab"); // Produces "ab{2,}" and matches 2..n "ab"

将一个或多个部分表达式添加到整个正则表达式，并用“重复”表达式包装。期望重复的最小值和最大值作为前两个参数。此表达式的部分必须在测试字符串中出现 $min 到 $max 次。

此方法使用 RepetitionEx 表达式类。

addCapturingGroup

$regEx->addCapturingGroup('test');

将一个或多个部分表达式添加到整体正则表达式，并将其包装在“捕获组”表达式中。当测试整体正则表达式时，此表达式将添加到匹配项中。如果您添加了多个部分，这些部分将通过“和”连接。

结果正则表达式字符串的示例：(test)

此方法使用CapturingGroupEx表达式类。

addComment

$regEx->addComment('This is a comment');

将一个或多个注释添加到整体正则表达式中，并将它们包装在“注释”表达式中。此表达式将不会自动引用其内部部分。注意：注释不允许包含任何结束括号（"()"）！引用它们将不起作用。

结果正则表达式字符串的示例：(?#This is a comment)

建议使用PHP注释而不是正则表达式注释。

此方法使用CommentEx表达式类。

其他方法

quote

$quoted = $regEx->quote('Hello.')

引用（转义）正则表达式字符并返回结果。例如：Hello. > Hello\.

setModifier

$regEx->setModifier(RegEx::MULTI_LINE_MODIFIER_SHORTCUT, true);

激活或停用修饰符。修饰符的当前状态无关紧要，因此例如您可以在（伪）激活修饰符之前停用它。

了解更多关于修饰符的信息...

setInsensitiveModifier等。

$regEx->setInsensitiveModifier();
$regEx->setInsensitiveModifier(true);
$regEx->setInsensitiveModifier(false);

激活或停用“不区分大小写”的“i”修饰符。有所有修饰符的设置器。

getActiveModifiers

$modifiers = $regEx->getActiveModifiers();

返回一个包含当前活动修饰符快捷方式的数组。

isModifierActive()

$active = $regEx->isModifierActive(RegEx::MULTI_LINE_MODIFIER_SHORTCUT);

判断一个修饰符是否激活。

test

$matches = $regEx->test('https//www.example.com/');

测试给定的主题（字符串）是否与正则表达式匹配。返回匹配项。如果在测试过程中发生错误，则抛出异常。

replace

$modified = $regEx->replace('like', 'We hate to hate code');

使用正则表达式执行搜索和替换。返回修改后的字符串。如果在替换过程中发生错误，则抛出异常。

traverse

$regEx->traverse(function($expression, int $level, bool $hasChildren)
{
    var_dump($expression, $level, $hasChildren);
});

如果想要遍历它及其所有子表达式（无论它们在树中的嵌套有多深），请调用此方法。您只需传递一个闭包，无需传递级别参数。回调将具有三个参数：第一个是子表达式（AbstractExpression类型的对象或字符串 | int | float），第二个是该表达式的级别，第三个告诉您它是否有子表达式。

clear

$regEx->clear();

重置正则表达式。

getSize

$flatSize = $regEx->getSize();
$deepSize = $regEx->getSize(true);

返回部分表达式的数量。如果参数为false，则仅计算根级别的部分表达式。如果参数为true，则方法将遍历所有部分表达式并计算所有没有子表达式的部分表达式。换句话说，如果您将正则表达式想象成一棵树，则此方法将仅计算其叶子。

getExpressions

$expressions = $regEx->getExpressions();

部分表达式数组的获取器。

getStart

$start = $regEx->getStart()

"start"属性的获取器

setStart

$regEx->setStart('/')

"start"属性的设置器。这是一个原始字符串。

getEnd

$end = $regEx->getEnd()

"end"属性的获取器。这是一个原始字符串 - 它没有引用。

setEnd

$regEx->setEnd('/')

"end"属性的设置器

getVisualisation

$visualisation = $regEx->getStructure(false);
echo $visualisation;

返回正则表达式结构的“可视化”。这可能有助于您了解正则表达式是如何构建的。如果参数设置为true，则结果可能包含HTML标签。

示例输出

AndEx (Size: 1): (?:line)
  string: line
RawEx (Size: 1): (?:\r?\n*)
  string: \r?\n*
AndEx (Size: 1): (?:break)
  string: break

toString

$stringified = $regEx->toString();

返回连接部分正则表达式作为字符串。已实现魔术方法__toString，因此您可以将RegEx对象转换为字符串。

PHPVerbalExpressions

RegEx受到了PHPVerbalExpressions的启发。它并不比VerbalExpressions更好，而是不同。RegEx更多地使用了OOP原则。因此，它更适合模仿正则表达式的结构。缺点是它稍微复杂一些。

一般说明

• 欢迎贡献力量。如有问题或pull request，请毫不犹豫地创建。如果您发现遗漏了某个方法，请告知。

• 如果您想测试您的正则表达式，可以尝试使用在线正则表达式测试工具。

• 为什么广泛使用（非捕获）组？对我来说，“ab*”与“(?:ab)*”相同这一点并不直观。始终使用（非捕获）组可以强调正则表达式的结构。

• 关于正则表达式语法的官方PHP文档：https://php.ac.cn/manual/de/reference.pcre.pattern.syntax.php

• 此库的代码格式遵循由PSR-2标准定义的代码风格。

• 此仓库的状态：维护中。如有问题，请创建问题，您将在通常48小时内收到回复。