PHPの文字列置換：str_replace()の使い方

str_replace($search, $replace, $subject)は、$subjectの中の$searchをすべて$replaceに置き換えたコピーを返します。str_replace('world', 'PHP', 'Hello world')は"Hello PHP"を返します。

<?php
$text = 'I like cats. cats are great.';

$new = str_replace('cats', 'dogs', $text);

echo $new, "\n";
echo $text, "\n";   // the original is unchanged

この関数は新しい文字列を返すもので、渡した変数を変更するわけではありません。同じ変数に戻す場合でも、結果を代入します：$text = str_replace(...)。

構文

str_replace(
    array|string $search,
    array|string $replace,
    string|array $subject,
    int &$count = null
): string|array

最初の3つの引数は、それぞれ文字列でも配列でもかまいません。$subjectが配列なら、すべての要素に対して置換が行われ、同じキーを持つ配列が返ります：str_replace('.txt', '.md', ['a.txt', 'b.txt'])は['a.md', 'b.md']を返します。検索は大文字小文字を区別し、パターンではなくただのテキストに一致します。パターンにはpreg_replace()を使います。

複数の文字列を一度に置換する

$searchと$replaceに配列を渡します。1つ目の検索値は1つ目の置換値に、2つ目は2つ目に、と順に置き換えられます。$replaceが1つの文字列なら、すべての検索値がそれに置き換えられるので、文字の集合を取り除く短い書き方になります。

<?php
$template = 'Hello {name}, your order {id} has shipped.';

echo str_replace(['{name}', '{id}'], ['Ada', '#1042'], $template), "\n";

// One replacement for every search value: remove punctuation
echo str_replace(['.', ',', '!', '?'], '', 'Hi, there! Ready? Yes.'), "\n";

// Fewer replacements than searches: the missing ones are ""
echo str_replace(['a', 'b', 'c'], ['1'], 'abcabc'), "\n";

順番の罠とstrtr()

配列を渡すと、str_replace()は置換を1つずつ文字列全体に対して実行します。あとの検索が、直前の置換で挿入されたばかりのテキストに一致することがあります。配列を渡したstrtr()は1回の走査ですべてを置換し、長いキーから試し、すでに置換したテキストには触れません。

<?php
$s = 'apple banana';

// apple -> banana, then every banana (including the new one) -> cherry
echo str_replace(['apple', 'banana'], ['banana', 'cherry'], $s), "\n";

// One pass: each original word is replaced once
echo strtr($s, ['apple' => 'banana', 'banana' => 'cherry']), "\n";

値の入れ替えや、値の中に現れるかもしれないテンプレートのプレースホルダーにはstrtr()を使います。

置換した回数を数える

4つ目の引数には、行われた置換の回数が入ります。変数を渡すと、PHPがそこに書き込みます。

<?php
$text = 'one fish, two fish, red fish, blue fish';

$result = str_replace('fish', 'cat', $text, $count);

echo $result, "\n";
echo "Replaced $count times\n";

str_ireplaceで大文字小文字を区別せずに置換する

str_ireplace()は同じ引数を受け取り、照合のときに大文字小文字を無視します。置換値は書いたとおりに挿入されます。

<?php
$text = 'PHP, php and Php';

echo str_replace('php', 'Python', $text), "\n";
echo str_ireplace('php', 'Python', $text), "\n";

str_ireplace()が大文字小文字を同一視するのはASCIIの文字だけです。アクセント付きの文字やキリル文字を大文字小文字の区別なく置換するには、iとuの修飾子を付けたpreg_replace()を使います。

最初の1つだけを置換する

str_replace()は常にすべてを置換します。最初の一致だけを置換するには、strpos()で見つけてsubstr_replace()で切り取ります。

<?php
function replaceFirst(string $search, string $replace, string $subject): string
{
    $pos = strpos($subject, $search);
    if ($pos === false) {
        return $subject;
    }
    return substr_replace($subject, $replace, $pos, strlen($search));
}

echo replaceFirst('a', 'A', 'banana'), "\n";

// The same with a regex and a limit of 1
echo preg_replace('/' . preg_quote('a', '/') . '/', 'A', 'banana', 1), "\n";

最後の出現なら、strpos()の代わりにstrrpos()を使います。

空白、改行などの文字を取り除く

空文字列に置換すると、そのテキストが取り除かれます。よくある後始末は改行やすべての空白を取り除くことで、日本語の入力には普通の" "の検索では一致しない全角スペース（　、U+3000）がよく含まれます。

<?php
$text = "line one\r\nline two\nline three";
echo str_replace(["\r\n", "\n", "\r"], ' ', $text), "\n";

$phone = '090 1234 5678';
echo str_replace(' ', '', $phone), "\n";

$name = '山田　太郎';
echo str_replace('　', ' ', $name), "\n";   // full-width space to normal space

配列の中では"\r\n"を"\n"と"\r"より前に置いてください。そうすればWindowsの改行が2つではなく1つの空白になります。