array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.mb-detect-encoding.php', 1 => 'mb_detect_encoding', 2 => 'Detectar a codificação de caracteres', ), 'up' => array ( 0 => 'ref.mbstring.php', 1 => 'Strings Multibyte e Funções', ), 'prev' => array ( 0 => 'function.mb-decode-numericentity.php', 1 => 'mb_decode_numericentity', ), 'next' => array ( 0 => 'function.mb-detect-order.php', 1 => 'mb_detect_order', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/mbstring/functions/mb-detect-encoding.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Detectar a codificação de caracteres

Descrição

mb_detect_encoding(string $string, array|string|null $encodings = null, bool $strict = false): string|false

Detecta a codificação de caracteres mais provável para a string string a partir de uma lista de candidatos.

A partir do PHP 8.1, esta função usa heurística para detectar qual das codificações de texto válidas na lista especificada tem maior probabilidade de estar correta e pode não estar na ordem das codificações fornecidas no parâmetro encodings.

A detecção automática da codificação de caracteres pretendida nunca pode ser totalmente confiável; sem informações adicionais, é semelhante a decodificar uma string criptografada sem a chave. É sempre preferível usar uma indicação de codificação de caracteres armazenada ou transmitida com os dados, como um cabeçalho HTTP "Content-Type".

Esta função é mais útil com codificações multibyte, onde nem todas as sequências de bytes formam uma string válida. Se a string de entrada contiver tal sequência, essa codificação será rejeitada.

Aviso

O resultado não é preciso

O nome dessa função é enganoso: ela realiza "adivinhação" em vez de "detecção".

Os palpites estão longe de ser precisos e, portanto, esta função não pode ser usada para detectar com precisão a codificação correta de caracteres.

Parâmetros

string

A string sendo inspecionada.

encodings

Uma lista de codificações de caracteres para tentar. A lista pode ser especificada como um array de strings ou uma única string separada por vírgulas.

Se encodings for omitido ou null, a detect_order atual (definida com a opção de configuração mbstring.detect_order, ou função mb_detect_order()) será usada.

strict

Controla o comportamento quando string não é válida em nenhuma das encodings listadas. Se strict for definido como false, a codificação mais próxima correspondente será retornada; se strict for definido como true, false será retornado.

O valor padrão para strict pode ser definido com a opção de configuração mbstring.strict_detection.

Valor Retornado

A codificação de caracteres detectada ou false se a string não for válida em nenhuma das codificações listadas.

Registro de Alterações

Versão Descrição
8.2.0 mb_detect_encoding() não retornará mais as seguintes codificações não textuais: "Base64", "QPrint", "UUencode", "HTML entities", "7 bit" e "8 bit".

Exemplos

Exemplo #1 Exemplo de mb_detect_encoding()

<?php

$str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

// Detecta codificação de caracteres com a ordem de detecção atual
var_dump(mb_detect_encoding($str));

// "auto" é expandido de acordo com mbstring.language
var_dump(mb_detect_encoding($str, "auto"));

// Especifica parâmetro "encodings" com lista separada por vírgula
var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

// Usa array para especificar parâmetro "encodings"
$encodings = [
"ASCII",
"JIS",
"EUC-JP"
];
var_dump(mb_detect_encoding($str, $encodings));
?>

O exemplo acima produzirá:

string(5) "ASCII"
string(5) "ASCII"
string(8) "SJIS-win"
string(5) "ASCII"

Exemplo #2 Efeito do parâmetro strict

<?php
// 'áéóú' codificado em ISO-8859-1
$str = "\xE1\xE9\xF3\xFA";

// A string não é válida em ASCII ou UTF-8, mas UTF-8 é considerado uma correspondência mais próxima
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

// Se uma codificação válida for encontrada, o parâmetro strict não muda o resultado
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
?>

O exemplo acima produzirá:

string(5) "UTF-8"
bool(false)
string(10) "ISO-8859-1"
string(10) "ISO-8859-1"

Em alguns casos, a mesma sequência de bytes pode formar uma string válida em várias codificações de caracteres, e é impossível saber qual interpretação foi pretendida. Por exemplo, entre muitos outros, a sequência de bytes "\xC4\xA2" poderia ser:

Exemplo #3 Efeito da ordem quando várias codificações correspondem

<?php
$str = "\xC4\xA2";

// A string é válida em todas as três codificações, mas a primeira listada pode nem sempre ser a retornada
var_dump(mb_detect_encoding($str, ['UTF-8']));
var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // a partir do PHP 8.1, retorna ISO-8859-1 em vez de UTF-8
var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
?>

O exemplo acima produzirá:

string(5) "UTF-8"
string(10) "ISO-8859-1"
string(10) "ISO-8859-1"
string(10) "ISO-8859-5"

Veja Também