Funkcja PHP preg_match()

Funkcja PHP preg_match() przeszukuje tekst przekazany w drugim argumencie w poszukiwaniu fragmentu pasującego do wyrażenia regularnego przekazanego w pierwszym argumencie.

Znaleziony fragment funkcja preg_match() zapisuje w tablicy przekazanej jako trzeci argument. Jeśli nie zostanie on przekazany, nie ma możliwości sprawdzenia, jaki fragment tekstu został znaleziony.

Funkcja ta, w odróżnieniu od funkcji PHP preg_match_all(), kończy działanie po znalezieniu pierwszego pasującego fragmentu.

Przykład

Przeszukiwanie łańcucha znaków PHP za pomocą funkcji PHP preg_match().


preg_match('/k.t/', 'Ala ma kota', $matches);

print_r($matches);

Wynik:

Array
(
    [0] => kot
)

Składnia funkcji PHP preg_match()

Funkcja PHP preg_match() ma następującą składnię:

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

Parametry

Parametr	Opis
`pattern`	Parametr obowiązkowy. Wzorzec do wyszukania. Należy go umieścić w ogranicznikach wyrażenia regularnego, np. między znakami `/` i `/`.
`subject`	Parametr obowiązkowy. Łańcuch znaków do przeszukania.
`matches`	Tablica, w której zostaną umieszczone wyniki wyszukiwania. W elemencie `$matches[0]` zostanie umieszczony cały dopasowany ciąg znaków. Natomiast w kolejnych elementach tej tablicy będą umieszczane ciągi dopasowane przez podwzorce w nawiasach.
`flags`	Flagi modyfikujące sposób działania funkcji. Dostępne są następujące flagi: `PREG_OFFSET_CAPTURE` Powoduje, że razem z dopasowanym fragmentem tekstu zwracana jest jego pozycja w bajtach albo, inaczej mówiąc, zwracany jest numer bajtu, po którym zaczyna się ten tekst. `PREG_UNMATCHED_AS_NULL` Powoduje, że brak dopasowania wzorca jest sygnalizowany wartością `null`, a nie pustym łańcuchem.
`offset`	Określa numer bajtu, po którym ma zostać rozpoczęte przeszukiwanie łańcucha znaków.

Uwaga

Funkcja preg_match() działa na bajtach, nie na znakach. Jeśli o tym zapomnisz, możesz otrzymać zaskakujące wyniki, np.:


preg_match('/o/', 'kółko', $matches, PREG_OFFSET_CAPTURE);

W tym przypadku wynik będzie taki:

Array
(
    [0] => Array
        (
            [0] => o
            [1] => 6
        )

)

Litera o jest piątym znakiem w tym łańcuchu, ale ma indeks 6 (zamiast 4) ponieważ litery ó i ł zajmują po dwa bajty.

Uwaga

Pamiętaj też, że funkcja PHP preg_match() standardowo nie obsługuje znaków UTF-8, ale łatwo jest tę obsługę włączyć. Wystarczy na końcu wyrażenia regularnego dodać literę u, np.:


preg_match('/\w+/', 'żółtko', $matches_1);
preg_match('/\w+/u', 'żółtko', $matches_2);

print_r($matches_1);
print_r($matches_2);

Wynik:

Array
(
    [0] => tko
)
Array
(
    [0] => żółtko
)

Wartość zwrotna

Funkcja PHP preg_match() zwraca wartość 1, jeśli w przeszukiwanym tekście uda się znaleźć ciąg pasujący do szukanego wzorca, lub 0 w przeciwnym przypadku. Ewentualnie zwraca wartość false, jeśli wyrażenie regularne zawiera błąd.

Typ zwrotny: int|false.