Fix #382: add FilterTrashed (#383)

* #382: add `FilterTrashed`

* #382: fix code style

* #382: fix naming

Co-authored-by: Alex Vanderbist <alex.vanderbist@gmail.com>

src/AllowedFilter.php

@@ -6,6 +6,7 @@
 use Spatie\QueryBuilder\Filters\Filter;
 use Spatie\QueryBuilder\Filters\FiltersExact;
 use Spatie\QueryBuilder\Filters\FiltersPartial;
+use Spatie\QueryBuilder\Filters\FiltersTrashed;
 use Spatie\QueryBuilder\Filters\FiltersScope;
 
 class AllowedFilter
@@ -68,6 +69,11 @@ public static function scope(string $name, $internalName = null): self
         return new static($name, new FiltersScope(), $internalName);
     }
 
+    public static function trashed(string $name = 'trashed', $internalName = null): self
+    {
+        return new static($name, new FiltersTrashed(), $internalName);
+    }
+
     public static function custom(string $name, Filter $filterClass, $internalName = null): self
     {
         return new static($name, $filterClass, $internalName);

src/Filters/FiltersTrashed.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Spatie\QueryBuilder\Filters;
+
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * FiltersTrashed provides filter for soft deleted (trashed) records.
+ *
+ * This filter responds to particular values:
+ *
+ * - 'with' - include 'trashed' records to the result set.
+ * - 'only' - return only 'trashed' records at the result set.
+ * - any other - return only records without 'trashed' at the result set.
+ *
+ * Usage example:
+ *
+ * ```php
+ * QueryBuilder::for(Item::class)
+ *     ->allowedFilters([
+ *         AllowedFilter::trashed(),
+ *         // ...
+ *     ]);
+ * ```
+ *
+ * @see \Illuminate\Database\Eloquent\SoftDeletes
+ * @see \Spatie\QueryBuilder\AllowedFilter::trashed()
+ */
+class FiltersTrashed implements Filter
+{
+    /** {@inheritdoc} */
+    public function __invoke(Builder $query, $value, string $property)
+    {
+        if ($value === 'with') {
+            $query->withTrashed();
+
+            return;
+        }
+
+        if ($value === 'only') {
+            $query->onlyTrashed();
+
+            return;
+        }
+
+        $query->withoutTrashed();
+    }
+}

tests/FiltersTrashedTest.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Spatie\QueryBuilder\Tests;
+
+use Illuminate\Http\Request;
+use Spatie\QueryBuilder\QueryBuilder;
+use Spatie\QueryBuilder\AllowedFilter;
+use Spatie\QueryBuilder\Tests\TestClasses\Models\SoftDeleteModel;
+
+class FiltersTrashedTest extends TestCase
+{
+    /** @var \Illuminate\Support\Collection */
+    protected $models;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->models = factory(SoftDeleteModel::class, 2)->create()
+            ->merge(factory(SoftDeleteModel::class, 1)->create(['deleted_at' => now()]));
+    }
+
+    /** @test */
+    public function it_should_filter_not_trashed_by_default()
+    {
+        $models = $this
+            ->createQueryFromFilterRequest([
+                'trashed' => '',
+            ])
+            ->allowedFilters(AllowedFilter::trashed())
+            ->get();
+
+        $this->assertCount(2, $models);
+    }
+
+    /** @test */
+    public function it_can_filter_only_trashed()
+    {
+        $models = $this
+            ->createQueryFromFilterRequest([
+                'trashed' => 'only',
+            ])
+            ->allowedFilters(AllowedFilter::trashed())
+            ->get();
+
+        $this->assertCount(1, $models);
+    }
+
+    /** @test */
+    public function it_can_filter_with_trashed()
+    {
+        $models = $this
+            ->createQueryFromFilterRequest([
+                'trashed' => 'with',
+            ])
+            ->allowedFilters(AllowedFilter::trashed())
+            ->get();
+
+        $this->assertCount(3, $models);
+    }
+
+    protected function createQueryFromFilterRequest(array $filters): QueryBuilder
+    {
+        $request = new Request([
+            'filter' => $filters,
+        ]);
+
+        return QueryBuilder::for(SoftDeleteModel::class, $request);
+    }
+}