sscanf()

A função PHP sscanf() lê uma string e extrai valores de acordo com um formato que você descreve — ela é o inverso de sprintf(). Enquanto sprintf() constrói uma string formatada a partir de variáveis, sscanf() desmonta uma string formatada de volta em variáveis. Ela brilha quando você tem texto em um formato previsível (datas, coordenadas, linhas de log, códigos de ID) e deseja partes limpas e tipadas sem precisar escrever uma expressão regular.

Este capítulo aborda a sintaxe, as duas formas de receber resultados, os especificadores de formato que você realmente usará e as armadilhas comuns.

Sintaxe

sscanf(string $string, string $format, mixed &...$vars): array|int|null

• $string — o texto de entrada a ser analisado.
• $format — um modelo que descreve o que ler, usando especificadores % (a mesma família que printf usa).
• &...$vars — variáveis opcionais, passadas por referência, que recebem os valores analisados.

O comportamento de sscanf() depende de você passar ou não essas variáveis extras:

Retornar os valores como um array

Se você omitir os argumentos por referência, sscanf() retorna tudo como um array. Este é o estilo mais limpo no PHP moderno e evita passar variáveis por referência.

%s lê a próxima palavra sem espaço em branco (John), e %d lê um inteiro (25, armazenado como um int real, não a string "25"). A saída é:

John
25

Atribuir diretamente em variáveis

Passar variáveis após o formato atribui valores diretamente a elas. Neste modo, o valor de retorno é a contagem de campos que corresponderam, o que é útil para validar entradas.

<?php
$input = 'John 25';
$matched = sscanf($input, '%s %d', $name, $age);

echo $matched . "\n"; // 2  (both fields were read)
echo $name . "\n";    // John
echo $age;            // 25
?>

Nota: no PHP 8, o prefixo & no momento da chamada (ex.: sscanf($s, $f, &$name)) foi removido. Basta passar a variável simples — sscanf() declara esses parâmetros como por referência por conta própria.

Especificadores de formato comuns

Caracteres literais no formato (espaços, barras, dois-pontos) também devem aparecer na entrada. Isso torna sscanf() excelente para dados de formato fixo, como datas:

<?php
$date = '2026-06-21';
[$year, $month, $day] = sscanf($date, '%d-%d-%d');

printf("Year=%d Month=%d Day=%d", $year, $month, $day);
// Year=2026 Month=6 Day=21
?>

Quando usar sscanf() vs. alternativas

• Use sscanf() quando o formato for fixo e simples e você quiser resultados tipados em uma linha.
• Use explode() quando precisar apenas dividir por um delimitador e manter tudo como strings.
• Use preg_match() quando a estrutura for irregular ou precisar de regras de validação que vão além de tipos de campo simples.
• Para fazer o inverso — montar uma string formatada — use sprintf() ou printf().

Para ler entradas formatadas diretamente de um arquivo em vez de uma string, veja fscanf(), que funciona da mesma forma linha por linha.

Armadilhas

• %s para no espaço em branco. Ele não capturará um valor com várias palavras. Para ler o restante de uma linha, use um conjunto de varredura como %[^\n].
• Um campo sem correspondência interrompe o restante. Se %d é esperado, mas a entrada tem letras, a análise para; o valor de retorno de contagem permite detectar isso.
• Variáveis à direita sem correspondência tornam-se null. Sempre verifique a contagem retornada antes de confiar nas variáveis seguintes.

Prática