PHPStan complains about @var Builder<ProductTemplate> in Laravel Eloquent scope

Question

I'm trying to define a Laravel Eloquent model with a custom scope that filters categories by a related product's vendor_id. Here's my setup:

class Category extends Model
{
    public function productTemplates(): HasMany
    {
        return $this->hasMany(ProductTemplate::class, 'category_id');
    }

    #[Scope]
    protected function byVendor(Builder $query, ?int $vendorId = null): void
    {
        $query->whereHas('productTemplates', function (Builder $productQuery): void {
            /** @var Builder<ProductTemplate> $productQuery */
            $productQuery->byVendor($vendorId);
        });
    }
}

class ProductTemplate extends Model
{
    #[Scope]
    protected function byVendor(Builder $query, ?int $vendorId = null): void
    {
        if ($vendorId) {
            $query->where('vendor_id', $vendorId);
        }
    }
}

When I run PHPStan, I get this error:

PHPDoc tag @var with type Illuminate\Database\Eloquent\Builder<App\Models\ProductTemplate> 
is not subtype of native type Illuminate\Database\Eloquent\Builder<Illuminate\Database\Eloquent\Model>.

How can I fix the PHPDoc or type hinting so PHPStan recognizes the $productQuery type correctly in the scope?

Baris Taskiran · Accepted Answer · 2025-11-29 01:04:37Z

1

PHPStan complains because the closure gets a generic Builder<Model> and your docblock says Builder<ProductTemplate>, so it thinks the types don’t match. Laravel knows the relation returns ProductTemplate, but PHPStan doesn’t infer that on its own inside whereHas().

You can just hint it directly in the closure:

$query->whereHas('productTemplates', function (Builder $productQuery) use ($vendorId) {
    /** @var Builder<ProductTemplate> $productQuery */
    $productQuery->byVendor($vendorId);
});

This basically tells PHPStan “yes, this builder is for ProductTemplate” and it stops complaining. Nothing else in your scope has to change.

answered 2 days ago

Baris Taskiran

3142 silver badges11 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

PHPStan complains about @var Builder<ProductTemplate> in Laravel Eloquent scope

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related