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

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

preg_replace_callback_array関数は、複数の正規表現パターンと、それら各パターンに対応するコールバック関数を一度に指定し、入力文字列内でマッチした部分を置換する関数です。

この関数は、単一の正規表現パターンとコールバック関数を用いて置換を行うpreg_replace_callback関数の拡張版と位置づけられます。従来の関数では、異なる正規表現に対して異なる処理を行う場合、関数を複数回呼び出す必要がありましたが、preg_replace_callback_array関数では、連想配列形式でパターンとコールバック関数のペアを複数渡すことで、一度の呼び出しでこれを実現できます。

第一引数には、キーに正規表現パターン、値にそのパターンがマッチした場合に実行されるコールバック関数を指定した連想配列を渡します。第二引数には、検索と置換の対象となる文字列（または文字列の配列）を指定します。これにより、複雑な文字列処理において、異なる条件に基づいた複数の置換ルールを簡潔かつ効率的に適用することが可能になります。

コールバック関数は、マッチした部分の情報を引数として受け取り、その情報に基づいて置換後の文字列を返します。この柔軟性により、単なる固定値への置換だけでなく、マッチした内容に応じた動的な文字列生成や加工を行うことができます。置換処理が成功した場合は置換後の文字列を返し、エラーが発生した場合はNULLを返します。この関数は、特に文字列の整形やデータのクレンジングなど、多様な正規表現と処理を組み合わせる必要がある場面で非常に役立ちます。

基本的な使い方

構文(syntax)

<?php
$subject = "Hello 123 World 456.";

$pattern_callbacks = [
    '/\d+/' => function (array $matches) {
        return $matches[0] * 2;
    },
    '/World/' => function (array $matches) {
        return 'PHP';
    },
];

$result = preg_replace_callback_array($pattern_callbacks, $subject);

引数(parameters)

array $pattern, string|array $subject, int $limit = -1, int &$count = null, int $flags = 0

array $pattern: 置換処理を行う正規表現パターンとコールバック関数の連想配列
string|array $subject: 置換対象の文字列、または文字列の配列
int $limit = -1: 各パターンに対して実行する置換の最大回数。-1は無制限
int &$count = null: 実行された置換の総数を格納する変数
int $flags = 0: 正規表現のフラグを指定

戻り値(return)

array|string|null

正規表現のパターンとコールバック関数の配列に基づいて、文字列の置換処理を行います。処理結果として、置換後の文字列、または置換が行われなかった場合は元の文字列が返されます。置換処理中にエラーが発生した場合は、NULLが返されます。