preg_replace
(PHP 4, PHP 5, PHP 7, PHP 8)
preg_replace — 執行一個正規表示式的搜索和替換
說明
string|array
$pattern,string|array
$replacement,string|array
$subject,int
$limit = -1,int
&$count = null): string|array|null
搜索 subject 中匹配 pattern 的部分，以 replacement 進行替換。
參數
-
pattern 要搜索的模式。可以使一個字串或字串陣列。
可以使用一些 PCRE 修飾符。
-
replacement 用於替換的字串或字串陣列。如果這個參數是一個字串，並且
pattern是一個陣列，那麼所有的模式都使用這個字串進行替換。如果pattern和replacement都是陣列，每個pattern使用replacement中對應的元素進行替換。如果replacement中的元素比pattern中的少，多出來的pattern使用空字串進行替換。replacement中可以包含後向引用\\n或$n，語法上首選後者。 每個這樣的引用將被匹配到的第 n 個捕獲子組捕獲到的文字替換。 n 可以是0-99，\\0和$0代表完整的模式匹配文字。捕獲子組的序號計數方式為：代表捕獲子組的左括號從左到右， 從1開始數。如果要在replacement中使用反斜線，必須使用 4 個("\\\\"，譯註：因為這首先是 PHP 的字串，經過轉義后，是兩個，再經過正規表示式引擎后才被認為是一個原文反斜線)。當在替換模式下工作並且後向引用後面緊跟著需要是另外一個數字 (比如：在一個匹配模式后緊接著增加一個原文數字)，不能使用
\\1這樣的語法來描述後向引用。比如，\\11將會使preg_replace() 不能理解你希望的是一個\\1後向引用緊跟一個原文1，還是一個\\11後向引用後面不跟任何東西。 這種情況下解決方案是使用${1}1。這建立了一個獨立的$1後向引用, 一個獨立的原文1。當使用被棄用的
e修飾符時, 這個函式會轉義一些字元 (即：'、"、\和 NULL) 然後進行後向引用替換。當這些完成後請確保後向引用解析完后沒有單引號或雙引號引起的語法錯誤 (比如：'strlen(\'$1\')+strlen("$2")')。確保符合 PHP 的 字串語法，並且符合 eval 語法。因為在完成替換后，引擎會將結果字串作為 PHP 程式碼使用 eval 方式進行評估並將返回值作為最終參與替換的字串。-
subject 要進行搜索和替換的字串或字串陣列。
如果
subject是一個陣列，搜索和替換回在subject的每一個元素上進行, 並且返回值也會是一個陣列。-
limit 每個模式在每個
subject上進行替換的最大次數。預設是-1(無限)。-
count 如果指定，將會被填充為完成的替換次數。
返回值
如果 subject 是一個陣列，preg_replace() 返回一個陣列，其他情況下返回一個字串。
如果匹配被查詢到，替換后的 subject 被返回，其他情況下返回沒有改變的 subject。如果發生錯誤，返回 null 。
錯誤／異常
"\e" 會並忽略，併產生 E_WARNING 錯誤。
範例
示例 #1 使用後向引用緊跟數值原文
<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?> 以上例程會輸出：
April1,2003
示例 #2 preg_replace() 中使用基於索引的陣列
<?php
$string = 'The quick brown fox jumps over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?> 以上例程會輸出：
The bear black slow jumps over the lazy dog.
對模式和替換內容按 key 進行排序我們可以得到期望的結果。
<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?> 以上例程會輸出：
The slow black bear jumps over the lazy dog.
示例 #3 替換一些值
<?php
$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/');
$replace = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?> 以上例程會輸出：
$startDate = 5/27/1999
示例 #4 剝離空白字元
這個例子剝離多餘的空白字元
<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
// 將會改變為'foo o'
echo $str;
?> 示例 #5 使用參數 count
<?php
$count = 0;
echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; //3
?> 以上例程會輸出：
xp***to 3
註釋
注意:
當使用陣列形式的
pattern和replacement時, 將會按照key在陣列中出現的順序進行處理. 這不一定和陣列的索引順序一致. 如果你期望使用索引對等方式用replacement對pattern進行替換, 你可以在呼叫preg_replace()之前對兩個陣列各進行一次ksort()排序.
參見
- PCRE 模式
- preg_quote() - 轉義正規表示式字元
- preg_filter() - 執行一個正規表示式搜索和替換
- preg_match() - 執行匹配正規表示式
- preg_replace_callback() - 執行一個正規表示式搜索並且使用一個回撥進行替換
- preg_split() - 通過一個正規表示式分隔字串
- preg_last_error() - 返回最後一個PCRE正則執行產生的錯誤程式碼