preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match — Realiza uma correspondência com expressão regular

Descrição

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

Pesquisa subject por uma correspondência à expressão regular informada em pattern.

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; caso contrário elas são reportadas como strings vazias. 

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

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"
}
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.

Note:

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 ao invés da âncora ^, ou o modificador A, ambos funcionam com o parâmetro offset.

Valor Retornado

preg_match() retorna 1 se pattern corresponder a subject, 0 se não corresponder, ou false em caso de falha.

Warning

Esta função pode retornar o valor booleano false, mas também pode retornar um valor não booleano que pode ser avaliado como false. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

Erros/Exceções

Se o padrão de expressão regular passado não for compilado para uma expressão regular válida, um E_WARNING será emitido.

Registro de Alterações

Versão Descrição
7.2.0 A constante PREG_UNMATCHED_AS_NULL agora é suportada para o parâmetro $flags.

Exemplos

Example #1 Encontrando a string de texto "php"

<?php
// A letra "i" após o delimitador da expressão indica uma pesquisa insensível a maiúsculas/minúsculas
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
    echo "Uma correspondência foi encontrada.";
} else {
    echo "Uma correspondência foi encontrada.";
}
?>

Example #2 Encontrando a palavra "web"

<?php
/* \b na expressão indica uma borda de palavra, portanto somente a palavra
 * separada "web" é correspondida, e não uma palavra que contém "web" como "webbing" or "cobweb" */
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
    echo "Uma correspondência foi encontrada.";
} else {
    echo "Uma correspondência foi encontrada.";
}

if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
    echo "Uma correspondência foi encontrada.";
} else {
    echo "Uma correspondência foi encontrada.";
}
?>

Example #3 Obtendo o nome de domínio de uma URL

<?php
// obtem o nome do servidor da URL
preg_match('@^(?:http://)?([^/]+)@i',
    "http://www.php.net/index.html", $matches);
$host = $matches[1];

// obtém os últimos dois segmentos do nome do servidor
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "nome de domínio é: {$matches[0]}\n";
?>

O exemplo acima produzirá:

nome de domínio é: php.net

Example #4 Usando sub-expressão nomeada

<?php

$str = 'foobar: 2008';

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

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

print_r($matches);

?>

O exemplo acima produzirá:

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

Notas

Tip

Não use preg_match() se for requerido apenas verificar se uma string está contida em outra. Use strpos() em seu lugar, pois será mais rápida.

Veja Também