preg_match

Parâmetros

pattern

A expressão sendo procurada, como uma string.

subject

A string de entrada.

matches

Se matches for informada, será preenchida com os resultados da pesquisa. $matches[0] contéra o texto que correspondeu à expressão inteira, $matches[1] terá o texto que correspondeu à primeira sub-expressão entre parênteses capturada, e assim por diante.

flags

flags pode ser uma combinação das seguintes constantes:

PREG_OFFSET_CAPTURE

Se esta constante for passada, para cada correspondência o deslocamento (em bytes) da string também será retornado. Observe que isto modifica o valor de matches para um array de arrays onde cada elemento é um array que consiste na string correspondida no elemento 0 e seu deslocamento na string subject no elemento 1.

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

O exemplo acima produzirá:

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

Se esta constante for passada, sub-expressões não correspondidas são reportadas como null e sempre são incluídas nos resultados (incluindo as finais). Sem esta constante, subpadrões não correspondidos que são seguidos por um subpadrão correspondente são reportados como uma string vazia, enquanto subpadrões não correspondidos finais são omitidos dos resultados completamente.

<?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);

// Trailing unmatched subpatterns:
preg_match('/(a)(b)?(c)?/', 'a', $matches);
var_dump($matches);
preg_match('/(a)(b)?(c)?/', 'a', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>

O exemplo acima produzirá:

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"
}
array(2) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "a"
}
array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  NULL
}

offset

Normalmente, a pesquisa começa no início da string de entrada. O parâmetro opcional offset pode ser usado para especificar o deslocamento alternativo (em bytes) a partir do qual a pesquisa será iniciada.

Nota:

Usar offset não é equivalente a passar substr($subject, $offset) para preg_match() no lugar da string de entrada, porque pattern pode conter afirmações como ^, $ ou (?<=x) que depende da string inteira. Compare:

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

O exemplo acima produzirá:

Array
(
)

enquanto este exemplo

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

produz

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

)

Alternativamente, para evitar o uso de substr(), use a afirmação \G no lugar da âncora ^, ou o modificador A; ambos não funcionam com o parâmetro offset.