Merge pull request #37 from tattersoftware/soft-deletes

Author: MGatner

README.md

@@ -1,8 +1,9 @@
 # Tatter\Relations
 Entity relationships for CodeIgniter 4
 
-[![](https://github.com/tattersoftware/codeigniter4-relations/workflows/PHPUnit/badge.svg)](https://github.com/tattersoftware/codeigniter4-relations/actions?query=workflow%3A%22PHPUnit)
-[![](https://github.com/tattersoftware/codeigniter4-relations/workflows/PHPStan/badge.svg)](https://github.com/tattersoftware/codeigniter4-relations/actions?query=workflow%3A%22PHPStan)
+[![](https://github.com/tattersoftware/codeigniter4-relations/workflows/PHPUnit/badge.svg)](https://github.com/tattersoftware/codeigniter4-relations/actions/workflows/phpunit.yml)
+[![](https://github.com/tattersoftware/codeigniter4-relations/workflows/PHPStan/badge.svg)](https://github.com/tattersoftware/codeigniter4-relations/actions/workflows/phpstan.yml)
+[![](https://github.com/tattersoftware/codeigniter4-relations/workflows/Deptrac/badge.svg)](https://github.com/tattersoftware/codeigniter4-relations/actions/workflows/deptrac.yml)
 [![Coverage Status](https://coveralls.io/repos/github/tattersoftware/codeigniter4-relations/badge.svg?branch=develop)](https://coveralls.io/github/tattersoftware/codeigniter4-relations?branch=develop)
 
 ## Quick Start
@@ -19,10 +20,12 @@ Entity relationships for CodeIgniter 4
 
 Install easily via Composer to take advantage of CodeIgniter 4's autoloading capabilities
 and always be up-to-date:
-* `> composer require tatter/relations`
+```shell
+    > composer require tatter/relations
+```
 
 Or, install manually by downloading the source files and adding the directory to
-`app/Config/Autoload.php`.
+**app/Config/Autoload.php***.
 
 ## Configuration (optional)
 
@@ -50,21 +53,20 @@ methods and injecting relations into the returned results. Because this happens
 level, related items can be loaded ahead of time in batches ("eager loading").
 
 Add the trait to your models:
-
+```php
 	use \Tatter\Relations\Traits\ModelTrait
+```
 
 Related items can be requested by adding a `$with` property to your model:
-
-```
+```php
 	protected $with = 'groups';
 	// or
 	protected $with = ['groups', 'permissions'];
 ```
 
 ... or by requesting it on-the-fly using the model `with()` method:
 
-
-```
+```php
 $users = $userModel->with('groups')->findAll();
 foreach ($users as $userEntity)
 {
@@ -82,17 +84,15 @@ and `__call()` methods to check for matching database tables. Because this happe
 item, related items can be retrieved or updated on-the-fly ("lazy loading").
 
 Add the trait and its necessary properties to your entities:
-
-```
+```php
 	use \Tatter\Relations\Traits\EntityTrait
 
 	protected $table      = 'users';
 	protected $primaryKey = 'id';
 ```
 
 Related items are available as faux properties:
-
-```
+```php
 	$user = $userModel->find(1);
 
 	foreach ($user->groups as $group)
@@ -102,8 +102,7 @@ Related items are available as faux properties:
 ```
 
 ... and can also be updated directly from the entity:
-
-```
+```php
 	$user->addGroup(3);
 
 	if ($user->hasGroups([1, 3]))
@@ -123,7 +122,7 @@ for "manyToMany" relationships.
 successful, **Relations** will use each table's model to find the related items. This keeps
 consistent the return types, events, and other aspects of your models. In addition to the
 return type, **Relations** will also adjust related items for singleton relationships:
-```
+```php
 // User hasMany Widgets
 $user = $userModel->with('widgets')->find($userId);
 echo "User {$user->name} has " . count($user->widgets) . " widgets.";
@@ -138,7 +137,7 @@ echo $widget->name . " belongs to " . $widget->user->name;
 **ModelTrait** supports nested relation calls, but these can be resource intensive so may
 be disabled by changing `$allowNesting` in the config. With nesting enabled, any related
 items will also load their related items (but not infinitely):
-```
+```php
 /* Define your models */
 class UserModel
 {
@@ -162,6 +161,14 @@ foreach ($groups as $group)
 }
 ```
 
+### Soft Deletes
+
+If your target relations correspond to a CodeIgniter Model that uses [soft deletion](https://codeigniter.com/user_guide/models/model.html#usesoftdeletes)
+then you may include the table name in the `array $withDeletedRelations` property to include
+soft deleted items. This is particularly helpful for tight relationships, like when an item
+`belongsTo` another item that has been soft deleted. `$withDeletedRelations` works on both
+Entities and Models.
+
 ## Performance
 
 *WARNING*: Be aware that **Relations** relies on a schema generated from the **Schemas**
@@ -170,7 +177,7 @@ request initiates the load. The schema will attempt to cache to prevent this del
 if your cache is not configured correctly you will likely experience noticeable performance
 degradation. The recommended approach is to have a cron job generate your schema regularly
 so it never expires and no user will trigger the un-cached load, e.g.:
-```
+```shell
 php spark schemas
 ```
 

src/Traits/BaseTrait.php

@@ -151,7 +151,16 @@ public function _getRelations($tableName, $ids = null): array
 
         // If the model is available then use it to get the result
         // (Bonus: triggers model's afterFind)
-        $results = isset($table->model) ? $builder->find() : $builder->get()->getResult();
+        if (isset($table->model)) {
+            // Check if this table should include soft deletes
+            if (isset($this->withDeletedRelations) && in_array($table->name, $this->withDeletedRelations, true)) {
+                $builder->withDeleted();
+            }
+
+            $results = $builder->find();
+        } else {
+            $results = $builder->get()->getResult();
+        }
 
         // Clean up
         unset($table, $builder);

tests/_support/Models/WorkerModel.php

@@ -9,13 +9,14 @@ class WorkerModel extends Model
 {
     use ModelTrait;
 
-    protected $table              = 'workers';
-    protected $primaryKey         = 'id';
-    protected $returnType         = 'object';
-    protected $useSoftDeletes     = true;
-    protected $allowedFields      = ['firstname', 'lastname', 'role', 'age'];
-    protected $useTimestamps      = true;
-    protected $validationRules    = [];
-    protected $validationMessages = [];
-    protected $skipValidation     = false;
+    protected $table                = 'workers';
+    protected $primaryKey           = 'id';
+    protected $returnType           = 'object';
+    protected $useSoftDeletes       = true;
+    protected $allowedFields        = ['firstname', 'lastname', 'role', 'age'];
+    protected $useTimestamps        = true;
+    protected $validationRules      = [];
+    protected $validationMessages   = [];
+    protected $skipValidation       = false;
+    protected $withDeletedRelations = [];
 }

tests/entity/RelationsTest.php

@@ -110,4 +110,21 @@ public function testRelationsMatchModelWith()
         /** @var Factory $factory */
         $this->assertEquals($factory->workers, $workers);
     }
+
+    public function testWithDeletedRelations()
+    {
+        $object   = (new MachineModel())->with(false)->find(4);
+        $machine1 = new Machine((array) $object);
+        $this->assertNull($machine1->factory);
+
+        $machine2                                 = new class () extends Machine {
+            protected array $withDeletedRelations = ['factories'];
+        };
+        $machine2->fill((array) $object);
+
+        $result = $machine2->factory;
+
+        $this->assertNotNull($result);
+        $this->assertSame('widget', $result->uid);
+    }
 }

tests/model/MethodsTest.php

@@ -86,4 +86,14 @@ public function testBelongsToNested()
 
         $this->assertEquals($factories[3], $machines[6]->factory);
     }
+
+    public function testWithDeletedRelations()
+    {
+        $worker = $this->workers->with('factories')->find(4);
+        $this->assertCount(1, $worker->factories);
+
+        $this->setPrivateProperty($this->workers, 'withDeletedRelations', ['factories']);
+        $worker = $this->workers->with('factories')->find(4);
+        $this->assertCount(2, $worker->factories);
+    }
 }