O Laravel 13 agora permite que você substitua as propriedades $table, $fillable e $casts que sobrecarregam a maioria dos modelos por atributos nativos do PHP. A mudança se aplica a mais de uma dúzia de recursos do framework, desde a configuração de modelos até ouvintes de eventos (event listeners) e mailables, e funciona sem quebrar o código existente.

Por que o Laravel adicionou atributos nativos

O Laravel há muito tempo depende de “strings mágicas” – arrays de nomes de colunas ou campos ocultos que ficam no topo de uma classe de modelo. Esses arrays não dão pistas à IDE sobre o esquema subjacente, então a refatoração de um nome de coluna pode passar despercebida. Ao mover a configuração para um código real e tipado, o Laravel oferece aos desenvolvedores uma maneira de manter o corpo da classe focado na lógica de negócio, enquanto permite que o editor exiba preenchimento automático (autocomplete), verificação de tipos e ferramentas de renomeação e refatoração.

O framework lê os atributos via API de reflexão do PHP e faz o cache do resultado, de modo que o overhead de tempo de execução é efetivamente zero. Os modelos existentes baseados em propriedades continuam a funcionar exatamente como funcionam hoje, o que significa que você pode adotar a nova sintaxe gradualmente.

O que você ganha

  • Configuração tipada – Atributos aceitam argumentos tipados, eliminando strings mágicas. Renomeie uma coluna e a IDE apontará todos os lugares que você precisa atualizar.
  • Corpos de classe mais limpos – Toda a configuração reside acima do nome da classe; o corpo contém apenas relacionamentos, escopos e métodos.
  • Melhor experiência de IDE – Autocomplete e análise estática funcionam nos argumentos dos atributos, algo que arrays de strings não podem fornecer.
  • Sem alterações que quebrem o código – O Laravel lê tanto as propriedades antigas quanto os novos atributos, portanto, uma base de código mista funciona sem problemas.

Guia de migração passo a passo

  1. Identifique o modelo para migrar
    Abra o arquivo do modelo. Se as primeiras doze linhas forem dominadas por $table, $fillable, $hidden ou um método casts(), ele é um candidato.

  2. Adicione as classes de atributo
    No topo do arquivo, importe as classes de atributo que correspondem às propriedades que você substituirá (ex: Table, Fillable, Casts). O Laravel já fornece esses atributos nativamente.

  3. Substitua as declarações de propriedade por atributos 

    // Before
protected $table = 'site_deployments';
protected $fillable = ['site_id', 'server_id', 'status'];
protected function casts(): array
{
    return ['is_rollback' => 'boolean'];
}

    // After
#[Table('site_deployments')]
#[Fillable(['site_id', 'server_id', 'status'])]
#[Casts(['is_rollback' => 'boolean'])]
class Deployment extends Model
{
    // business logic only
}

    A sintaxe de atributo fica diretamente acima da declaração da classe. Remova a propriedade ou método original após confirmar que o atributo funciona.

  4. Execute a suíte de testes
    Verifique se a atribuição em massa (mass-assignment), a serialização e qualquer casting personalizado ainda se comportam como antes. O tratamento de atributos do Laravel é em cache, então um teste que falha geralmente aponta para um erro de digitação nos argumentos do atributo.

  5. Faça o commit e o deploy em pequenos lotes
    Envie o modelo migrado para um branch de funcionalidade (feature branch), faça o merge após a passagem do pipeline de CI e implemente em um subconjunto de servidores. Como a sintaxe de propriedade antiga ainda é suportada, qualquer referência perdida não causará um erro de tempo de execução.

  6. Repita por namespace
    Em vez de reescrever toda a base de código de uma vez, mova um grupo lógico de modelos (ex: todas as entidades relacionadas ao faturamento) para atributos e, em seguida, repita para o próximo grupo. Isso limita o raio de impacto de qualquer regressão.

Ferramentas e redes de segurança

  • Rector – Uma ferramenta de refatoração automatizada que pode converter a sintaxe repetitiva de propriedades em atributos. Execute-a em uma cópia da base de código, revise o diff e aplique as alterações que parecerem corretas.
  • Testes automatizados – As utilidades de teste integradas do Laravel capturam discrepâncias na atribuição em massa e na saída JSON. Mantenha-os passando (green) após cada etapa de migração.
  • Feature flags – Se precisar reverter rapidamente, envolva o uso do novo atributo em uma flag que alterna entre a configuração antiga e a nova.

Quando você pode pular a migração

Se um projeto for pequeno, estável e raramente tocado, o benefício de modelos mais limpos pode não compensar o esforço de conversão. A sintaxe de atributo é opcional; você pode continuar usando a abordagem clássica de propriedades indefinidamente. Por outro lado, para aplicações em desenvolvimento ativo, especialmente aquelas com modelos grandes ou mudanças frequentes de esquema, adotar atributos precocemente reduz o atrito futuro.

O que observar a seguir

O suporte a atributos do Laravel 13 se expande para além dos modelos, abrangendo ouvintes de eventos, notificações, mailables e eventos de broadcast. À medida que a comunidade adota a sintaxe nessas áreas, padrões de refatoração semelhantes surgirão. Fique de olho no guia de atualização oficial para quaisquer novas classes de atributos que cheguem em futuras versões menores.

Resumo: O Laravel 13 oferece um caminho de custo zero para modelos mais enxutos e amigáveis ao IDE. Converta um namespace por vez, apoie-se no Rector e na sua suíte de testes, e você acabará com classes que se leem como especificações de negócio, em vez de arquivos de despejo de configuração.