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

<?php

/**
 * 文字列の配列から特定の正規表現パターンにマッチする要素のみを抽出し、
 * さらにマッチした部分を置換するサンプル関数です。
 *
 * preg_filter は preg_replace と同様に正規表現による置換を行いますが、
 * パターンにマッチしなかった要素は結果の配列から自動的に除外されるという特徴があります。
 * これは、array_filter を使って preg_match に合格した要素のみを残し、
 * その後で preg_replace を適用する、という一連の処理を1つの関数で実現するようなものです。
 *
 * @param array $subjects 処理対象となる文字列の配列。
 * @return array パターンにマッチし、置換が適用された要素のみを含む配列。
 *               もしどの要素もパターンにマッチしなかった場合、空の配列を返します。
 */
function filterAndReplaceWithRegex(array $subjects): array
{
    // 検索する正規表現パターンを定義します。
    // ここでは、文字列中の1つ以上の数字の並び（\d+）をキャプチャグループ（()）で指定しています。
    $pattern = '/(\d+)/';

    // 置換文字列を定義します。
    // $1 はキャプチャグループ（上記のパターンで括弧で囲まれた部分）にマッチした内容を指します。
    // 例: "123" が "(123)" に置換されます。
    $replacement = '($1)';

    // preg_filter 関数を使用して、以下の処理を一度に行います。
    // 1. $subjects 配列の各要素に対して $pattern で正規表現マッチングを行います。
    // 2. マッチした要素については、マッチした部分を $replacement で置換します。
    // 3. パターンにマッチしなかった要素は、結果の配列から自動的に除外されます。
    // 第4引数 -1 は、各 subject に対して置換回数の制限を設けないことを意味します。
    $filteredAndReplaced = preg_filter($pattern, $replacement, $subjects, -1);

    // preg_filter は、マッチする要素が全くなかった場合に null を返すことがあります。
    // その場合、期待される戻り値の型 (array) に合わせるため、空の配列を返します。
    return is_array($filteredAndReplaced) ? $filteredAndReplaced : [];
}

// サンプルデータを用意します。
$data = [
    'document_id_1001',
    'report_title_finance',
    'user_code_A5B6C7',
    'status_active',
    'version_2.0',
    'no_number_string'
];

echo "--- 元のデータ配列 ---\n";
print_r($data);

// filterAndReplaceWithRegex 関数を実行し、結果を取得します。
$result = filterAndReplaceWithRegex($data);

echo "\n--- 処理後のデータ配列 (数字を含む要素のみ抽出・置換) ---\n";
print_r($result);

// 期待される出力:
// document_id_(1001)
// user_code_(A5B6C7)
// version_(2.0)
//
// 'report_title_finance', 'status_active', 'no_number_string' は
// 数字が含まれないため、結果から除外されます。
// 'version_2.0' は、正規表現 `(\d+)` に `2` と `0` が別々にマッチし、
// 結果的に `version_(2).(0)` のように置換されます。
// (ただし、この例では小数点を区切りとして`2`と`0`が別々に処理されるので注意。
//  もし`2.0`全体を置換したい場合はパターンを調整する必要があります。例: `(\d+\.?\d*)` )

?>

PHPのpreg_filter関数は、正規表現を使って文字列や文字列の配列を検索し、マッチした部分を置換すると同時に、パターンにマッチしなかった要素を結果から自動的に除外する機能を提供します。これは、preg_replaceによる置換処理と、array_filterを使ってpreg_matchに合格する要素のみを残すフィルタリング処理を一度に、効率的に行うようなものです。

この関数は、第一引数に検索する正規表現パターン、第二引数に置換する文字列、第三引数に処理対象の文字列または文字列の配列を指定します。パターンと置換文字列は、それぞれ配列で複数指定することも可能です。戻り値は、パターンにマッチして置換が適用された要素のみを含む配列、または単一の文字列となります。もし、どの要素もパターンに全くマッチしなかった場合はnullを返します。

サンプルコードでは、与えられた文字列の配列の中から数字の並び（\d+）を含む要素だけを抽出し、さらにその数字部分を括弧で囲むように置換しています。例えば、「document_id_1001」という文字列は「document_id_(1001)」に変換されますが、「report_title_finance」のように数字を含まない要素は結果の配列から除外されます。このように、preg_filterは特定の条件に合致するデータだけを効率的に選別し、整形する際に役立ちます。