preg_match()

Introdução

preg_match() realiza uma correspondência com expressão regular em uma string. Ela informa se um padrão PCRE ocorre em um sujeito e, opcionalmente, captura o que foi correspondido. Ela para na primeira correspondência — se você precisar de todas as ocorrências, use preg_match_all() em vez disso.

Este capítulo abrange a assinatura e os valores de retorno, como o array $matches é preenchido, os flags mais úteis e as armadilhas (a armadilha 0 vs false, ancoragem, delimitadores) que costumam confundir as pessoas.

Sintaxe

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

Valor de retorno: 1 se o padrão correspondeu, 0 se não correspondeu, ou false em caso de erro (padrão inválido). Como preg_match() retorna no máximo 1, ela nunca informa quantas correspondências existem — apenas que havia uma.

Exemplo básico

O padrão captura uma palavra alfabética seguida de espaço em branco e outra palavra. Em uma correspondência, $matches[0] contém a correspondência completa (This is), e $matches[1] / $matches[2] contêm os dois grupos capturados (This e is).

A armadilha 0 vs false

Um erro muito comum é usar == para testar o resultado. preg_match() retorna 0 para "sem correspondência" e false apenas para um erro, e 0 == false é true em PHP. Sempre compare com o operador estrito:

<?php

$result = preg_match('/[0-9]+/', 'abc');

// Wrong: treats "no match" and "error" the same
if ($result == false) {
  echo "ambiguous\n";
}

// Right: distinguish the three outcomes
if ($result === false) {
  echo "Error in the pattern\n";
} elseif ($result === 0) {
  echo "No match\n";
} else {
  echo "Matched\n";
}

Isso imprime ambiguous e depois No match.

Grupos nomeados

Adicione (?<name>...) ao seu padrão e $matches conterá as capturas tanto pelo índice numérico quanto pelo nome, o que mantém o código legível quando a ordem dos grupos muda:

<?php

$date = '2026-06-21';
preg_match('/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/', $date, $m);

echo $m['year'] . "\n";  // 2026
echo $m['month'] . "\n"; // 06
echo $m['day'];          // 21

Capturando deslocamentos com PREG_OFFSET_CAPTURE

Passe o flag PREG_OFFSET_CAPTURE e cada entrada em $matches torna-se um par [texto_correspondido, deslocamento_em_bytes], para que você possa saber onde a correspondência ocorreu:

<?php

preg_match('/world/', 'hello world', $m, PREG_OFFSET_CAPTURE);

echo $m[0][0] . "\n"; // world
echo $m[0][1];        // 6

Padrões sem diferenciação de maiúsculas e ancorados

Os modificadores vão após o delimitador de fechamento. O modificador i ignora maiúsculas e minúsculas; ^ e $ ancoram a correspondência ao início e ao fim da string, de modo que todo o sujeito deve corresponder ao padrão:

<?php

var_dump(preg_match('/^hello$/i', 'HELLO')); // int(1)
var_dump(preg_match('/^hello$/i', 'hello!')); // int(0)

Quando usar outra alternativa

• Todas as ocorrências, não apenas a primeira → preg_match_all().
• Encontrar e substituir → preg_replace().
• Dividir uma string por um padrão → preg_split(); para um delimitador fixo, o simples explode() é mais rápido.
• Escapar entrada do usuário antes de incorporá-la em um padrão → preg_quote().
• Uma revisão da sintaxe PCRE → o capítulo sobre expressões regulares PHP.

Conclusão

preg_match() é a função ideal para testar se uma string corresponde a um padrão e extrair grupos capturados. Lembre-se dos seus três valores de retorno, compare com === para evitar a armadilha 0/false, e mude para preg_match_all() quando uma única correspondência não for suficiente.

Prática