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

<?php

/**
 * 文字列内で正規表現パターンに最初に一致する部分を検索します。
 *
 * この関数はPHPのpreg_match関数を使用して、正規表現による単一マッチングの基本を示します。
 * preg_match_allは文字列内の全ての出現を検索するのに対し、preg_matchは最初に見つかった一致のみを検索します。
 *
 * @param string $subject 検索対象の文字列。
 * @return void
 */
function demonstratePregMatchBasic(string $subject): void
{
    // 検索したい正規表現パターンを定義します。
    // この例では、「PHP」という単語を検索します。
    // かっこ () は「キャプチャグループ」と呼ばれ、一致した部分を個別に取得できます。
    // i 修飾子は、大文字・小文字を区別しないマッチングを意味します。
    $pattern = '/(PHP)/i';

    echo "対象文字列: \"" . $subject . "\"\n";
    echo "検索パターン: \"" . $pattern . "\"\n\n";

    // preg_match関数を実行します。
    // - $pattern: 検索する正規表現
    // - $subject: 検索対象の文字列
    // - $matches: 検索結果を格納する配列 (参照渡し)。
    //            $matches[0]にはパターン全体の一致、
    //            $matches[1]以降にはキャプチャグループの一致が格納されます。
    // 戻り値は一致した回数 (0または1) です。一致しない場合はfalseを返します。
    if (preg_match($pattern, $subject, $matches)) {
        echo "一致が見つかりました！\n";
        echo "---------------------------------\n";
        echo "完全な一致 (パターン全体): " . $matches[0] . "\n";
        
        // キャプチャグループが存在する場合、それらも表示
        if (isset($matches[1])) {
            echo "キャプチャグループ1の一致: " . $matches[1] . "\n";
        }

        echo "\n全てのマッチ情報 (配列形式):\n";
        print_r($matches);
    } else {
        echo "一致は見つかりませんでした。\n";
    }
}

// 関数の実行例
demonstratePregMatchBasic("This is a PHP 8.4.12 string.");
echo "\n=================================\n\n";
demonstratePregMatchBasic("Another example with php version.");
echo "\n=================================\n\n";
demonstratePregMatchBasic("No match here.");

PHPのpreg_match関数は、文字列の中から特定のパターン（正規表現）に最初に一致する部分を検索するために使用されます。文字列内に出現する全ての一致を検索するpreg_match_all関数とは異なり、preg_matchは最初に見つかった一致のみを検出します。

この関数は、検索したい正規表現パターンを定義する$pattern、検索対象の文字列を指定する$subject、そして検索結果を格納するための配列である&$matchesという主要な引数を持ちます。$matches配列には、パターン全体に一致した部分が$matches[0]に、正規表現内で指定されたキャプチャグループに一致した部分が$matches[1]以降に格納されます。

関数の戻り値は、一致が見つかった場合に1を返します。一致するパターンが見つからなかった場合は0を返し、正規表現の構文エラーなどによって処理が失敗した場合はfalseを返します。サンプルコードでは、「PHP」という単語を大文字・小文字を区別せずに検索し、一致した場合にその内容とキャプチャグループの情報を表示することで、preg_matchの基本的な使い方と結果の取得方法を示しています。

<?php

/**
 * preg_match関数の基本的な使用例とマッチした値の取得方法を示します。
 *
 * この関数は、文字列が特定の正規表現パターンに合致するかどうかをチェックし、
 * 合致した場合、マッチした部分を配列に格納します。
 * preg_matchは、最初に見つかったマッチのみを処理します。
 */
function demonstratePregMatch(): void
{
    // 検証対象の文字列
    $subject = "今日は2023-10-26です。明日は2023-10-27でしょう。";

    // 日付形式 (YYYY-MM-DD) にマッチする正規表現パターン
    // かっこ () で囲まれた部分は「キャプチャグループ」と呼ばれ、
    // マッチした値が $matches 配列に個別に格納されます。
    // \d{4} は4桁の数字、\d{2} は2桁の数字を表します。
    // - はリテラルなハイフンです。
    $pattern = '/(\d{4})-(\d{2})-(\d{2})/';

    echo "--- preg_matchの基本 ---" . PHP_EOL;
    echo "対象文字列: " . $subject . PHP_EOL;
    echo "パターン: " . $pattern . PHP_EOL . PHP_EOL;

    // preg_match関数を実行
    // $matches 変数には、マッチした結果が配列として格納されます。(参照渡し)
    // 第一引数: 正規表現パターン
    // 第二引数: 検索対象の文字列
    // 第三引数: マッチした結果を格納する配列
    $result = preg_match($pattern, $subject, $matches);

    // 戻り値に基づいて結果を表示
    if ($result === 1) {
        echo "正規表現パターンに合致しました。" . PHP_EOL;
        echo "マッチした回数 (最初の1回): " . $result . PHP_EOL;
        echo "マッチした内容（$matches配列）:" . PHP_EOL;
        // $matches[0] には、パターン全体にマッチした文字列が格納されます。
        // $matches[1] 以降には、キャプチャグループにマッチした文字列が格納されます。
        print_r($matches);
        echo "--------------------------" . PHP_EOL;
        echo "年: " . $matches[1] . PHP_EOL;
        echo "月: " . $matches[2] . PHP_EOL;
        echo "日: " . $matches[3] . PHP_EOL;
    } elseif ($result === 0) {
        echo "正規表現パターンに合致しませんでした。" . PHP_EOL;
    } else { // $result === false の場合 (正規表現パターンに問題があるなどのエラー)
        echo "preg_match関数でエラーが発生しました。" . PHP_EOL;
    }

    echo PHP_EOL . "--- マッチしない場合の例 ---" . PHP_EOL;
    $subjectNoMatch = "今日の天気は晴れです。";
    $resultNoMatch = preg_match($pattern, $subjectNoMatch, $matchesNoMatch);

    echo "対象文字列: " . $subjectNoMatch . PHP_EOL;
    echo "パターン: " . $pattern . PHP_EOL . PHP_EOL;

    if ($resultNoMatch === 1) {
        echo "正規表現パターンに合致しました。" . PHP_EOL;
    } elseif ($resultNoMatch === 0) {
        echo "正規表現パターンに合致しませんでした。" . PHP_EOL;
    } else {
        echo "preg_match関数でエラーが発生しました。" . PHP_EOL;
    }
}

// 関数の実行
demonstratePregMatch();

PHPのpreg_match関数は、指定した正規表現パターンが対象の文字列中に存在するかどうかを検索する際に使用されます。この関数は、最初に見つかった合致のみを処理し、それ以降の合致は無視します。

第一引数には検索したい正規表現パターンを、第二引数には検索対象の文字列を指定します。第三引数の$matchesは参照渡しの配列で、パターンに合致した結果が格納されます。具体的には$matches[0]にパターン全体にマッチした部分が、正規表現の括弧()で囲まれた「キャプチャグループ」にマッチした内容は$matches[1]以降に順に格納されます。

関数の戻り値は整数またはfalseです。パターンに合致した場合、つまり検索対象の文字列からパターンに該当する部分が見つかった場合は1を返します。合致しなかった場合、見つからなかった場合は0を返します。正規表現パターンに誤りがあるなど、関数の実行中にエラーが発生した場合はfalseを返します。

サンプルコードでは、"今日は2023-10-26です。"という文字列から日付形式YYYY-MM-DDを抽出しています。/(\d{4})-(\d{2})-(\d{2})/というパターンにより、$matches[0]には"2023-10-26"が、$matches[1]には"2023"（年）、$matches[2]には"10"（月）、$matches[3]には"26"（日）がそれぞれ格納されることが示されています。マッチする部分が見つからない場合は、戻り値が0となり、$matches配列は空になります。