Web e Desenvolvimento

PHP 8.6: Novos Recursos, Funções Depreciadas e um Guia Prático de Migração

PHP 8.6: New Features, Deprecated Functions, and a Practical Migration Guide

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.

PHP 8.6 migration path: inventory, staging, logs, fixes and regression tests

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);
Illustration of the article's main concept

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:

Technical workflow illustration
<?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 como asort(), ksort(), setFlags() e serialize() estão descontinuados. Ordene o array subjacente ou use o ArrayObject quando 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() e validateId() 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ável array; retornar null já estava descontinuado.
  • define(): remova o terceiro argumento de case_insensitive, mesmo quando ele é false.
  • http_build_query() e array_walk(): passar objetos onde arrays são esperados está descontinuado. Converta intencionalmente usando get_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) e namespace (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.

A safe PHP 8.6 migration workflow with staging, log review and regression testing

Uma sequência de migração reproduzível

  1. Registre a versão atual do PHP e as extensões habilitadas.
  2. Faça backup de arquivos e banco de dados; prepare uma cópia de staging.
  3. Execute o projeto com PHP 8.6 com logging de depreciação habilitado.
  4. Inventarie avisos por arquivo e linha, depois agrupe por API.
  5. Corrija o código próprio com mudanças direcionadas; atualize dependências de terceiros separadamente.
  6. Rode novamente testes unitários/integração e jornadas importantes do usuário.
  7. Verifique formulários, login, sessões, e-mail, pagamentos, jobs agendados, importação/exportação CSV e acesso ao banco de dados.
  8. 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.

Fontes oficiais