is it normal to add @static annotations on Model files?

So, I was generating some Seeders. I tried using some AI help, which worked great. However, PHPStorm didn't like the static methods being called... I actually didn't try it as-is, but followed PHPStorm's recommendation, which was to annotate my model classes such as the example below. Maybe it would have worked without - the annotations are just to help PHPStorm know that these methods are available from the base Model class, right? Is this the normal way? I don't seem to see this being done, have searched a few times over an hour. Just making sure I'm not doing something completely wrong. (I am guessing this only happens for Seeders.)

/**
 * @method static firstOrCreate(array $array, array $array1)
 * @method static whereNull(string $string)
 * @method static whereNotNull(string $string)
 * @method static whereNotIn(string $string, $filter)
 * @method static whereIn(string $string, $filter)
 */

LaryAI

1 year ago

Level 58

In Laravel, it's common to use Eloquent models with static methods like firstOrCreate, whereNull, whereNotNull, etc. These methods are part of the Eloquent query builder and are available through the __callStatic magic method, which allows you to call them statically on your model classes.

However, PHPStorm and other IDEs might not recognize these methods as they are not explicitly defined in your model classes. To help the IDE understand and provide autocompletion for these methods, you can use PHPDoc annotations. This is a common practice to improve the development experience by providing better code insights and autocompletion.

Here's how you can annotate your model classes:

/**
 * @method static \Illuminate\Database\Eloquent\Builder|static firstOrCreate(array $attributes, array $values = [])
 * @method static \Illuminate\Database\Eloquent\Builder|static whereNull(string $column)
 * @method static \Illuminate\Database\Eloquent\Builder|static whereNotNull(string $column)
 * @method static \Illuminate\Database\Eloquent\Builder|static whereNotIn(string $column, $values)
 * @method static \Illuminate\Database\Eloquent\Builder|static whereIn(string $column, $values)
 */
class YourModel extends \Illuminate\Database\Eloquent\Model
{
    // Your model code here
}

These annotations are not required for your code to function correctly, but they are helpful for IDEs to provide better support. It's not unusual to see these annotations in projects where developers want to leverage the full power of their IDE's features. If you find it beneficial, feel free to use them. Otherwise, your code should work without them, as these methods are inherently available through Laravel's Eloquent ORM.

martinbean

1 year ago

Best Answer

Level 80

@rockafella I hate annotations like this. They make diffs awful, and can quickly get out of date if you’re adding annotations for things like attributes and relations.

The example annotations you’ve added (firstOrCreate et al) are redundant if you add query after the model class name. For example:

$article = Article::query()->whereNull('column_name')->first();

This will return a query builder instance and you’ll get type-hinting for all of the query builder’s methods, like firstOrCreate, whereNull, etc.

2 likes

rockafella

1 year ago

Level 2

@martinbean ah, I knew I was missing something simple! Yeah that explains it, I didn't recognize that the code wasn't using query()-> to start it off. Thanks a lot!

Please or to participate in this conversation.