正規表現検索を行い、コールバック関数を使用して置換を行う

# preg_replace_callback

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

preg_replace_callback — 正規表現検索を行い、コールバック関数を使用して置換を行う

### 説明

function preg_replace_callback(
string|array `$pattern`,
callable `$callback`,
string|array `$subject`,
int `$limit` = -1,
int `&$count` = `null`,
int `$flags` = 0
): string|array|null

この関数の動作は、ほぼ preg_replace() と同じですが、 `replacement` の代わりに `callback` を指定するところが異なります。

### パラメータ

`pattern`

  検索するパターン。 文字列あるいは文字列の配列のいずれかとなります。

`callback`

  このコールバック関数は、検索対象文字列でマッチした要素の配列が指定されて コールされます。このコールバック関数は、置換後の文字列を返す必要があります。 コールバックのシグネチャは、次のとおりです。

  function handler(array `$matches`): string

  preg_replace_callback() 用の `callback` 関数が、 ひとつの場所だけで必要となることがあります。 そんな場合は、 無名関数 を使って宣言した無名関数を preg_replace_callback() のコール時に使用します。 このようにすることにより、コールに関するすべての情報を 1 ヶ所に集め、 他の場所で使用されないコールバック関数名で関数の名前空間を 汚染しないようにすることができます。

  例1 preg_replace_callback() と無名関数

      <?php
      /* Unix 方式のコマンドラインフィルタです。
       * 段落の冒頭の大文字を、小文字に変換します。*/
      $fp = fopen("php://stdin", "r") or die("標準入力から読み込めません");
      while (!feof($fp)) {
          $line = fgets($fp);
          $line = preg_replace_callback(
              '|<p>\s*\w|',
              function ($matches) {
                  return strtolower($matches[0]);
              },
              $line
          );
          echo $line;
      }
      fclose($fp);
      ?>

`subject`

  文字列あるいは文字列の配列で、 検索および置換の対象となる文字列を指定します。

`limit`

  `subject` 文字列における 各パターンの最大置換回数。デフォルトは `-1` (無制限) です。

`count`

  指定した場合は、置換を行った回数がここに格納されます。

`flags`

  `flags` には、 `PREG_OFFSET_CAPTURE` と `PREG_UNMATCHED_AS_NULL` の組み合わせが指定できます。 これは matches 配列のフォーマットに影響します。 詳細は preg_match() 関数の説明を参照ください。

### 戻り値

preg_replace_callback() は、 `subject` が配列の場合には配列を、 それ以外の場合は文字列を返します。 エラー時の戻り値は `null` となります。

マッチするものが見つかった場合は新しい subject を返し、それ以外の場合はもとの `subject` をそのまま返します。

### エラー / 例外

渡された正規表現のパターンがコンパイルできない場合、`E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
7.4.0 | パラメータ `flags` が追加されました。

### 例

例2 preg_replace_callback() の例

    <?php
    // このテキストは 2002 に使われていたものなのですが、
    // これを 2003 年対応の日付に変更したいのです
    $text = "エイプリルフールの日付は 04/01/2002 です\n";
    $text.= "この前のクリスマスの日付は 12/24/2001 でした\n";
    // コールバック関数
    function next_year($matches)
    {
      // 通常は、$matches[0] がマッチした全体を表します。
      // $matches[1] は、マッチした中で、パターン内の最初の '(...)'
      // にあてはまる部分を表します。それ以降も同様です。
      return $matches[1].($matches[2]+1);
    }
    echo preg_replace_callback(
                "|(\d{2}/\d{2}/)(\d{4})|",
                "next_year",
                $text);

    ?>

上の例の出力は以下となります。

    エイプリルフールの日付は 04/01/2003 です
    この前のクリスマスの日付は 12/24/2002 でした

例3 カプセル化された BB code を処理するための、 preg_replace_callback() での再帰構造の使用

    <?php
    $input = "通常の位置 [indent] 字下げ [indent] もっと字下げ [/indent] 字下げ [/indent] 通常の位置";

    function parseTagsRecursive($input)
    {

        $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

        if (is_array($input)) {
            $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
        }

        return preg_replace_callback($regex, 'parseTagsRecursive', $input);
    }

    $output = parseTagsRecursive($input);

    echo $output;
    ?>

### 参考

- PCRE のパターン
- preg_replace_callback_array() - 正規表現検索を行い、コールバック関数を使用して置換を行う
- preg_quote() - 正規表現文字をクオートする
- preg_replace() - 正規表現検索および置換を行う
- preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
- 無名関数

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open