preg_last_error()

Introdução

As expressões regulares são uma ferramenta poderosa para manipular e pesquisar strings em PHP. Ocasionalmente, as operações de regex falham devido a padrões inválidos ou limites do motor. A função preg_last_error() ajuda a identificar essas falhas retornando o código de erro da última chamada à função PCRE.

Sintaxe

preg_last_error(): int

A função não recebe argumentos. Ela retorna uma constante inteira descrevendo o que deu errado durante a última chamada à função PCRE — como preg_match(), preg_match_all(), preg_replace() ou preg_split(). Se a última chamada foi bem-sucedida, retorna PREG_NO_ERROR (0).

Por que você precisa dela

As funções PCRE são incomuns: quando falham, elas não lançam uma exceção. Em vez disso, preg_match() retorna false (não 0 — isso significa "sem correspondência"), e preg_replace() retorna null. Esses valores de retorno informam que algo falhou, mas não por quê. preg_last_error() preenche essa lacuna relatando a razão subjacente.

É por isso que você deve comparar com === em vez de um == solto: 0 (sem correspondência) e false (erro) parecem "falsy", mas têm significados muito diferentes.

Constantes de erro

preg_last_error() retorna uma dessas constantes inteiras. Os valores numéricos são mostrados para referência, mas você deve sempre comparar com a constante nomeada.

Desde o PHP 8.0, preg_last_error_msg() retorna as mesmas informações como uma string legível por humanos, o que é útil para logging.

Provocando e lendo um erro

Uma falha comum no mundo real é o backtracking catastrófico, onde um padrão mal escrito força o motor a tentar um número enorme de caminhos e aciona o limite de backtrack. O exemplo abaixo reduz o pcre.backtrack_limit para que a falha seja reproduzível e, em seguida, inspeciona o resultado.

<?php

// Lower the limit so the failure is easy to reproduce.
ini_set('pcre.backtrack_limit', '100');

$pattern = '/(\w+)*$/';            // nested quantifier — backtracks heavily
$string  = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaa!';

$result = preg_match($pattern, $string, $matches);

if ($result === false) {
    echo 'preg_match() failed!' . PHP_EOL;
    echo 'Error code: ' . preg_last_error() . PHP_EOL;
    echo 'Error message: ' . preg_last_error_msg() . PHP_EOL;

    if (preg_last_error() === PREG_BACKTRACK_LIMIT_ERROR) {
        echo 'The pattern was too expensive to evaluate.' . PHP_EOL;
    }
} elseif ($result === 1) {
    echo 'Match found.' . PHP_EOL;
} else {
    echo 'No match.' . PHP_EOL;
}

Saída:

preg_match() failed!
Error code: 2
Error message: Backtrack limit exhausted
The pattern was too expensive to evaluate.

O código de erro 2 é PREG_BACKTRACK_LIMIT_ERROR. Crucialmente, a verificação if ($result === false) é o que nos diz que ocorreu um erro real — um 0 aqui simplesmente significaria que o padrão não correspondeu.

Detectando entrada UTF-8 inválida

Quando você usa o modificador u (unicode) em uma string que não é UTF-8 válido, o PCRE interrompe a execução e define PREG_BAD_UTF8_ERROR:

<?php

$result = preg_match('/./u', "\x80");   // \x80 is not a valid UTF-8 sequence

if ($result === false && preg_last_error() === PREG_BAD_UTF8_ERROR) {
    echo 'Invalid UTF-8 input: ' . preg_last_error_msg();
}
// Invalid UTF-8 input: Malformed UTF-8 characters, possibly incorrectly encoded

Esta é uma fonte frequente de bugs silenciosos ao processar dados enviados por usuários, portanto, proteger-se contra isso é uma boa prática.

Armadilhas comuns

• Verifique imediatamente. preg_last_error() reflete apenas a chamada PCRE mais recente. Qualquer chamada regex posterior o substitui, portanto, leia-o logo após a operação que você se preocupa.
• false vs 0. Sempre use ===. preg_match() retorna 0 para "sem correspondência" e false para um erro — eles não são intercambiáveis.
• Falhas de preg_replace(). Quando preg_replace() retorna null, também vale a pena chamar preg_last_error() para saber o motivo.

Conclusão

preg_last_error() transforma um retorno opaco de false em uma razão acionável, tornando-a essencial para depurar expressões regulares em PHP. Ao comparar valores de retorno com === e inspecionar o código de erro (ou preg_last_error_msg()), você pode separar claramente as falhas do motor das simples não-correspondências. Para as funções cujas falhas ela reporta, consulte preg_match(), preg_replace() e preg_split().

Prática