Funkcja PHP preg_match_all()

Funkcja PHP preg_match_all() przeszukuje tekst przekazany w drugim argumencie w poszukiwaniu fragmentów pasujących do wyrażenia regularnego przekazanego w pierwszym argumencie.

Znalezione fragmenty funkcja preg_match_all() zapisuje w tablicy przekazanej jako trzeci argument. Jeśli nie zostanie on przekazany, nie ma możliwości sprawdzenia, jakie fragmenty tekstu zostały znalezione.

Funkcja ta, w odróżnieniu od funkcji PHP preg_match(), przeszukuje cały łańcuch i zwraca wszystkie fragmenty pasujące do wyrażenia regularnego.

Przykład

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


preg_match_all('/k.t/', 'kot, kat, kit, pet', $matches);

print_r($matches);

Wynik:

Array
(
    [0] => Array
        (
            [0] => kot
            [1] => kat
            [2] => kit
        )

)

Składnia funkcji PHP preg_match_all()

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

preg_match_all(
    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 wielowymiarowa PHP, w której zostaną umieszczone wyniki wyszukiwania.
`flags`	Flagi modyfikujące sposób działania funkcji. Dostępne są następujące flagi: `PREG_PATTERN_ORDER` Porządkuje wyniki w taki sposób, że element `$matches[0]` jest tablicą zawierającą pełne dopasowania wzorca, element `$matches[1]` jest tablicą łańcuchów pasujących do pierwszego podwzorca w nawiasie, element `$matches[2]` jest tablicą łańcuchów pasujących do drugiego podwzorca w nawiasie itd. `PREG_SET_ORDER` Porządkuje wyniki w taki sposób, że każdy element tablicy wynikowej jest tablicą zawierającą jedno całe dopasowanie w pierwszym elemencie i jego grupy w kolejnych elementach, np.: `preg_match_all('/\b(\w+)@(\w+)(\.com\|\.pl)/', 'jola@example.com, radek@example.pl', $matches, PREG_SET_ORDER); print_r($matches);` Wynik: `Array ( [0] => Array ( [0] => jola@example.com [1] => jola [2] => example [3] => .com ) [1] => Array ( [0] => radek@example.pl [1] => radek [2] => example [3] => .pl ) )` `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_all() działa na bajtach, nie na znakach. Jeśli o tym zapomnisz, możesz otrzymać zaskakujące wyniki, np.:


preg_match_all('/t/', 'kąt, kat', $matches, PREG_OFFSET_CAPTURE);

W tym przypadku wynik będzie taki:

Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => t
                    [1] => 3
                )

            [1] => Array
                (
                    [0] => t
                    [1] => 8
                )

        )
)

Litera t jest trzecim i ósmym znakiem w tym łańcuchu, więc powinna mieć indeksy 2 i 7, ale ponieważ litera ą zajmuje dwa bajty, indeksy litery t to 3 i 8.

Uwaga

Pamiętaj też, że funkcja PHP preg_match_all() 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_all('/\w+/', 'żółtko', $matches_1);
preg_match_all('/\w+/u', 'żółtko', $matches_2);

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

Wynik:

Array
(
    [0] => Array
        (
            [0] => tko
        )

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

Wartość zwrotna

Funkcja PHP preg_match_all() zwraca liczbę znalezionych pełnych dopasowań do wzorca, 0 jeśli nic nie znajdzie lub wartość false, jeśli wyrażenie regularne zawiera błąd.

Typ zwrotny: int|false.