Laravel with Eloquent has a lot of "magic" — dynamic solutions that don't require developer intervention, while providing access to various methods and properties. This allows for writing much less code. However, it also has drawbacks. The main drawback of this approach is that neither the developer nor any IDE knows exactly which methods and properties are in the code. This means that the developer needs to remember everything, and the IDE won't help; instead, it will underline everything and complain that the method doesn't exist.

The solution for Laravel is IDE helper.

In short, the IDE helper creates a PHP file that replicates your project's structure, but adds PHPDoc annotations for all the hidden dynamic properties and methods.

To get started, you need 3 helper files and commands:

• php artisan ide-helper:generate — generates the _ide_helper.php file with Laravel facade methods;
• php artisan ide-helper:meta -M — generates the .phpstorm.meta.php file, a helper class for PHPStorm;
• php artisan ide-helper:models — generates php artisan ide-helper:models with a full description of Eloquent models. This is a very useful feature. It literally scans the database schema, creating a model schema with all the properties and dynamic methods related to them.
• php artisan ide-helper:eloquent — adds the Eloquent, Database\Eloquent\Builder, and Database\Query\Builder mixins to the base model class. This is done directly in the vendor directory. This hints to the models that they have all the query builder methods. This is very convenient if you use scope functions.

A few setup tips:

• php artisan ide-helper:models -M — I recommend using it with the -M parameter. It adds a mixin to the model class, which fixes IDE warnings about duplicates. Never use it with the -W parameter, which instead of a file, inserts PHPDoc into each model — this is very inconvenient, it needs to be reviewed, sent to production, tracked for code style, etc. Although, in fact, it is an auto-generated piece of code that provides no benefit compared to the -M option.
• Generate the helper for models immediately after migrations. Just add it to the configuration file. This is convenient and helps you start working right away.

'post_migrate' => [
    'ide-helper:models -M',
]

• Generate all necessary helper files when installing and updating PHP dependencies. This allows developers to start working immediately and have up-to-date files (models will be updated after migrations if the database was empty before the install command).

{
  "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"
    ]
  }
}

• Generate models before each commit and code style check. This prevents the developer from committing a model without a mixin. The next developer won't see the mixin changes and won't waste time committing them.

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

• Always add helper files to .gitignore and .dockerignore. These files help developers and have no place in production. They also prevent the team from reviewing auto-generated files.

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

Personal advice:

If you are using Active Records (in this case, Eloquent), don't fight it! Small, thin models are one of the advantages of Active Records. Either use the IDE helper or find similar solutions. If you want to turn the model into a kilometer-long property description — use Doctrine or another "classic" ORM for that.

A small life hack for PHPStorm users — Laravel Query Plugin. Connect PHPStorm to the database and start getting suggestions in any query directly from the database.