PHP マニュアル: 正規表現検索および置換を行う

説明

stringarraynull preg_replace(
    stringarray $pattern,
    stringarray $replacement,
    stringarray $subject,
    int $limit = -1,
    int &$count = null
)

subject に関して pattern を用いて検索を行い、 replacement に置換します。

パターンではなく、文字列と正確にマッチさせたい場合、この関数の代わりに str_replace や str_ireplace を使うことを検討してください。

パラメータ

pattern

検索を行うパターン。文字列もしくは配列とすることができます。

PCRE 修飾子も使えます。

replacement

置換を行う文字列もしくは文字列の配列。この引数が文字列で、pattern 引数が配列の場合、すべてのパターンがこの文字列に置換されます。 pattern および replacement のいずれもが配列の場合、各 pattern は対応する replacement に置換されます。もし、replacement 配列の要素の数が pattern 配列よりも少ない場合は、余った pattern は空文字に置換されます。

replacement では、 \n 形式または $n 形式で参照を指定することができます。後者の形式の方が好ましい形式です。各参照は、n 番目のキャプチャ用サブパターンにマッチしたテキストにより置換されます。 n は 0 から 99 までとすることができ、 \0 または $0 はパターン全体にマッチするテキストを参照します。キャプチャ用サブパターンの番号については、その左括弧が左から右に（1から）カウントされます。 string に含まれるバックスラッシュリテラルは、エスケープが必須であることに注意して下さい。

後方参照の直後に他の数字が続くような置換 (replacement) パターンを使用する場合（すなわち、マッチしたパターンの直後に数字リテラルを置く場合）、後方参照を行うために通常の \1 表記を使用することができません。例えば、\11　は、後方参照 \1 の後にリテラル 1 が続くのか、後方参照 \11 でその後には何も続かないのかが不明のため、 preg_replace を混乱させる可能性があります。この場合、解決策は、${1}1 を使用することです。こうすることで、1 はリテラルとなり、後方参照 $1 を明確に作成できます。

非推奨の e 修飾子を使用する際に、この関数は後方参照を置換する文字列のうちの特定の文字 (具体的には '、"、 \ および NULL) をエスケープします。これは、後方参照をシングルクォートやダブルクォートを共用した場合 (たとえば 'strlen(\'$1\')+strlen("$2")') に構文エラーが発生しないようにするためのものです。 PHP の文字列構文を意識し、文字列がどのように解釈されるのかを正確に知っておくようにしましょう。

subject

検索・置換対象となる文字列もしくは文字列の配列

subject が配列の場合、検索と置換は subject の各要素に対して行われ、戻り値も配列となります。

subject が連想配列の場合、キーは戻り値でも保持されます。

limit

subject 文字列において、各パターンによる置換を行う最大回数。デフォルトは -1 (制限無し)。

count

この引数が指定されると、置換回数が渡されます。

戻り値

preg_replace は、 subject 引数が配列の場合は配列を、その他の場合は文字列を返します。

パターンがマッチした場合、〔置換が行われた〕新しい subject を返します。マッチしなかった場合、subject をそのまま返します。エラーが発生した場合、null を返します。

エラー / 例外

"\e" 修飾子を使うと、 E_WARNING レベルのエラーが発生します。

渡された正規表現のパターンがコンパイルできない場合、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 添字配列の使用

<?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.

pattern と replacement を ksort すると、所望のものが得られます。

<?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);
// This will be 'foo o' now
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 を使用する際、配列の並び順に処理されます。添字は整数であっても、その並びは値の小さい順になっているとは限りません。ですから、配列の添字を使って、どの pattern が、どの replacement に置換されるかを指定しようとする場合は、 preg_replace をコールする前に、各配列に対し ksort を実行しておくべきです。

注意:
pattern と replacement が両方配列の場合、ルールのマッチは順番に行われます。つまり、二番目の pattern/replacement のペアは、最初の pattern/replacement のペアの適用結果に対して行われます。オリジナルの文字列に対しては行われません。ふたつの値の交換のような、置換の操作を並列で行わせたい場合は、中間のプレースホルダー内で一方のパターンを置換した後に、そのプレースホルダーに対して望んだ置換を行うようにしましょう。
<?php
$p = array('/a/', '/b/', '/c/');
$r = array('b', 'c', 'd');
print_r(preg_replace($p, $r, 'a'));
// prints d
?>

参考

PCRE のパターン
preg_quote
preg_filter
preg_match
preg_replace_callback
preg_split
preg_last_error
str_replace