PHP 8.6: Novos Recursos, Funções Depreciadas e um Guia Prático de Migração
Atualize para o PHP 8.6 com exemplos antes e depois para funções PHP depreciadas, MySQLi, mbstring, CSV, sessões e um checklist prático de migração.
PHP 8.6.0 foi lançado em 19 de novembro de 2026. Os recursos principais são interessantes, mas para desenvolvedores que mantêm sites reais a pergunta urgente é muitas vezes diferente: quais linhas do código existente começarão a emitir avisos de depreciação, e como elas devem ser reescritas?
Esta guia coloca o trabalho de migração primeiro. Cada exemplo identifica uma API descontinuada, mostra uma substituição e destaca onde uma substituição mecânica de busca e substituição seria perigosa. Um aviso de deprecação não é o mesmo que um erro fatal imediato: ele avisa que o código precisa de atenção, muitas vezes antes que uma versão major futura remova a API.
1. Verifique o runtime antes de tocar em produção
Execute estes comandos no mesmo ambiente PHP que serve a aplicação (CLI e PHP web podem usar binários e configurações diferentes):
php -v
php -m
php --ini
Verifique as extensões usadas pelo projeto, especialmente mbstring, mysqli e intl. Verifique se o framework, CMS, extensões e ambiente de hospedagem suportam explicitamente o PHP 8.6; não infira compatibilidade apenas porque um site inicia.
Em um ambiente de staging, registre todos os erros mantendo as mensagens de diagnóstico fora do HTML público:
<?php
error_reporting(E_ALL);
ini_set('log_errors', '1');
ini_set('display_errors', '0');
Estas configurações de runtime são úteis para um teste controlado. Prefira configurar o logging no nível do servidor para ambientes de longa duração; garanta que o log de erros seja gravável e privado. Uma mensagem do Deprecated é acionável mesmo quando a página ainda é renderizada.
2. Referência rápida: APIs descontinuadas e o que usar em vez disso
| Descontinuada no PHP 8.6 | Abordagem recomendada | Advertência de migração |
|---|---|---|
is_integer(), is_long() |
is_int() |
Aliases diretos |
is_double() |
is_float() |
Alias direto |
doubleval() |
floatval() |
Alias direto |
spl_object_hash() |
spl_object_id() |
Alteração de tipo de retorno de string para int |
mb_ereg(), mb_eregi() |
preg_match() |
Adaptar sintaxe de padrão e flags Unicode |
mb_ereg_replace() |
preg_replace() |
Verificar escape, semântica de substituição e erros |
mysqli_stmt_init() |
mysqli_prepare() |
Prepare-se imediatamente |
mysqli_get_charset() |
mysqli_character_set_name() |
Apenas se o nome do charset for necessário |
SplFileObject::fgetcsv() |
fgetcsv() em um stream |
Revisar posição do stream e configurações CSV |
SplFileObject::fputcsv() |
fputcsv() em um stream |
Passar delimitador, encapsulamento e escape explicitamente |
strcoll() |
Collator::compare() |
Requer intl; escolha um locale |
SORT_LOCALE_STRING |
Collator::sort() / asort() |
O comportamento do locale pode mudar |
spl_classes() |
ReflectionExtension::getClassNames() |
Inspecionar a extensão apropriada |
Third argument of define() |
Omit the argument | O modo antigo sem diferenciação de caso não existe mais |
return in finally |
Return outside finally |
Evite suprimir exceções |
Object passed to array_walk() |
get_object_vars() first |
Edições por referência podem não mutar mais o objeto |
metaphone() |
A maintained phonetic implementation | Nenhuma substituição central pronta para uso |
Algumas APIs não têm substituição exata. A migração correta pode exigir alterar o design em vez de renomear uma função. Veja a lista oficial de deprecações do PHP 8.6.
3. Aliases simples: correções seguras e rápidas
Antes — descontinuado:
<?php
if (is_integer($quantity) && is_double($price)) {
$total = doubleval($price) * $quantity;
}
Depois:
<?php
if (is_int($quantity) && is_float($price)) {
$total = floatval($price) * $quantity;
}
Os aliases têm o mesmo significado. Não assuma que is_float(40) é verdadeiro: um inteiro permanece um inteiro. Esse comportamento já existia antes da migração.
Para um valor em string, floatval() é uma conversão, não uma representação decimal segura para dinheiro. Mantenha a estratégia existente de tratamento de dinheiro do projeto em vez de alterá-la como parte de um upgrade do PHP não relacionado.
4. Migrando expressões regulares do mbstring
A família mb_ereg* está descontinuada porque seu motor de regex Oniguruma subjacente não é mais mantido. O PHP recomenda o PCRE para muitos casos de uso, mas os dialetos de padrão não são idênticos.
Antes:
<?php
$isReference = mb_ereg('^[0-9]+$', $reference) !== false;
Depois (apenas dígitos ASCII):
<?php
$isReference = preg_match('/^[0-9]+$/D', $reference) === 1;
Aqui o modificador D faz com que o $ corresponda apenas no final do assunto. Para texto Unicode, use um padrão UTF-8 adequado e o modificador u:
<?php
$isName = preg_match('/^\p{L}+(?:[ -]\p{L}+)*$/uD', $name) === 1;
Antes — substituição:
<?php
$clean = mb_ereg_replace('[[:space:]]+', ' ', $text);

Depois — substituição:
<?php
$clean = preg_replace('/\s+/u', ' ', $text);
if ($clean === null) {
throw new RuntimeException('Regular expression failed');
}
Os dois padrões podem diferir em alguns espaços em branco Unicode. Para migrações reais, teste caracteres acentuados, quebras de linha, UTF-8 inválido, grupos de captura e referências retroativas contra dados reais do projeto. Não substitua em massa todas as chamadas de mb_ereg sem revisar a expressão.
5. MySQLi: prepare uma instrução em um único passo
Antes — descontinuado:
<?php
$stmt = mysqli_stmt_init($mysqli);
mysqli_stmt_prepare($stmt, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
Depois:
<?php
$stmt = mysqli_prepare($mysqli, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
Com a API orientada a objetos, use $mysqli->prepare($sql) em vez de $mysqli->stmt_init() seguido por prepare(). Mantenha seu tratamento de erros existente e feche as instruções adequadamente.
A API separada mysqli_get_charset() também está descontinuada. Se você só precisa do nome atual do charset:
<?php
$charsetName = mysqli_character_set_name($mysqli);
Isso não é uma substituição para todos os campos do objeto antigo de informações de charset. Se o código depender de metadados de collation, inspecione o que ele realmente precisa e consulte o servidor adequadamente.
6. CSV: substituir métodos CSV descontinuados do SplFileObject
Os métodos CSV específicos do SplFileObject estão descontinuados. Para código novo e migrado, use as funções baseadas em stream fgetcsv() e fputcsv().
Antes:
<?php
$file = new SplFileObject($path, 'r');
while (!$file->eof()) {
$row = $file->fgetcsv();
// Process row
}
Depois:
<?php
$handle = fopen($path, 'rb');
if ($handle === false) {
throw new RuntimeException('Cannot open CSV file');
}
try {
while (($row = fgetcsv($handle, 0, ',', '"', '')) !== false) {
// Process row
}
} finally {
fclose($handle);
}
O argumento vazio de escape desativa o mecanismo de escape proprietário do PHP; teste essa escolha contra o formato que o sistema de origem exporta. Verifique linhas em branco, cabeçalhos, delimitadores, quebras de linha incorporadas e codificação. Este exemplo ilustra a mudança na API, não um parser CSV universal.
Para escrita, use fputcsv($handle, $fields, ',', '"', ''). Mantenha o dialeto esperado do arquivo original.
7. Identidade de objeto: spl_object_hash() não é um hash de conteúdo
Antes:
<?php
$key = spl_object_hash($object);
Depois:
<?php
$key = spl_object_id($object);
A substituição retorna um inteiro, não uma string. Se as chaves são serializadas, armazenadas em um banco de dados ou expostas por meio de uma API, revise os consumidores primeiro. Nenhuma função produz um identificador persistente entre solicitações, e os IDs podem ser reutilizados após a destruição de objetos. Para um mapa com chave pela identidade de objeto ativa, considere SplObjectStorage ou WeakMap, dependendo dos requisitos de ciclo de vida.
8. Um return em finally pode ocultar falhas
Antes — descontinuado e enganoso:
<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
return []; // Overrides the result and hides exceptions
}
}
Depois — preserve a limpeza sem substituir o resultado:

<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
releaseTemporaryResources();
}
}
Se o código original retornava intencionalmente um fallback, mova essa decisão para um bloco catch com tratamento explícito. Não engula silenciosamente uma exceção que deveria chegar ao chamador.
9. Ordenação sensível a locale e outras mudanças menos óbvias
strcoll() e a flag de ordenação SORT_LOCALE_STRING estão descontinuadas. A alternativa recomendada intl é Collator:
<?php
$collator = new Collator('fr_FR');
$names = ['Émile', 'Alice', 'Zoé'];
$collator->sort($names);
Verifique se o intl está instalado. A ordenação com base em locale é uma regra de negócio: teste sua ordem esperada em vez de assumir que o ICU e um locale global de processo sempre se comportarão de forma idêntica.
Outros itens de migração merecem atenção explícita:
ArrayIterator: ordenação, flags e métodos de serialização comoasort(),ksort(),setFlags()eserialize()estão descontinuados. Ordene o array subjacente ou use oArrayObjectquando sua API for apropriada; não assuma que um iterador e um contêiner são intercambiáveis.- Manipuladores de sessão personalizados: implemente ambos
create_sid()evalidateId()conforme exigidos pelas interfaces/comportamento atualizados. O PHP 8.6 habilita padrões de sessão mais estritos; teste login, rotação de sessão e persistência. __debugInfo(): use o tipo de retorno não anulávelarray; retornarnulljá estava descontinuado.define(): remova o terceiro argumento decase_insensitive, mesmo quando ele éfalse.http_build_query()earray_walk(): passar objetos onde arrays são esperados está descontinuado. Converta intencionalmente usandoget_object_vars()ou crie explicitamente o array desejado.metaphone(): não existe uma substituição pronta para uso no PHP. Escolha e teste um algoritmo fonético mantido e adequado à linguagem.- Identificadores reservados: nomes como
let,is,readonly(função) enamespace(constante de classe) têm novas restrições de depreciação. Renomeie as declarações afetadas com cuidado. - Reflection: revise objetos inválidos passados para
ReflectionProperty::setValue()e argumentos de objeto fornecidos ao invocar métodos estáticos.
Consulte o guia completo de migração para casos limite não cobertos por esta seleção prática.
10. Encontre chamadas descontinuadas em um projeto existente
Comece com um inventário somente leitura. No Linux ou macOS:
grep -RnE --include='*.php' \
'is_integer\(|is_long\(|is_double\(|doubleval\(|spl_object_hash\(|mb_ereg\(|mb_ereg_replace\(|mysqli_stmt_init\(|mysqli_get_charset\(' \
./src
Substitua ./src pelo diretório real. Esta busca em texto pode corresponder a comentários ou strings e não encontrará chamadas dinâmicas, aliases namespaced e outras APIs descontinuadas. É um ponto de partida, não um analisador estático completo.
Para uma opção multiplataforma, a busca de arquivos do editor pode pesquisar os mesmos nomes. Não edite arquivos principais de vendor ou CMS diretamente: atualize o pacote upstream ou envie um patch ao seu mantenedor.
Uma sequência de migração reproduzível
- Registre a versão atual do PHP e as extensões habilitadas.
- Faça backup de arquivos e banco de dados; prepare uma cópia de staging.
- Execute o projeto com PHP 8.6 com logging de depreciação habilitado.
- Inventarie avisos por arquivo e linha, depois agrupe por API.
- Corrija o código próprio com mudanças direcionadas; atualize dependências de terceiros separadamente.
- Rode novamente testes unitários/integração e jornadas importantes do usuário.
- Verifique formulários, login, sessões, e-mail, pagamentos, jobs agendados, importação/exportação CSV e acesso ao banco de dados.
- Faça deploy com um plano de rollback; monitore os logs de erros após a release.
Joomla e WordPress: O lançamento do PHP 8.6 não significa que toda versão de CMS, extensão ou plugin seja suportado. Confirme a compatibilidade com as versões exatas em uso e teste primeiro um ambiente de staging. Não use a atualização como motivo para aplicar patches diretamente em código principal ou vendor.
11. O que realmente é novo no PHP 8.6?
Além das deprecações, o release adiciona vários recursos de linguagem e runtime:
| Recurso | Uso prático |
|---|---|
| Aplicação parcial de funções | Pré-preencher argumentos e obter um callable para os restantes |
clamp() |
Restringir um valor entre um mínimo e um máximo |
\Time\Duration |
Representar tempo decorrido em vez de data de calendário |
SortDirection |
Expressar direção ascendente/descendente por meio de um enum padrão |
Io\Poll |
Suportar polling de stream em bibliotecas de event loop e I/O |
| Padrões para propriedades readonly | Simplificar declarações de classes imutáveis selecionadas |
Um pequeno exemplo, imediatamente útil, é clamp():
<?php
// Before PHP 8.6
$percentage = min(100, max(0, $input));
// PHP 8.6
$percentage = clamp($input, 0, 100);
O código é mais fácil de ler, mas a prioridade de migração ainda deve ser o teste de compatibilidade. Os outros recursos não são necessários apenas para manter um aplicativo existente funcionando. Veja o anúncio oficial do release.
12. Antes de trocar a versão do PHP em produção
Trate o PHP 8.6 como um upgrade controlado, não como um botão a ser clicado em um servidor de produção ocupado. Uma lista de release sensata é: CMS e dependências suportados; extensões disponíveis; nenhum inesperado influxo de deprecações; testes passando; comportamento de banco de dados e sessão verificado; backups testados; e um procedimento de rollback.
Conclusão: O PHP 8.6 traz recursos úteis, mas suas deprecações são muitas vezes onde o trabalho de manutenção começa. Corrija primeiro os aliases diretos, depois teste migrações comportamentais—especially regex, CSV, sessões e operações sensíveis a locale—contra dados reais.