[5.x] Support scopes as query methods

src/Query/Builder.php

@@ -11,9 +11,12 @@
 use Statamic\Contracts\Query\Builder as Contract;
 use Statamic\Extensions\Pagination\LengthAwarePaginator;
 use Statamic\Facades\Pattern;
+use Statamic\Query\Scopes\AppliesScopes;
 
 abstract class Builder implements Contract
 {
+ use AppliesScopes;
+
  protected $columns;
  protected $limit;
  protected $offset = 0;
@@ -34,6 +37,13 @@ abstract class Builder implements Contract
  '<=' => 'LessThanOrEqualTo',
  ];
 
+ public function __call($method, $args)
+ {
+ $this->applyScope($method);
+
+ return $this;
+ }
+
  public function select($columns = ['*'])
  {
  $this->columns = $columns;

src/Query/EloquentQueryBuilder.php

@@ -10,10 +10,13 @@
 use Statamic\Contracts\Query\Builder;
 use Statamic\Extensions\Pagination\LengthAwarePaginator;
 use Statamic\Facades\Blink;
+use Statamic\Query\Scopes\AppliesScopes;
 use Statamic\Support\Arr;
 
 abstract class EloquentQueryBuilder implements Builder
 {
+ use AppliesScopes;
+
  protected $builder;
  protected $columns;
 
@@ -40,6 +43,10 @@ public function __call($method, $args)
  {
  $response = $this->builder->$method(...$args);
 
+ if ($this->canApplyScope($method)) {
+ $this->applyScope($method);
+ }
+
  return $response instanceof EloquentBuilder ? $this : $response;
  }
 

src/Query/Scopes/AppliesScopes.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Statamic\Query\Scopes;
+
+use Statamic\Facades\Scope;
+
+trait AppliesScopes
+{
+ public function applyScope($method, $context = [])
+ {
+ // Throw an exception if the scope doesn't exist.
+ if (! $scope = Scope::find(snake_case($method))) {
+ throw new \Exception("The [$method] scope does not exist.");
+ }
+
+ // Apply the scope to all builders if none were defined.
+ if ($scope->builders()->isEmpty()) {
+ return $scope->apply($this, $context);
+ }
+
+ // Only apply the scope to the defined builders.
+ if ($scope->builders()->contains(get_class($this))) {
+ return $scope->apply($this, $context);
+ }
+
+ // Throw an exception if a user is trying to access a scope that is not supported by this builder.
+ throw new \Exception('The ['.get_class($this)."] query builder does not support the [$method] scope.");
+ }
+
+ public function canApplyScope($method): bool
+ {
+ // If the scope doesn't exist, return false.
+ if (! $scope = Scope::find(snake_case($method))) {
+ return false;
+ }
+
+ // If no builders are defined, return true.
+ if ($scope->builders()->isEmpty()) {
+ return true;
+ }
+
+ // If builders are defined and this builder is one of them, return true.
+ if ($scope->builders()->contains(get_class($this))) {
+ return true;
+ }
+
+ return false;
+ }
+}

src/Query/Scopes/Scope.php

@@ -4,12 +4,14 @@
 
 use Statamic\Extend\HasHandle;
 use Statamic\Extend\RegistersItself;
+use Statamic\Statamic;
 
 abstract class Scope
 {
  use HasHandle, RegistersItself;
 
  protected static $binding = 'scopes';
+ protected static $builders;
 
  /**
  * Apply the scope to a given query builder.
@@ -19,4 +21,16 @@ abstract class Scope
  * @return void
  */
  abstract public function apply($query, $values);
+
+ /**
+ * Return the query builders that this scope supports.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ public static function builders()
+ {
+ return collect(static::$builders)->map(function ($builder) {
+ return get_class(Statamic::query($builder));
+ });
+ }
 }

src/Query/Scopes/ScopeRepository.php

@@ -14,8 +14,18 @@ public function all()
 
  public function find($key, $context = [])
  {
- if ($scope = app('statamic.scopes')->get($key)) {
- return app($scope)?->context($context);
+ if ($class = app('statamic.scopes')->get($key)) {
+ $scope = app($class);
+
+ if (! $scope) {
+ return null;
+ }
+
+ if ($scope instanceof Filter) {
+ $scope->context($context);
+ }
+
+ return $scope;
  }
  }
 

src/Tags/Concerns/QueriesScopes.php

@@ -8,21 +8,15 @@ trait QueriesScopes
 {
  public function queryScopes($query)
  {
- $this->parseQueryScopes()
- ->map(function ($handle) {
- return app('statamic.scopes')->get($handle);
- })
- ->filter()
- ->each(function ($class) use ($query) {
- $scope = app($class);
- $scope->apply($query, $this->params);
- });
+ $this->parseQueryScopes()->each(function ($handle) use ($query) {
+ $query->applyScope($handle, $this->params);
+ });
  }
 
  protected function parseQueryScopes()
  {
  $scopes = Arr::getFirst($this->params, ['query_scope', 'filter']);
 
- return collect(explode('|', $scopes ?? ''));
+ return collect(explode('|', $scopes))->filter();
  }
 }

tests/Data/Assets/AssetQueryBuilderTest.php

@@ -6,6 +6,7 @@
 use Statamic\Facades\Asset;
 use Statamic\Facades\AssetContainer;
 use Statamic\Facades\Blueprint;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -28,6 +29,8 @@ public function setUp(): void
  Storage::disk('test')->put('e.jpg', '');
  Storage::disk('test')->put('f.jpg', '');
  $this->container = tap(AssetContainer::make('test')->disk('test'))->save();
+
+ app('statamic.scopes')[CustomScope::handle()] = CustomScope::class;
  }
 
  /** @test */
@@ -524,6 +527,14 @@ public function it_can_get_assets_using_tap()
  $this->assertEquals(['a'], $assets->map->filename()->all());
  }
 
+ /** @test **/
+ public function assets_are_found_using_scopes()
+ {
+ $assets = $this->container->queryAssets()->customScope()->get();
+
+ $this->assertCount(1, $assets);
+ }
+
  /** @test */
  public function assets_are_found_using_offset()
  {
@@ -601,3 +612,11 @@ public function querying_a_data_field_will_generate_meta_files()
  ], collect(Storage::disk('test')->allFiles())->sort()->values()->all());
  }
 }
+
+class CustomScope extends Scope
+{
+ public function apply($query, $params)
+ {
+ $query->where('filename', 'a');
+ }
+}

tests/Data/Entries/EntryQueryBuilderTest.php

@@ -7,13 +7,21 @@
 use Statamic\Facades\Collection;
 use Statamic\Facades\Entry;
 use Statamic\Facades\Site;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
 class EntryQueryBuilderTest extends TestCase
 {
  use PreventSavingStacheItemsToDisk;
 
+ public function setUp(): void
+ {
+ parent::setUp();
+
+ app('statamic.scopes')[CustomScope::handle()] = CustomScope::class;
+ }
+
  private function createDummyCollectionAndEntries()
  {
  Collection::make('posts')->save();
@@ -655,6 +663,17 @@ public function it_substitutes_entries_by_uri_and_site()
  $this->assertSame($found, $substituteFr);
  }
 
+ /** @test **/
+ public function entries_are_found_using_scopes()
+ {
+ EntryFactory::id('1')->slug('post-1')->collection('posts')->data(['title' => 'Post 1'])->create();
+ EntryFactory::id('2')->slug('post-2')->collection('posts')->data(['title' => 'Post 2'])->create();
+
+ $entries = Entry::query()->customScope()->get();
+
+ $this->assertCount(1, $entries);
+ }
+
  /** @test */
  public function entries_are_found_using_offset()
  {
@@ -738,3 +757,11 @@ public function likeProvider()
  });
  }
 }
+
+class CustomScope extends Scope
+{
+ public function apply($query, $params)
+ {
+ $query->where('title', 'Post 1');
+ }
+}

tests/Data/Taxonomies/TermQueryBuilderTest.php

@@ -8,6 +8,7 @@
 use Statamic\Facades\Site;
 use Statamic\Facades\Taxonomy;
 use Statamic\Facades\Term;
+use Statamic\Query\Scopes\Scope;
 use Statamic\Taxonomies\LocalizedTerm;
 use Statamic\Taxonomies\TermCollection;
 use Tests\PreventSavingStacheItemsToDisk;
@@ -17,6 +18,13 @@ class TermQueryBuilderTest extends TestCase
 {
  use PreventSavingStacheItemsToDisk;
 
+ public function setUp(): void
+ {
+ parent::setUp();
+
+ app('statamic.scopes')[CustomScope::handle()] = CustomScope::class;
+ }
+
  /** @test */
  public function it_gets_terms()
  {
@@ -253,39 +261,45 @@ public function it_filters_usage_in_collections()
  Term::make('g')->taxonomy('cats')->data([])->save();
  Term::make('h')->taxonomy('cats')->data([])->save();
 
- $this->assertEquals(['cats::f', 'cats::g', 'tags::a', 'tags::c'],
+ $this->assertEquals(
+ ['cats::f', 'cats::g', 'tags::a', 'tags::c'],
  Term::query()
  ->where('collection', 'blog')
  ->get()->map->id()->sort()->values()->all()
  );
 
- $this->assertEquals(['tags::a', 'tags::c'],
+ $this->assertEquals(
+ ['tags::a', 'tags::c'],
  Term::query()
  ->where('collection', 'blog')
  ->where('taxonomy', 'tags')
  ->get()->map->id()->sort()->values()->all()
  );
 
- $this->assertEquals(['cats::f', 'cats::h', 'tags::a', 'tags::b'],
+ $this->assertEquals(
+ ['cats::f', 'cats::h', 'tags::a', 'tags::b'],
  Term::query()
  ->where('collection', 'news')
  ->get()->map->id()->sort()->values()->all()
  );
 
- $this->assertEquals(['tags::a', 'tags::b'],
+ $this->assertEquals(
+ ['tags::a', 'tags::b'],
  Term::query()
  ->where('collection', 'news')
  ->where('taxonomy', 'tags')
  ->get()->map->id()->sort()->values()->all()
  );
 
- $this->assertEquals(['cats::f', 'cats::g', 'cats::h', 'tags::a', 'tags::b', 'tags::c'],
+ $this->assertEquals(
+ ['cats::f', 'cats::g', 'cats::h', 'tags::a', 'tags::b', 'tags::c'],
  Term::query()
  ->whereIn('collection', ['blog', 'news'])
  ->get()->map->id()->sort()->values()->all()
  );
 
- $this->assertEquals(['tags::a', 'tags::b', 'tags::c'],
+ $this->assertEquals(
+ ['tags::a', 'tags::b', 'tags::c'],
  Term::query()
  ->whereIn('collection', ['blog', 'news'])
  ->where('taxonomy', 'tags')
@@ -587,6 +601,18 @@ public function terms_are_found_using_where_json_length()
  $this->assertEquals(['2', '5', '4'], $entries->map->slug()->all());
  }
 
+ /** @test **/
+ public function terms_are_found_using_scopes()
+ {
+ Taxonomy::make('tags')->save();
+ Term::make('a')->taxonomy('tags')->data(['title' => 'Post 1'])->save();
+ Term::make('b')->taxonomy('tags')->data(['title' => 'Post 2'])->save();
+
+ $entries = Term::query()->customScope()->get();
+
+ $this->assertCount(1, $entries);
+ }
+
  /** @test */
  public function terms_are_found_using_offset()
  {
@@ -602,3 +628,11 @@ public function terms_are_found_using_offset()
  $this->assertEquals(['b', 'c'], $terms->map->slug()->all());
  }
 }
+
+class CustomScope extends Scope
+{
+ public function apply($query, $params)
+ {
+ $query->where('title', 'Post 1');
+ }
+}