【PHP8.x】substr_replace関数の使い方

作成日: 2025年09月11日更新日: 2025年09月29日

substr_replace関数は、文字列の一部を指定した別の文字列で置き換えるための関数です。この関数は、与えられた文字列の特定の位置から指定された長さの範囲を、新しい文字列に置き換える処理を実行します。

具体的には、この関数は四つの引数を受け取ります。最初の引数には、置き換えの対象となる元の文字列を指定します。二番目の引数には、置き換えとして挿入する新しい文字列を指定します。三番目の引数には、置き換えを開始する位置を数値で指定します。この開始位置は文字列の先頭を0として数え、負の値を指定した場合は文字列の末尾から数えた位置になります。四番目の引数には、置き換える文字の長さを数値で指定します。この長さを省略した場合や、指定した長さが文字列の残りの部分よりも長い場合は、開始位置から文字列の最後までが置き換えの対象となります。また、長さに負の値を指定すると、文字列の末尾から数えた長さを除いた部分が置き換えの対象となります。

この関数は、置き換えが完了した新しい文字列を返します。元の文字列自体が変更されることはありませんので、必要に応じて戻り値を新しい変数に代入して利用します。例えば、ユーザーの入力した文字列の一部を修正したり、特定の情報をマスクしたりする場合など、多様な文字列操作の場面で活用できる機能です。シンプルながらも非常に柔軟な文字列操作を実現できるため、プログラミングにおいて頻繁に利用されます。

基本的な使い方

構文(syntax)

<?php

// 文字列の一部を、別の文字列で置換する
$result = substr_replace(
    $string,      // 置換対象の文字列
    $replacement, // 置換後の文字列
    $start,       // 置換を開始する位置 (0から始まるインデックス)
    $length       // 置換する文字数 (省略可能)
);

引数(parameters)

string|array $string: 処理対象となる文字列または文字列の配列
string|array $replace: 置換する文字列または置換文字列の配列
int|array $offset: $string のどの位置から置換を開始するかを指定する整数、またはオフセットの配列
int|null|array $length = null: $string の $offset から置換する文字数を指定する整数、または文字数の配列。null を指定すると、$offset から文字列の最後まで置換します。

戻り値(return)

string|array|null

指定された文字列の一部を別の文字列に置き換えた結果を返します。置換が正常に行われた場合は文字列、置換対象が配列で部分的に置換された場合は配列、エラーが発生した場合はnullを返します。