preg_replace参数如何正确使用？

函数签名

preg_replace 的基本语法有以下几种形式：

// 最常用的形式
mixed preg_replace( array|string $pattern, array|string $replacement, array|string $subject, int $limit = -1, int &$count = null )
// 带标志（flags）的形式，PHP 7.0+ 推荐
mixed preg_replace( array|string $pattern, array|string $replacement, array|string $subject, int $limit = -1, int &$count = null, int $flags = 0 )

参数详解

我们逐一来看每个参数的含义和用法。

$pattern - 搜索模式（必选）

• 类型: string 或 array
• 作用: 定义要搜索的字符串模式，这通常是一个 PCRE (Perl Compatible Regular Expression) 正则表达式。
• 细节:
  • 字符串形式: 如果你只替换一种模式，可以直接传入一个字符串，'/\s+/' (匹配一个或多个空白字符)。
  • 数组形式: 如果你需要同时匹配并替换多种不同的模式，可以传入一个模式数组，数组的每个元素都是一个独立的正则表达式。
  • 分隔符: 正则表达式字符串通常需要用分隔符括起来，, , 等，如果字符串中包含分隔符，可以在前面加上反斜杠 \ 进行转义，或者选择一个不包含在字符串中的字符作为分隔符。'/http:\/\//' 或 '#http://#'。
  • 修饰符 (Modifiers): 在分隔符后面可以添加修饰符，用来改变正则表达式的匹配行为，常见的修饰符有：
    • i: 不区分大小写 (Case-insensitive)。/apple/i 可以匹配 "apple", "Apple", "APPLE"。
    • m: 多行模式 (Multiline)，使 ^ 和 不仅匹配字符串的开头和结尾，还能匹配每一行的开头和结尾。
    • s: 单行模式 (Single-line)，使 匹配包括换行符在内的所有字符。
    • u: UTF-8 模式 (UTF-8)，强烈建议在处理包含中文字符等非 ASCII 字符的文本时加上此修饰符，以确保正确匹配。

$replacement - 替换字符串（必选）

• 类型: string 或 array
• 作用: 指定用于替换匹配项的字符串。
• 细节:
  • 字符串形式: $pattern 是字符串，$replacement 也应该是字符串。
  • 数组形式: $pattern 是一个模式数组，$replacement 也必须是一个对应的数组，其中每个元素用于替换 $pattern 中对应索引的模式。
  • 反向引用 (Backreferences): 这是 preg_replace 的核心功能之一，在替换字符串中，可以使用 \n 或 $n 的形式来引用正则表达式中的 捕获组 (capturing groups)。
    • n 是一个数字，代表第 n 个捕获组（从 1 开始计数）。
    • '/(\d{4})-(\d{2})-(\d{2})/' 这个模式有三个捕获组：(\d{4}), (\d{2}), (\d{2})。
    • 替换字符串 '\2/\3/\1' 或 '$2/$3/$1' 会将 "2025-10-27" 这样的日期格式转换为 "10/27/2025"。
    • \0 或 $0 代表整个匹配到的字符串。

$subject - 操作目标（必选）

• 类型: string 或 array
• 作用: 需要被搜索和替换的原始字符串或字符串数组。
• 细节:
  • $subject 是一个数组，preg_replace 会对数组中的每个元素执行搜索和替换，并返回一个新数组。
  • 原始的 $subject 数组本身不会被修改（PHP 中字符串和数组都是按值传递的）。

$limit - 替换次数（可选）

• 类型: int
• 作用: 限制每个模式在每个目标字符串上最多执行的替换次数。
• 细节:
  • 默认值为 -1，表示替换所有匹配项。
  • 如果设置为 1，则只替换第一个匹配项。
  • $pattern 和 $subject 都是数组，preg_replace 会依次处理每个元素，并对每个元素应用这个 $limit 限制。

$count - 替换计数（可选）

• 类型: int (必须通过引用传递，即前面加 &)
• 作用: 一个输出参数，用于接收执行了多少次替换操作。
• 细节:
  • 函数执行后,这个变量的值会被设置为总共发生的替换次数。
  • 这在需要知道替换操作是否执行或执行了多少次时非常有用。

$flags - 标志位（可选，PHP 7.0+）

• 类型: int
• 作用: 控制函数的返回行为。
• 细节:
  • PREG_OFFSET_CAPTURE (值为 1): 如果设置了此标志，preg_replace 会返回一个数组，对于每个匹配的字符串，数组中不仅包含替换后的字符串，还包含匹配项在原始字符串中的偏移量（位置）。
  • PREG_UNMATCHED_AS_NULL (值为 2): 如果设置了此标志，对于没有匹配到的捕获组，在结果中会返回 null，而不是一个空字符串 ，这有助于区分“未匹配”和“匹配到了空字符串”两种情况。
  • 默认值为 0。

返回值

• 成功时:
  • $subject 是一个字符串，返回替换后的新字符串。
  • $subject 是一个数组，返回一个包含所有替换后字符串的新数组。
  • 如果没有找到任何匹配项,会原样返回 $subject（字符串或数组）。
• 失败时:
  • 如果正则表达式语法错误,会返回 null。

实例演示

示例 1：基本替换

// 将所有的 "world" 替换为 "Planet"
$subject = "Hello, world! This is a wonderful world.";
$pattern = "/world/";
$replacement = "Planet";
$result = preg_replace($pattern, $replacement, $subject);
echo $result; 
// 输出: Hello, Planet! This is a wonderful Planet.

示例 2：使用反向引用

// 调整日期格式从 YYYY-MM-DD 到 MM/DD/YYYY
$subject = "The event date is 2025-12-25.";
$pattern = "/(\d{4})-(\d{2})-(\d{2})/";
$replacement = "$2/$3/$1"; // 使用 $n 形式的反向引用
$result = preg_replace($pattern, $replacement, $subject);
echo $result;
// 输出: The event date is 12/25/2025.

示例 3：使用数组和限制

// 同时替换多个词，并限制每个词只替换一次
$subject = "The cat and the dog are friends.";
$patterns = ["/cat/", "/dog/"];
$replacements = ["dog", "cat"];
$limit = 1;
$result = preg_replace($patterns, $replacements, $subject, $limit);
echo $result;
// 输出: The dog and the dog are friends.
// (第一次 "cat" 被替换为 "dog"，"dog" 被替换为 "cat"，但都只替换了一次)

示例 4：处理数组输入

$subjects = ["apple pie", "banana split", "cherry tart"];
$pattern = "/pie|split|tart/";
$replacement = "cake";
$result = preg_replace($pattern, $replacement, $subjects);
print_r($result);
// 输出:
// Array
// (
//     [0] => apple cake
//     [1] => banana cake
//     [2] => cherry cake
// )

示例 5：使用 $count 参数

$subject = "Hello world, hello universe.";
$pattern = "/hello/";
$replacement = "Hi";
$count = 0; // 初始化计数器
$result = preg_replace($pattern, $replacement, $subject, -1, $count);
echo "替换后的字符串: " . $result . "\n";
echo "总共替换了 " . $count . " 次，\n";
// 输出:
// 替换后的字符串: Hi world, Hi universe.
// 总共替换了 2 次。

掌握 preg_replace 的这些参数，特别是 $pattern 和 $replacement 的强大组合，可以让你高效地处理各种复杂的文本替换任务。