[12.x] Do not require returning a Builder instance from a local scope method

[cosmastech]

To resolve the issue that @JeffreyWay reported on Twitter. https://x.com/jeffrey_way/status/1907138791799709883

Related to: #54450

---

In the current state, a local scope method must return a builder instance when called in a static context. This is counter to how scopes traditionally work, where the return value is essentially ignored.

cc: @shaedrich

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[newtonjob]

Thanks for this @cosmastech! I believe it's not just about the return. We should ideally proxy the static call to the query builder to ensure consistent behavior. The builder adds a few more logic when invoking local scopes that won't be covered here if we call it on the model directly.

See my comment here: #54450 (review)

[cosmastech]

Thanks for this @cosmastech! I believe it's not just about the return. We should ideally proxy the static call to the query builder to ensure consistent behavior. The builder adds a few more logic when invoking local scopes that won't be covered here if we call it on the model directly.

See my comment here: #54450 (review)

Hey @newtonjob!

I am unable to reproduce the grouping issue you identified.

`User` model code

class User extends Authenticatable
{
    /** @use HasFactory<\Database\Factories\UserFactory> */
    use HasFactory, Notifiable, SoftDeletes;
    protected $fillable = [
        'name',
        'email',
        'password',
    ];
    
    #[\Override]
    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }

    public function scopeMyScope(Builder $builder)
    {
        $builder->where('email', '=', '[email protected]')->orWhere('id', 1);
    }

    #[Scope]
    protected function other(Builder $builder)
    {
        return $builder->where('email', '=', '[email protected]')->orWhere('id', 1);
    }
}

All of which seem to produce the same query

Is there something I'm missing with the setup?

[shaedrich]

@JeffreyWay Thanks for reporting that on Twitter/X! 👍🏻
@newtonjob Thanks for explaining the problem over in the original PR! 👍🏻
@cosmastech Thanks for opening a PR to solve this and cc-ing me! 👍🏻

[shaedrich]

Nice solution! 👍🏻 Is there a reason, you chose this over what @newtonjob suggested in #54450 (comment)?

[cosmastech]

I didn't actually see his suggestion until after the fact. I have changed it to @newtonjob's suggestion.

[newtonjob]

Hey @cosmastech! Apparently, the SoftDeletes trait is hiding the issue in your example, so keeping it aside for now.

Here's a better way to reproduce it.

class User extends Authenticatable
{
    protected function scopeOne(Builder $query): void
    {
        $query->where('foo', true)->orWhere('bar', false);
    }

    #[Scope]
    protected function two(Builder $query): Builder
    {
        return $query->where('foo', true)->orWhere('bar', false);
    }
}

The reason why the new scope syntax isn't grouping the OR condition is that when called statically, the scope is invoked directly and doesn't pass through Illuminate\Database\Eloquent\Builder::callNamedScope().

I believe the behavior should be the same whether or not the scope is invoked statically.

[newtonjob]

@cosmastech just saw you made the change already, thanks! 🙌

[taylorotwell]

@cosmastech sorry, how does this solve the issue of needing to return? Aren't you still just returning whatever the scope returns in your change?

[cosmastech]

@cosmastech sorry, how does this solve the issue of needing to return? Aren't you still just returning whatever the scope returns in your change?

@taylorotwell Through the chain of calls, Builder::callScope() is called. It either returns the Builder instance returned from the scope method (scope* or with the new #[Scope] attribute), or if null, returns the query that was passed as the first parameter.

This is illustrated by the test case which statically calls a local scope that does not return a Builder instance.