Laravel 13 замінює $fillable, $table та $casts нативними атрибутами PHP

Laravel 13 тепер дозволяє замінити властивості $table, $fillable та $casts, які переповнюють більшість моделей, на нативні атрибути PHP. Зміна стосується понад десятка функцій фреймворку — від конфігурації моделей до слухачів подій (event listeners) та mailables — і вона працює без порушення існуючого коду.

Чому Laravel додав нативні атрибути

Laravel тривалий час покладався на «магічні рядки» — масиви імен колонок або прихованих полів, що розміщуються на початку класу моделі. Ці масиви не дають IDE жодної підказки щодо структури схеми, тому перейменування колонки може залишитися непоміченим. Переносячи конфігурацію в реальний типізований код, Laravel дає розробникам можливість зосередити тіло класу на бізнес-логіці, дозволяючи при цьому редактору пропонувати автодоповнення, перевірку типів та інструменти рефакторингу (rename-refactor).

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

Що ви отримуєте

• Типізована конфігурація — Атрибути приймають типізовані аргументи, усуваючи «магічні рядки». Перейменуйте колонку, і IDE вкаже на кожне місце, яке потрібно оновити.
• Чистіші тіла класів — Уся конфігурація розміщується над назвою класу; тіло містить лише зв'язки (relationships), scope-методи та звичайні методи.
• Кращий досвід роботи з IDE — Автодоповнення та статичний аналіз працюють з аргументами атрибутів, чого не можуть забезпечити масиви рядків.
• Відсутність критичних змін (breaking changes) — 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), серіалізація та будь-яке кастомне приведення типів (custom casting) працюють так само, як і раніше. Обробка атрибутів у Laravel кешується, тому невдалий тест зазвичай вказує на друкарську помилку в аргументах атрибута.

5. Фіксуйте (commit) та розгортайте невеликими партіями
   Відправте мігровану модель у feature-гілку, злийте її після проходження CI pipeline та розгорніть на частині серверів. Оскільки старий синтаксис властивостей усе ще підтримується, будь-яке випадкове посилання не спричинить помилку під час виконання.

6. Повторюйте для кожного простору імен (namespace)
   Замість того, щоб переписувати всю кодову базу одразу, переведіть одну логічну групу моделей (наприклад, усі сутності, пов'язані з білінгом) на атрибути, а потім повторіть це для наступної групи. Це обмежить радіус ураження у разі виникнення регресії.

Інструменти та засоби безпеки

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

Коли можна пропустити міграцію

Якщо проєкт невеликий, стабільний і рідко змінюється, перевага чистіших моделей може не вартувати зусиль на конвертацію. Синтаксис атрибутів є необов'язковим; ви можете нескінченно використовувати класичний підхід із властивостями. І навпаки, для застосунків, що активно розробляються, особливо з великими моделями або частими змінами схеми, раннє впровадження атрибутів зменшить труднощі в майбутньому.

На що звернути увагу далі

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

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