PHPのstr_replace関数 — 文字列・配列を置換する使い方と実例

// 基本例
str_replace("World", "PHP", "Hello, World!");        // "Hello, PHP!"
str_replace(["a", "b"], ["1", "2"], "abc");           // "12c"
str_replace("-", "", "090-1234-5678");                // "09012345678"

PHPのstr_replace()関数は、文字列の中から指定した文字列を検索し、別の文字列に置き換えるための組み込み関数です。単純な単語の置換だけでなく、配列を使った複数箇所の一括置換にも対応しており、テンプレートの埋め込み処理やデータの整形など幅広い場面で使われます。ただし大文字・小文字を区別する点や、置換順序によって意図しない連鎖置換が起きる点など、知っておくべき注意点もあります。この記事では基本構文から配列を使った応用パターン、よくある落とし穴、他の置換関数との使い分けまで解説します。

str_replace関数とは？

PHPのstr_replace()は、対象の文字列（または文字列の配列）から検索文字列を探し、置換文字列に差し替えて返す組み込み関数です。

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

引数の詳細

基本的な使い方

$text = "Hello, World!";

// "World" を "PHP" に置換
echo str_replace("World", "PHP", $text); // "Hello, PHP!"

// 一致しない場合は元の文字列がそのまま返る
echo str_replace("Java", "PHP", $text);  // "Hello, World!"

電話番号やコードからハイフンを取り除く

$phone = "090-1234-5678";

$digitsOnly = str_replace('-', '', $phone);
echo $digitsOnly; // "09012345678"

改行コードを統一する

// CRLF・CR を LF に統一する
$text = "line1\r\nline2\rline3\n";

$normalized = str_replace(["\r\n", "\r"], "\n", $text);
echo $normalized; // "line1\nline2\nline3\n"

配列を使った置換パターン

str_replace()は$search・$replace・$subjectそれぞれに配列を渡すことができ、組み合わせによって挙動が変わります。

パターン1：複数の単語をそれぞれ別の文字列に置換する

$search  = ['apple', 'banana', 'cherry'];
$replace = ['りんご', 'バナナ', 'さくらんぼ'];
$text    = "I like apple, banana and cherry.";

echo str_replace($search, $replace, $text);
// "I like りんご, バナナ and さくらんぼ."

パターン2：複数の文字列をまとめて同じ文字列に置換する

$searchが配列で$replaceが文字列の場合、その1つの値がすべての検索対象に使われます。

// HTMLタグをすべて取り除く
$html = "<b>Hello</b>, <i>World</i>!";

$plain = str_replace(['<b>', '</b>', '<i>', '</i>'], '', $html);
echo $plain; // "Hello, World!"

パターン3：テンプレートのプレースホルダーを一括置換する

$template = "Hello, {name}! You have {count} new messages.";

$replacements = [
    '{name}'  => 'Yamada',
    '{count}' => 3,
];

echo str_replace(array_keys($replacements), array_values($replacements), $template);
// "Hello, Yamada! You have 3 new messages."

パターン4：$subjectに配列を渡す（複数の文字列をまとめて処理）

$texts = ["foo bar", "baz foo"];

print_r(str_replace('foo', 'FOO', $texts));
// ["FOO bar", "baz FOO"]

$searchと$replaceの要素数が異なる場合

$replaceの要素数が$searchより少ないと、対応する値がない部分は空文字列に置換されます。

$search  = ['a', 'b', 'c', 'd', 'e'];
$replace = ['A', 'B', 'C'];

echo str_replace($search, $replace, 'abcdefg');
// "ABCfg"（d, e は空文字に置換される）

置換回数を数える（$count引数）

第4引数に変数を渡すと、置換が行われた合計回数が代入されます。

$count = 0;

$result = str_replace('a', '', 'banana', $count);

echo $result; // "bnn"
echo $count;  // 3

よくある落とし穴・注意点

連鎖置換（置換順序の罠）

str_replace()は$search配列の要素を左から右へ順番に処理します。そのため、ある置換の結果が次の検索対象と一致すると、意図せず連鎖して置換されてしまうことがあります。

$search  = ['A', 'B', 'C', 'D', 'E'];
$replace = ['B', 'C', 'D', 'E', 'F'];

echo str_replace($search, $replace, 'A');
// 期待値: "B"
// 実際の結果: "F"（A→B→C→D→E→F と連鎖してしまう）

この問題を避けたい場合は、置換順序に依存しないstrtr()を使います。

$search  = ['A', 'B', 'C', 'D', 'E'];
$replace = ['B', 'C', 'D', 'E', 'F'];

echo strtr('A', array_combine($search, $replace));
// "B"（連鎖せず正しく1回だけ置換される）

重複パターンを1回で完全には消せない

$str = "-aaa----b-c-----d--e---f";

echo str_replace('--', '-', $str);
// "-aaa--b-c---d-e--f"（"----" のような4連続以上は1回では潰れない）

完全に1文字へ潰したい場合は、置換回数が0になるまでループさせるか、正規表現のpreg_replace()を使います。

do {
    $str = str_replace('--', '-', $str, $count);
} while ($count > 0);

// または
$str = preg_replace('/-+/', '-', $str);

PHP 8.1以降はnullを渡すと非推奨警告が出る

PHP 8.1以降、内部関数の非nullableな引数にnullを渡すとDeprecated警告が出ます。$subjectなどに変数を渡す際、値がnullになる可能性がある場合は空文字列にキャストしてから渡してください。

// PHP 8.1+ で $value が null だと Deprecated 警告
str_replace('a', 'b', $value);

// 対策：明示的に文字列へキャストする
str_replace('a', 'b', (string) $value);

大文字・小文字を区別しない置換にはstr_ireplace()

str_replace()は大文字・小文字を区別します。区別せずに置換したい場合は、同じ引数構成のstr_ireplace()を使います。

$text = "Hello World, hello PHP";

echo str_replace('hello', 'Hi', $text);   // "Hello World, Hi PHP"（小文字のhelloのみ一致）
echo str_ireplace('hello', 'Hi', $text);  // "Hi World, Hi PHP"（大文字小文字を区別しない）

str_replace() / str_ireplace() / preg_replace() / substr_replace() / strtr() の使い分け

substr_replace()との違い

str_replace()は「検索文字列に一致した箇所」を置換しますが、substr_replace()は「位置と長さで指定した箇所」を置換します。マスキング処理など、内容に関係なく特定の位置を書き換えたい場合はsubstr_replace()が適しています。

$card = "1234-5678-9012-3456";

// str_replace: 内容が一致した箇所を置換（一致しなければ何も起きない）
echo str_replace('1234', '****', $card); // "****-5678-9012-3456"

// substr_replace: 位置指定で置換（内容に関係なく先頭4文字を置換）
echo substr_replace($card, '****', 0, 4); // "****-5678-9012-3456"

関連記事

• PHPのpreg_replace関数 — 正規表現でパターン置換する使い方と実例 — 可変長・条件付きのパターンで置換したいときはこちら
• PHP substr関数の使い方と実例：文字列操作をマスターしよう — 位置・長さ指定で文字列を切り出したいときはこちら
• 初心者向け：PHP strpos関数を使って文字列内の位置を取得する方法 — 置換の前に文字列内の位置を調べたいときはこちら
• PHPのexplode関数 — 文字列を区切り文字で配列に分割する — 区切り文字で分割してから処理したいときはこちら
• PHPのimplode関数 — 配列要素を区切り文字で連結して文字列にする — 置換後に配列を1つの文字列へ戻したいときはこちら

FAQ

str_replaceとpreg_replaceの違いは？

str_replace()は固定の文字列をそのまま検索して置換します。preg_replace()は正規表現パターンで検索するため、「数字が連続する部分」のような可変長・条件付きのパターンも置換できます。置換対象が固定文字列なら処理が軽いstr_replace()で十分です。

// 固定文字列の置換
echo str_replace('-', '', '090-1234-5678'); // "09012345678"

// 正規表現での置換（数字以外をすべて除去）
echo preg_replace('/\D/', '', '090-1234-5678'); // "09012345678"

str_replaceで大文字・小文字を区別しないようにするには？

str_ireplace()を使います。引数の順番・型はすべてstr_replace()と同じです。

echo str_ireplace('PHP', 'Laravel', 'I love php!'); // "I love Laravel!"

str_replaceで配列を一括置換するには？

$searchと$replaceにそれぞれ配列を渡すと、対応する位置の値同士で一括置換できます。要素数が揃っていない場合、不足分は空文字列に置換される点に注意してください。

$search  = ['a', 'b', 'c'];
$replace = ['1', '2', '3'];
echo str_replace($search, $replace, 'abc'); // "123"

置換した回数を取得するには？

第4引数に変数を渡すと、置換された合計回数が代入されます。値ではなく変数を渡す必要があります。

str_replace('a', '', 'banana', $count);
echo $count; // 3

まとめ

str_replace()関数のポイントをまとめます。

• str_replace($search, $replace, $subject)で文字列中の指定パターンを置換する
• $search・$replaceに配列を渡すと、複数パターンを一括で置換できる
• 大文字・小文字を区別する（区別しない置換はstr_ireplace()）
• 配列を使った置換は左から右へ順番に処理されるため、置換結果が次の検索対象と一致すると連鎖置換が起きる（回避するならstrtr()）
• 連続する重複パターンは1回の呼び出しでは完全に潰れない（ループまたはpreg_replace()で対処）
• 可変長パターンでの置換はpreg_replace()、位置指定の置換はsubstr_replace()が向いている

固定文字列の置換であればstr_replace()が最も手軽で高速です。まずは基本の1対1置換から始め、配列を使った一括置換や連鎖置換の罠を押さえておくことで、意図しないバグを避けられます。