[5.x] Support scopes as query methods

[aerni]

This PR implements the new query scopes approach as discussed in PR #5869.

Each scope in the App\Scopes namespace is now also available to the query builders.

Example

Let's assume we've got a App\Scopes\PaymentSuccessful scope class. This scope can now be used in Antlers and in PHP.

// Antlers
{{ collection:blog filter="payment_successful" }}

// PHP
Entry::query()->paymentSuccessful()

The query method corresponds to the scope's handle in camel case.

// The handle in App\Scopes\PaymentSuccessful
protected static $handle = 'where_something';

Entry::query()->whereSomething()

By default, each scope is available to all query builders. You may want to restrict the scope to be available on certain query builders only. You can do that by adding the alias of the query builder to the $builders property.

// The scope is only available to the EntryQueryBuilder
protected static $builders = ['entries'];

I also added some nice exceptions. But you might decide to remove them for a more graceful handling if the scope doesn't exist.

[aerni]

I added a bunch of tests. The only thing I wasn't sure about was how to test the eloquent builder for entries and users?

[duncanmcclean]

Thanks for this - it looks good! I've noticed one small thing though... 🤔

[jasonvarga]

Ahem, sorry for the delay. 🫠

We talked through how we thought this should work and have made some changes.

Scopes aren't automatically applied to all builders. You have to opt into them. You can do that in a provider:

Entry::allowQueryScope(MichaelsScope::class); // handle of michaels_scope
// Allows $query->michaelsScope()

You can set the method in the second argument:

Entry::allowQueryScope(MyScope::class, 'whereMichael');
// Allows $query->whereMichael()

This made it feel more close to how it works in Laravel. In Laravel you would allow these "local scopes" by adding methods to the Model. Since you aren't touching the models in Statamic, opting in like this was an alternative.

[aerni]

I like it. Would it make sense to also scope the scope (no pun intended) to a collection? A PaymentSuccessful scope probably doesn't make sense for all collections.

[jasonvarga]

I get the request, but not really. The entry query builder can query across collections.
In your case your PaymentSuccessful scope could add $query->where('collection', 'orders').

Also, I've adjusted the PR so that context needs to be passed into the method as an array. This is different to Laravel, but Statamic scopes are different. We may be able to change it for v6.

i.e. Instead of ->myScope($arg) you'd need to do ->myScope(['foo' => $foo]) since our scopes' apply method expects an array.

function apply($query, $values) {
  $foo = $values['foo'];
  // ...
}

[ryanmitchell]

I have been waiting so long for this. Thank you!!

[jasonvarga]

Pfft relax it was only opened in April 2022.