説明

preg_match(
    string $pattern,
    string $subject,
    array &$matches = null,
    int $flags = 0,
    int $offset = 0
): int|false

pattern で指定した正規表現により subject を検索します。

パラメータ

pattern

検索するパターンを表す文字列。

subject

入力文字列。

matches

matches を指定した場合、検索結果が代入されます。 $matches[0] にはパターン全体にマッチしたテキストが代入され、 $matches[1] には 1 番目のキャプチャ用サブパターンにマッチした文字列が代入され、といったようになります。

flags

flags には以下のフラグの組み合わせを指定できます。

PREG_OFFSET_CAPTURE

このフラグを設定した場合、各マッチに対応する文字列のオフセットも(バイト単位で)返されます。これは、matches の値を配列の配列に変更することに注意してください。配列のすべての要素が、オフセット 0 に、マッチした文字列、オフセット 1 に、subject 内でのその文字列のオフセットからなる配列になります。

<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

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

Array
(
    [0] => Array
        (
            [0] => foobarbaz
            [1] => 0
        )

    [1] => Array
        (
            [0] => foo
            [1] => 0
        )

    [2] => Array
        (
            [0] => bar
            [1] => 3
        )

    [3] => Array
        (
            [0] => baz
            [1] => 6
        )

)

PREG_UNMATCHED_AS_NULL

このフラグを設定すると、サブパターンがマッチしなかった場合に null が渡されます。通常は、空の string が渡されます。

<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>

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

array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  string(0) ""
  [3]=>
  string(1) "c"
}
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  string(1) "c"
}

offset

通常、検索は対象文字列の先頭から開始されます。オプションのパラメータ offset を使用して検索の開始位置を (バイト単位で) 指定することも可能です。

注意:
offset を用いるのと、 substr($subject, $offset) を preg_match()の対象文字列として指定するのとは等価ではありません。これは、pattern には、 ^, $ や (?<=x) のような言明を含めることができるためです。以下を比べてみてください。
<?php $subject = "abcdef"; $pattern = '/^def/'; preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3); print_r($matches); ?>

上の例の出力は以下となります。
Array
(
)
一方、この例を見てください。

<?php $subject = "abcdef"; $pattern = '/^def/'; preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE); print_r($matches); ?>

出力は以下のようになります。
Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)
substr() 関数を利用しない別の方法として、 ^ アンカーではなく、言明 \G または A 修正子を使う方法があります。これらは両方とも offset パラメータとともに動作します。

戻り値

preg_match() は、pattern が指定した subject にマッチした場合に 1 を返します。マッチしなかった場合は 0 を返します。失敗した場合に false を返します

警告

この関数は論理値 false を返す可能性がありますが、false として評価される値を返す可能性もあります。詳細については論理値のセクションを参照してください。この関数の返り値を調べるには ===演算子を使用してください。

エラー / 例外

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

変更履歴

バージョン説明

7.2.0 $flags パラメータが PREG_UNMATCHED_AS_NULL をサポートしました。

バージョン	説明
7.2.0	`$flags` パラメータが `PREG_UNMATCHED_AS_NULL` をサポートしました。

例

例1 文字列 "php" を探す

<?php
// パターンのデリミタの後の "i" は、大小文字を区別しない検索を示す
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

例2 単語 "web" を探す

<?php
/* パターン内の \b は単語の境界を示す。このため、独立した単語の
 *  "web"にのみマッチし、"webbing" や "cobweb" のような単語の一部にはマッチしない */
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}

echo "\n";

if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

例3 URL からドメイン名を得る

<?php
// get host name from URL
preg_match('@^(?:http://)?([^/]+)@i',
    "http://www.php.net/index.html", $matches);
$host = $matches[1];

// get last two segments of host name
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>

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

domain name is: php.net

例4 名前つきサブパターンの使用法

<?php

$str = 'foobar: 2008';

preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

/* 別のやり方 */
// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

print_r($matches);

?>

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

Array
(
    [0] => foobar: 2008
    [name] => foobar
    [1] => foobar
    [digit] => 2008
    [2] => 2008
)

注意

ヒント

ある文字列が他の文字列内に含まれているかどうかを調べるためだけに preg_match() を使うのは避けた方が良いでしょう。 strpos() 関数を使うほうが速くなります。

参考

PCRE のパターン
preg_quote() - 正規表現文字をクオートする
preg_match_all() - 繰り返し正規表現検索を行う
preg_replace() - 正規表現検索および置換を行う
preg_split() - 正規表現で文字列を分割する
preg_last_error() - 直近の PCRE 正規表現処理のエラーコードを返す
preg_last_error_msg() - 最後に実行した PCRE 正規表現に関するエラーメッセージを返す