str_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

str_replace — 検索文字列に一致したすべての文字列を置換する

説明

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

この関数は、subject の中の search を全て replace に置換します。

固定の文字列ではなく、パターンベースでテキストを置換したい場合、 preg_replace() を使ってください。

パラメータ

search と replace が配列の場合、str_replace() は各配列から値をひとつ取り出し、 subject 上で検索と置換を行うために使用します。 replace の値が search よりも少ない場合、置換される値の残りの部分には空の文字列が使用されます。 search が配列で replace が文字列の場合、この置換文字列が search の各値について使用されます。しかし、逆は意味がありません。

search あるいは replace が配列の場合は、配列の最初の要素から順に処理されます。

search

探したい値。needle (針) と呼ばれることもあります。配列を使えば、複数の値を指定することもできます。

replace

見つかった search を置き換える値。配列を使えば、複数の値を指定することもできます。

subject

検索・置換の対象となる文字列あるいは配列。 haystack (干し草の山) と呼ばれることもあります。

subject が配列の場合、 subject の各エントリについて検索と置換が行われ、戻り値は同様に配列となります。

count

指定した場合は、マッチして置換が行われた箇所の個数がここに格納されます。

戻り値

この関数は、置換後の文字列あるいは配列を返します。

例

例1 基本的な str_replace() の例

<?php
// <body text='black'> となります
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
echo $bodytag, PHP_EOL;

// Hll Wrld f PHP となります
$vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$onlyconsonants = str_replace($vowels, "", "Hello World of PHP");
echo $onlyconsonants, PHP_EOL;

// You should eat pizza, beer, and ice cream every day となります
$phrase  = "You should eat fruits, vegetables, and fiber every day.";
$healthy = array("fruits", "vegetables", "fiber");
$yummy   = array("pizza", "beer", "ice cream");

$newphrase = str_replace($healthy, $yummy, $phrase);
echo $newphrase, PHP_EOL;

// 2 となります
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count, PHP_EOL;
?>

例2 str_replace() に関するちょっとした事実

<?php
// 置換の順番を指定します
$str     = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
$order   = array("\r\n", "\n", "\r");
$replace = '<br />';

// まず最初に \r\n を置換するので、二重に変換されることはありません
$newstr = str_replace($order, $replace, $str);
echo $newstr, PHP_EOL;

// 出力は F となります。A が B に、そして B が C に、そして……
// 最終的に E が F に置換されるからです。置換は左から右へと順に行われます
$search  = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject), PHP_EOL;

// 出力は apearpearle pear となります
// 上で説明したのと同じ理由です
$letters = array('a', 'p');
$fruit   = array('apple', 'pear');
$text    = 'a p';
$output  = str_replace($letters, $fruit, $text);
echo $output, PHP_EOL;
?>

注意

注意: この関数はバイナリデータに対応しています。

警告

置換の順番に関するメモ

str_replace() は左から右へと置換を行うので、複数の置換を行うときには、前に追加された値を置換する可能性もあります。このドキュメントのサンプルを参照ください。

注意:
この関数は大文字小文字を区別します。区別せずに置換するには str_ireplace() を使用します。

参考

str_ireplace() - 大文字小文字を区別しない str_replace
substr_replace() - 文字列の一部を置換する
preg_replace() - 正規表現検索および置換を行う
strtr() - 文字の変換あるいは部分文字列の置換を行う