Soft delete search #minor (asseco-voice#28)

* Implemented searching by soft deleted models

* Readme update

* Apply fixes from StyleCI

Co-authored-by: jmilotic <josip.milotic@asseco-see.hr>
Co-authored-by: Marko Dupor <Norgul@users.noreply.github.com>

Author: 3 people

README.md

@@ -57,6 +57,7 @@ JSON parameters (keys):
 - `offset` - will return a subset of results starting from a point given. This parameter **MUST**
 be used together with ``limit`` parameter. 
 - `count` - will return record count.
+- `soft_deleted` - will include soft deleted models in search results
 
 ### Search
 
@@ -329,6 +330,17 @@ You can fetch count of records instead of concrete records by adding the count k
 
 This will do a ``SELECT count(*) FROM table``.
 
+### Soft deleted
+
+By default, soft deleted records are excluded from the search. This can be overridden
+with ``soft_deleted``:
+
+```
+{
+    "soft_deleted": true
+}
+```
+
 ## Top level logical operators
 
 Additionally, it is possible to group search clauses by top-level logical operator.

config/asseco-json-query-builder.php

@@ -8,6 +8,7 @@
 use Asseco\JsonQueryBuilder\RequestParameters\RelationsParameter;
 use Asseco\JsonQueryBuilder\RequestParameters\ReturnsParameter;
 use Asseco\JsonQueryBuilder\RequestParameters\SearchParameter;
+use Asseco\JsonQueryBuilder\RequestParameters\SoftDeletedParameter;
 use Asseco\JsonQueryBuilder\SearchCallbacks\Between;
 use Asseco\JsonQueryBuilder\SearchCallbacks\Equals;
 use Asseco\JsonQueryBuilder\SearchCallbacks\GreaterThan;
@@ -32,6 +33,7 @@
         OffsetParameter::class,
         CountParameter::class,
         GroupByParameter::class,
+        SoftDeletedParameter::class,
     ],
 
     /**

src/RequestParameters/SoftDeletedParameter.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Asseco\JsonQueryBuilder\RequestParameters;
+
+use Asseco\JsonQueryBuilder\Exceptions\JsonQueryBuilderException;
+use Illuminate\Database\Eloquent\SoftDeletingScope;
+
+class SoftDeletedParameter extends AbstractParameter
+{
+    public static function getParameterName(): string
+    {
+        return 'soft_deleted';
+    }
+
+    protected function areArgumentsValid(): void
+    {
+        if (count($this->arguments) != 1) {
+            throw new JsonQueryBuilderException("Parameter '{$this->getParameterName()}' expects only one argument.");
+        }
+
+        if (!in_array($this->arguments[0], [1, '1', true, 'true'], true)) {
+            throw new JsonQueryBuilderException("Parameter '{$this->getParameterName()}' expects to be 'true' if it is to be used.");
+        }
+    }
+
+    protected function appendQuery(): void
+    {
+        $this->builder->withoutGlobalScope(SoftDeletingScope::class);
+    }
+}

tests/Unit/RequestParameters/SoftDeletedParameterTest.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Asseco\JsonQueryBuilder\Tests\Unit\RequestParameters;
+
+use Asseco\JsonQueryBuilder\Config\ModelConfig;
+use Asseco\JsonQueryBuilder\RequestParameters\SoftDeletedParameter;
+use Asseco\JsonQueryBuilder\Tests\TestCase;
+use Exception;
+use Illuminate\Database\Eloquent\Builder;
+use Mockery;
+
+class SoftDeletedParameterTest extends TestCase
+{
+    protected Builder $builder;
+    protected ModelConfig $modelConfig;
+
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->builder = app(Builder::class);
+
+        $this->modelConfig = Mockery::mock(ModelConfig::class);
+    }
+
+    /** @test */
+    public function has_a_name()
+    {
+        $countParameter = new SoftDeletedParameter([], $this->builder, $this->modelConfig);
+
+        $this->assertEquals('soft_deleted', $countParameter::getParameterName());
+    }
+
+    /** @test */
+    public function accepts_valid_arguments()
+    {
+        foreach ([1, '1', true, 'true'] as $validArgument) {
+            $countParameter = new SoftDeletedParameter([$validArgument], $this->builder, $this->modelConfig);
+            $countParameter->run();
+        }
+
+        $this->assertTrue(true);
+    }
+
+    /** @test */
+    public function rejects_non_bool_argument()
+    {
+        $this->expectException(Exception::class);
+
+        $countParameter = new SoftDeletedParameter(['invalid'], $this->builder, $this->modelConfig);
+        $countParameter->run();
+    }
+
+    /** @test */
+    public function rejects_multiple_arguments()
+    {
+        $this->expectException(Exception::class);
+
+        $countParameter = new SoftDeletedParameter([1, 1], $this->builder, $this->modelConfig);
+        $countParameter->run();
+    }
+}