Laravel з Eloquent мають багато "магії" — динамічних рішень, які не потребують втручання розробника, при цьому надають доступ до тих чи інших методів та властивостей. Це дозволяє писати набагато менше коду. Але є і мінуси. Головним мінусом такого підходу є те, що розробник та жодна IDE не знають кінцево, які методи та властивості є у коді. Це означає, що розробнику потрібно це все пам'ятати, а IDE не допоможе, навпаки, буде все підкреслювати і кричати, що методу не існує.

Рішення для Laravel — IDE helper.

Дуже коротко: IDE helper створює PHP файл, який повторює обрану структуру вашого проєкту, але доповнює її PHPDoc з описами всіх захованих динамічних властивостей та методів.

Для старту цікавлять 3 таких helper файли та команди:

• php artisan ide-helper:generate — генерує help файл _ide_helper.php з методами фасадів Laravel;
• php artisan ide-helper:meta -M — генерує файл .phpstorm.meta.php, допоміжний клас для PHPStorm;
• php artisan ide-helper:models — генерує php artisan ide-helper:models з повним описом Eloquent моделей. Дуже корисна функція. Вона буквально сканує схему бази даних, створюючи схему моделі з усіма властивостями та динамічними методами щодо них.
• php artisan ide-helper:eloquent — додає до базового класу моделей домішки Eloquent, Database\Eloquent\Builder та Database\Query\Builder. Це робиться прямо у директорії vendor. Це дає підказку моделям, що в них є всі методи query builder. Дуже зручно, якщо користуєтесь scope функціями.

Декілька порад щодо налаштування:

• php artisan ide-helper:models -M — раджу використовувати з параметром -M. Він додасть mixin до класу моделі, що виправить IDE попередження про дублікати. Ніколи не використовуйте з параметром -W, який замість файлу впише PHPDoc до кожної моделі — це дуже незручно, його треба рев'ювати, відправляти на продакшн, слідкувати за кодстайлом і т.д. Хоча по факту це автосгенерований шматок коду, який не дає ніякої користі в порівнянні з варіантом -M.
• Генеруйте helper для моделей одразу після міграцій. Просто дописавши файл конфігурації. Це зручно і допомагає працювати одразу.

[config/ide-helper.php]
'post_migrate' => [
    'ide-helper:models -M',
]

• Генеруйте всі необхідні helper файли при інсталяції та оновленні PHP залежностей. Це дасть змогу розробникам одразу працювати та мати актуальні файли (моделі оновляться після міграцій, якщо БД була пуста до install команди).

{
  "scripts": {
    "ide-helper": [
      "@php artisan ide-helper:generate",
      "@php artisan ide-helper:meta",
      "@php artisan ide-helper:models -M",
      "@php artisan ide-helper:eloquent"
    ],
    "post-install-cmd": [
      "@ide-helper"
    ],
    "post-update-cmd": [
      "@ide-helper"
    ]
  }
}

• Генеруйте моделі перед кожним комітом та перевіркою кодстайлу. Це не дасть розробнику закомітити модель без міксину. І наступному розробнику міксин не вилізе у зміни та не змусить витрачати час на його коміт.

docker exec -t bh-app php artisan ide-helper:models -M
...
docker exec -t bh-app php artisan insights --fix --no-interaction

• Обов'язково додавайте helper файли до .gitignore та .dockerignore. Ці файли допомагають розробникам, їм не місце на продакшні, і не треба навантажувати команду рев'ю автоматично згенерованих файлів.

.phpstorm.meta.php
_ide_helper.php
_ide_helper_models.php

Особиста порада:

Якщо використовуєте Active Records (в цьому випадку Eloquent), не боріться з ним! Маленькі тоненькі моделі — це одна з переваг Active Records. Або використовуйте IDE helper, або шукайте схожі рішення. Якщо є бажання перетворити модель у кілометровий опис властивостей — то для цього використовуйте Doctrine або іншу "класичну" ORM.

Маленький лайфхак для користувачів PHPStorm — Laravel Query Plugin. Підключіть базу даних до шторму і почніть отримувати підказки в будь-яких query запитах прямо з бази даних.