PCRE

# 正则表达式(兼容 Perl)

## 简介
这些函数中使用的模式语法非常类似 perl。表达式必须用分隔符闭合，比如一个正斜杠(/)。 分隔符可以使任意非字母数字，除反斜杠(\)和空字节之外的非空白 ascii 字符。 如果分隔符 在表达式中使用，需要使用反斜线进行转义。也可以使用 perl 样式的()、 {}、 [] 以及 <> 作为分隔符。 更详细的解释参见模式语法。

结束分隔符后面可以紧跟模式修饰符来影响匹配效果。 参见[模式修饰符](http://www.bixiaguangnian.com/manual/phpfunction/2636.html "模式修饰符")。

<div class="callout callout-info mb-3">注意:
这个扩展维护了一个已编译正则表达式的全局线程化缓存(最大4096)。</div>

<div class="callout callout-danger mb-3">**警告** 你应该知道一些 PCRE 的限制。阅读» http://www.pcre.org/pcre.txt 获取更详细信息。</div>

PCRE 库是一个实现了与 perl 5 在语法和语义上略有差异(详见下文)的正则表达式模式匹配功能的函数集。 当前的实现对应于 perl 5.005。

## 安装/配置

### 需求
构建此扩展不需要其他扩展。

### 安装
PCRE 是 PHP 核心扩展，所以始终启用。默认情况下，该扩展使用内置的 PCRE 库。或者，也可以通过指定配置选项 --with-pcre-regex=DIR 设置外部 PCRE 库，DIR 是 PCRE 的 include 和 library 文件位置。推荐使用 PCRE 8.10 或更高版本，自 PHP 7.3.0 起，需要 PCRE2。

PCRE 默认支持 JIT（just-in-time）编译技术，PHP 7.0.12 起可以通过 --without-pcre-jit 禁用 PCRE 的 JIT 功能。

PHP 的 Windows 版本已内建对此扩展的支持。不需要载入额外的扩展来使用这些函数。

PCRE 是一个活跃的项目，作为它的一个演变，PHP功能依赖于它。 php 文档的某些部分可能会过期, 因为它可能不包括 PCRE 提供的一些新功能. 关于修正的清单，请查阅 [» PCRE 库更新日志](http://www.pcre.org/original/changelog.txt "» PCRE 库更新日志")，下面是绑定的 PCRE 库的历史记录：

| PHP 版本        | 更新 PCRE 版本 | 说明                                                                                                                 |
|---------------|------------|-------------------------------|
| 8.2.0         | 10.40      | &nbsp; |
| 8.1.0         | 10.39      | &nbsp; |
| 7.4.12, 8.0.0 | 10.35      | &nbsp; |
| 7.4.6         | 10.34      | &nbsp; |
| 7.4.0         | 10.33      | &nbsp; |
| 7.3.0         | 10.32      | &nbsp; |
| 7.2.0         | 8.41       | &nbsp; |
| 7.0.3         | 8.38       | 参见 CVE-2015-8383、CVE-2015-8386、CVE-2015-8387、CVE-2015-8389、CVE-2015-8390、CVE-2015-8391、CVE-2015-8393、CVE-2015-8394 |
| 7.0.0         | 8.37       | 参见 CVE-2015-2325、CVE-2015-2326 |

### 运行时配置
这些函数的行为受 `php.ini` 中的设置影响。

| 名字                   | 默认       | 可修改范围   | 更新日志   |
|----------------------|----------|---------|--------|
| pcre.backtrack_limit | "100000" | INI_ALL | &nbsp; |
| pcre.recursion_limit | "100000" | INI_ALL | &nbsp; |
| pcre.jit             | "1"      | INI_ALL | &nbsp; |

有关 INI_* 样式的更多详情与定义，见 [配置可被设定范围](https://www.php.net/manual/zh/configuration.changes.modes.php "配置可被设定范围")。
这是配置指令的简短说明。

`pcre.backtrack_limit` `int`
PCRE的回溯限制.

`pcre.recursion_limit` `int`
PCRE 的递归限制. 请注意, 如果将这个值设置为一个很大的数字, 可能会消耗掉进程所有可用的堆栈, 最终导致 PHP 崩溃（由于达到操作系统限制的堆栈大小）。

`pcre.jit` `bool`
是否使用 PCRE 的 JIT 编译。

### 资源类型
此扩展没有定义资源类型。

## 预定义常量
下列常量由此扩展定义，且仅在此扩展编译入 PHP 或在运行时动态载入时可用。

| 常量     | 说明            | 开始可用的版本 |
|----------|---------|---------|
| PREG_PATTERN_ORDER (int) | 对结果进行排序，以便 $matches[0] 是完整模式匹配的数组，$matches[1] 是第一个括号子模式匹配的字符串数组，以此类推。此 flag 仅与 preg_match_all() 一起使用。| &nbsp;  |
| PREG_SET_ORDER (int) | 对结果进行排序，以便 $matches[0] 是第一组匹配的数组，$matches[1] 是第二组匹配的数组，以此类推。此 flag 仅与 preg_match_all() 一起使用。| &nbsp;  |
| PREG_OFFSET_CAPTURE (int) | 查看 PREG_SPLIT_OFFSET_CAPTURE 的描述。 | &nbsp;  |
| PREG_SPLIT_NO_EMPTY (int) | 这个 flag 告诉 preg_split() 仅返回非空部分。 | &nbsp;  |
| PREG_SPLIT_DELIM_CAPTURE (int) | 这个 flag 告诉 preg_split() 也捕获分隔符模式中带括号的表达式。| &nbsp;  |
| PREG_SPLIT_OFFSET_CAPTURE (int) | 如果设置了此 flag，则对于每次发生的匹配，还将附带返回字符串偏移量。注意，这会改变返回数组中的值， 每个元素都是由匹配子串作为第 0 个元素，它相对目标字符串的偏移量作为第 1 个元素的数组。这个 flag 只能用于 preg_split()。 | &nbsp;  |
| PREG_UNMATCHED_AS_NULL (int) | 此 flag 告诉 preg_match() 和 preg_match_all() 在 $matches 将包含的未匹配子模式作为 null 值。没有此 flag，未匹配的子模式将报告为空字符串，就像是空匹配一样。设置此 flag 可以区分这两种情况。 | 7.2.0   |
| PREG_NO_ERROR  (int) | 如果没有错误，则由 preg_last_error() 返回。 | 5.2.0   |
| PREG_INTERNAL_ERROR (int) | 如果有 PCRE 内部错误，则由 preg_last_error() 返回。 | 5.2.0   |
| PREG_BACKTRACK_LIMIT_ERROR (int) | 如果超出了回溯限制，则由 preg_last_error() 返回。 | 5.2.0   |
| PREG_RECURSION_LIMIT_ERROR (int) | 如果超出了递归限制，则由 preg_last_error() 返回。 | 5.2.0   |
| PREG_BAD_UTF8_ERROR (int) | 如果最后一个错误是由格式错误的 UTF-8 数据引起的（仅在 UTF-8 模式下运行正则表达式时），则由 preg_last_error() 返回。 | 5.2.0   |
| PREG_BAD_UTF8_OFFSET_ERROR (int) | 如果偏移量不对应可用的 UTF-8 开始码位（仅在 UTF-8 模式下运行正则表达式时），则由 preg_last_error() 返回。 | 5.3.0   |
| PREG_JIT_STACKLIMIT_ERROR (int) | 当最后一个 PCRE 函数因 JIT 栈空间限制而失败，则由 preg_last_error() 返回。 | 7.0.0   |
| PCRE_VERSION (string)| PCRE 版本号和发布日期（比如：“7.0 18-Dec-2006”）。| 5.2.4   |

## 示例

示例 #1 合法模式示例

```
/<\/\w+>/
|(\d{3})-\d+|Sm
/^(?i)php[34]/
{^\s+(\s+)?$}
```

示例 #2 非法模式示例

```
/href='(.*)' - 缺失结束分隔符
/\w+\s*\w+/J - 未知模式修饰符"J"
1-\d3-\d3-\d4| - 缺失开始分隔符
```