O Atributo #[Override] no PHP 8.3

Antes do PHP 8.3, marcar a intenção de sobrescrever um método de uma classe pai era só uma convenção — um comentário, um nome parecido, talvez um bloco de documentação. Se alguém renomeasse o método na classe pai, ou se um erro de digitação fizesse a assinatura não bater mais, o PHP não avisava nada: o método "sobrescrito" simplesmente virava um método novo, solto, e o bug só aparecia em produção. O atributo #[Override] resolve isso tornando essa intenção explícita e verificada pelo motor do PHP em tempo de compilação.

Como funciona

Ao anotar um método com #[Override], o PHP exige que exista um método com o mesmo nome em uma classe pai, em uma interface implementada ou em um trait usado. Se não existir, o script falha imediatamente com um erro fatal, antes mesmo de qualquer código rodar:

class Repositorio
{
    public function buscarPorId(int $id): ?array
    {
        // implementação base
        return null;
    }
}

class RepositorioUsuarios extends Repositorio
{
    #[Override]
    public function buscarPorId(int $id): ?array
    {
        // sobrescreve de fato o método do pai
        return ['id' => $id, 'nome' => 'Exemplo'];
    }
}

Até aqui, nada quebra: buscarPorId existe em Repositorio, então a sobrescrita é válida. O ganho aparece quando essa relação para de existir.

Pegando o erro que passava em silêncio

Imagine que alguém renomeia o método na classe pai, mas esquece de atualizar a subclasse. Sem o atributo, isso compila sem avisos e cria um método novo que nunca é chamado via polimorfismo:

class Repositorio
{
    public function buscarPorIdentificador(int $id): ?array
    {
        return null;
    }
}

class RepositorioUsuarios extends Repositorio
{
    #[Override]
    public function buscarPorId(int $id): ?array // nome antigo, não existe mais no pai
    {
        return ['id' => $id, 'nome' => 'Exemplo'];
    }
}

PHP Fatal error:  RepositorioUsuarios::buscarPorId() has #[Override] attribute,
but no matching parent method exists

Sem o #[Override], esse mesmo código passaria silenciosamente, e qualquer chamada a buscarPorId() em uma instância de Repositorio continuaria rodando a implementação base — um bug difícil de rastrear.

Funciona com interfaces e traits também

A verificação não se limita a herança de classe: um método que implementa uma interface, ou que sobrescreve um método vindo de um trait, também conta como válido:

interface Notificavel
{
    public function notificar(string $mensagem): void;
}

class EmailService implements Notificavel
{
    #[Override]
    public function notificar(string $mensagem): void
    {
        echo "Enviando e-mail: {$mensagem}";
    }
}

Quando usar

• Em qualquer método que sobrescreve um método de pai, interface ou trait — principalmente em hierarquias profundas, onde fica difícil lembrar de cabeça o que vem de onde.
• Para detectar, no momento do deploy, uma mudança de assinatura em uma biblioteca de terceiros que quebrou a sobrescrita de um método em uma classe sua.
• Em refatorações: renomear ou remover um método de uma classe base revela imediatamente, com erro de compilação, todo lugar que dependia dele.
• Como documentação viva — quem lê o método já sabe que ele participa de polimorfismo, sem precisar ir checar a classe pai.

Cuidados

O #[Override] não obriga que você marque toda sobrescrita — ele é opcional, e o PHP não reclama se você sobrescrever um método sem o atributo. A verificação só acontece no sentido contrário: se o atributo está presente, o método pai (ou de interface/trait) precisa existir. Ferramentas de análise estática como o PHPStan e o Rector já têm regras para sugerir ou até adicionar automaticamente o #[Override] em métodos que já sobrescrevem algo, o que ajuda a adotar o atributo em bases de código existentes sem revisar tudo manualmente.

Compatibilidade

O atributo #[Override] foi introduzido no PHP 8.3 (lançado em novembro de 2023) para uso em métodos. A partir do PHP 8.5, ele também pode ser aplicado a propriedades, incluindo propriedades com property hooks. Em código que precisa rodar em versões anteriores ao 8.3, o atributo não pode ser usado — não há polyfill possível, já que a verificação acontece no motor da linguagem.

documentação oficial

Conclusão

O #[Override] é um atributo pequeno, mas que fecha uma lacuna real: a diferença entre "eu pretendia sobrescrever este método" e "eu criei um método novo por acidente" deixa de ser uma suposição e passa a ser verificada pelo PHP em tempo de compilação. Vale adotar como prática padrão em qualquer sobrescrita, especialmente em projetos com hierarquias de classes mais longas ou que dependem de bibliotecas externas.