Eloquent provides the ability to define local scopes like so:

class User extends Model
{
    /**
     * Scope a query to only include popular users.
     */
    public function scopePopular(Builder $query): void // May also return the Builder
    {
        $query->where('votes', '>', 100);
    }

This creates a User::popular() scope. Because there's some "magic" here, turning scopePopular into popular, it would be handy to add PHPDocs for these methods.

I'm not a Laravel superuser at this point so I admit there's some fuzziness here – I have noticed that I can make this function static or not and it will work the same. And of course AFAIK adding the PHPDoc here won't alter the Builder class so if you do, e.g., User::query()->where('foo', 'bar')->popular(), that is valid code but can't get typehinted/code-completed (at least in VSCode). But having them documented on the model seems reasonable.

What do you think?