README

~ 是一个方便的 PHP 库，它提供了一种使用 preg_match 的替代方式。它的功能与 preg_match 类似，但返回匹配元素或子集。

安装

推荐通过 Composer 安装 preg_return。

composer require dixflatlinr/preg_return

语法与用法

该软件包注册了全局函数作为便利，因此可以使用如下方式

preg_return(string $pattern, string $subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)
preg_return_all(string $pattern, string $subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)
preg_return_replace(string $pattern, string $replacement, string &$subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)

或者直接调用它

RX::pregReturn(string $pattern, string $subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)
RX::pregReturnAll(string $pattern, string $subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)
RX::pregReturnReplace(string $pattern, string $replacement, string &$subject, $indexesToReturn = null, int $flags = 0, int $offset = 0)

与

preg_match(string $pattern, string $subject, array &$matches = null, int $flags = 0, int $offset = 0): int|false

相比，唯一的区别是，现在不是使用 &$matches 参数，而是 $indexesToReturn 控制返回的内容和方式。

示例

<?
use DF\App\Helper\RX;
require "vendor/autoload.php";

//$indexesToReturn === null, gives back the preg_match return value
preg_return('~(a)(?<namedindex>b)~is','ab'); //=> 1;
RX::pregReturn('~(a)(?<namedindex>b)~is','ab'); //=> 1;

//Using an empty array or string returns the whole results array
preg_return('~(a)(?<namedindex>b)~is','ab', []);
/* =>
array(4) {
  [0]=>
  string(2) "ab"
  [1]=>
  string(1) "a"
  ["namedindex"]=>
  string(1) "b"
  [2]=>
  string(1) "b"
}
*/

//=== 0, gives back the text that matched the full pattern
preg_return('~(a)(?<namedindex>b)~is','ab', 0); //=> 'ab'

//=== 1, gives back text that matched the first captured parenthesized subpattern
preg_return('~(a)(?<namedindex>b)~is','ab', 1); //=> 'a'

//=== 'namedindex', gives back text that matched the given named group
preg_return('~(a)(?<namedindex>b)~is','ab', 'namedindex'); //=> 'b'

//Using an array with indexes or named groups returns those keyed accordingly
preg_return('~(a)(?<namedindex>b)~is','ab', [1,'namedindex']);//=> [1 => 'a', 'namedindex' => b]

//Using preg_return_replace modifies the provided subject variable and returns the matched element before replacement
$subject = 'first_second_third';
$r = preg_return_replace('~^(first)_(second)_(?<third>third)$~is', '\1_\2_XXX', $subject, 3);
/*
$r = "third";
$subject = "first_second_XXX";
*/