В Laravel 13 вы можете заменить свойства $table, $fillable и $casts, которые перегружают большинство моделей, на нативные атрибуты PHP. Это изменение затрагивает более дюжины функций фреймворка — от конфигурации моделей до слушателей событий и mailables — и работает без нарушения существующего кода.

Почему Laravel добавил нативные атрибуты

Laravel долгое время полагался на «магические строки» — массивы имен столбцов или скрытых полей, расположенные в начале класса модели. Эти массивы не дают IDE никаких подсказок о базовой схеме, поэтому при переименовании столбца ошибка может остаться незамеченной. Перенося конфигурацию в реальный типизированный код, Laravel дает разработчикам возможность сосредоточить тело класса на бизнес-логике, позволяя при этом редактору использовать автодополнение, проверку типов и инструменты рефакторинга.

Фреймворк считывает атрибуты через PHP Reflection API и кэширует результат, поэтому накладные расходы во время выполнения (runtime overhead) фактически равны нулю. Существующие модели на основе свойств продолжают работать точно так же, как и сегодня, а это значит, что вы можете внедрять новый синтаксис постепенно.

Что вы получаете

  • Типизированная конфигурация — Атрибуты принимают типизированные аргументы, избавляя от «магических строк». Переименуйте столбец, и IDE укажет на все места, которые необходимо обновить.
  • Чистое тело класса — Вся конфигурация находится над именем класса; тело содержит только связи (relationships), scopes и методы.
  • Улучшенная работа в IDE — Автодополнение и статический анализ работают с аргументами атрибутов, чего невозможно добиться с помощью массивов строк.
  • Отсутствие ломающих изменений — Laravel считывает как старые свойства, так и новые атрибуты, поэтому смешанная кодовая база работает без проблем.

Пошаговое руководство по миграции

  1. Определите модель для миграции
    Откройте файл модели. Если первые двенадцать строк заняты $table, $fillable, $hidden или методом casts(), она является кандидатом на обновление.

  2. Добавьте классы атрибутов
    В начале файла импортируйте классы атрибутов, соответствующие заменяемым свойствам (например, Table, Fillable, Casts). Эти атрибуты поставляются вместе с Laravel.

  3. Замените объявления свойств атрибутами 

    // 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
}

    Синтаксис атрибутов располагается непосредственно над объявлением класса. Удалите исходное свойство или метод после того, как убедитесь, что атрибут работает.

  4. Запустите тестовый набор
    Убедитесь, что массовое заполнение (mass-assignment), сериализация и любые пользовательские приведения типов (casting) по-прежнему работают как прежде. Обработка атрибутов в Laravel кэшируется, поэтому упавший тест обычно указывает на опечатку в аргументах атрибута.

  5. Коммитьте и развертывайте небольшими партиями
    Отправьте мигрированную модель в feature-ветку, объедините её после прохождения CI-конвейера и разверните на подмножестве серверов. Поскольку старый синтаксис свойств все еще поддерживается, любая случайная ссылка не вызовет ошибку во время выполнения.

  6. Повторяйте для каждого пространства имен (namespace)
    Вместо того чтобы переписывать всю кодовую базу сразу, переведите одну логическую группу моделей (например, все сущности, связанные с биллингом) на атрибуты, а затем повторите это для следующей группы. Это ограничит радиус поражения (blast radius) в случае возникновения регрессии.

Инструменты и средства защиты

  • Rector — Инструмент для автоматического рефакторинга, который может преобразовать повторяющийся синтаксис свойств в атрибуты. Запустите его на копии кодовой базы, просмотрите различия (diff) и примените только те изменения, которые выглядят корректно.
  • Автоматизированные тесты — Встроенные утилиты тестирования Laravel отлавливают несоответствия в массовом заполнении и JSON-выводе. Следите за тем, чтобы они оставались «зелеными» после каждого шага миграции.
  • Feature flags — Если вам нужно быстро откатиться, оберните использование новых атрибутов в флаг, который переключает конфигурацию между старой и новой.

Когда можно пропустить миграцию

Если проект небольшой, стабильный и редко подвергается изменениям, выгода от более чистых моделей может не перевесить усилия по конвертации. Синтаксис атрибутов необязателен; вы можете продолжать использовать классический подход со свойствами неограниченное время. И наоборот, для активно разрабатываемых приложений, особенно с большими моделями или частыми изменениями схемы, раннее внедрение атрибутов снижает трение в будущем.

Что ждать дальше

Поддержка атрибутов в Laravel 13 выходит за рамки моделей и распространяется на слушателей событий, уведомления, mailables и события широковещания (broadcast events). По мере того как сообщество будет внедрять этот синтаксис в этих областях, появятся аналогичные паттерны рефакторинга. Следите за официальным руководством по обновлению (upgrade guide), чтобы не пропустить новые классы атрибутов, которые появятся в будущих минорных релизах.

Итог: Laravel 13 предлагает путь без лишних затрат к созданию более лаконичных и удобных для IDE моделей. Переводите по одному пространству имен за раз, полагайтесь на Rector и свои тесты, и в итоге вы получите классы, которые читаются как бизнес-спецификации, а не как дампы конфигурационных файлов.