refactor: change UserModel::save() to saveWithEmailIdentity()

Author: kenjis

docs/concepts.md

@@ -45,8 +45,8 @@ While this has the potential to make the system more complex, the `email` and `p
 looked up for you when attempting to access them from the User entity. Caution should be used to craft queries that will pull
 in the `email` field when you need to display it to the user, as you could easily run into some n+1 slow queries otherwise.
 
-When you `save($user)` a `User` instance in the `UserModel`, the email/password identity will automatically be updated.
-If no email/password identity exists, you must pass both the email and the password to the User instance prior to calling `save()`.
+When you `saveWithEmailIdentity($user)` a `User` instance in the `UserModel`, the email/password identity will automatically be updated.
+If no email/password identity exists, you must pass both the email and the password to the User instance prior to calling `saveWithEmailIdentity()`.
 
 ## Password Validators
 

docs/quickstart.md

@@ -274,7 +274,7 @@ $user = new User([
     'email'    => '[email protected]',
     'password' => 'secret plain text password',
 ]);
-$users->save($user);
+$users->saveWithEmailIdentity($user);
 
 // To get the complete user object with ID, we need to get from the database
 $user = $users->findById($users->getInsertID());
@@ -296,7 +296,7 @@ NOTE: The User rows use [soft deletes](https://codeigniter.com/user_guide/models
 
 ### Editing A User
 
-The `UserModel::save()` method has been modified to ensure that an email or password previously set on the `User` entity will be automatically updated in the correct `UserIdentity` record.
+The `UserModel::saveWithEmailIdentity()` method ensures that an email or password previously set on the `User` entity will be automatically updated in the correct `UserIdentity` record.
 
 ```php
 $users = model('UserModel');
@@ -307,7 +307,7 @@ $user->fill([
     'email' => '[email protected]',
     'password' => 'secret123'
 ]);
-$users->save($user);
+$users->saveWithEmailIdentity($user);
 ```
 
 If you prefer to use the `update()` method then you will have to update the user's appropriate UserIdentity manually.

src/Authentication/Authenticators/AccessTokens.php

@@ -232,6 +232,6 @@ public function recordActiveDate(): void
 
         $this->user->last_active = Time::now();
 
-        $this->provider->save($this->user);
+        $this->provider->saveWithEmailIdentity($this->user);
     }
 }

src/Authentication/Authenticators/Session.php

@@ -311,7 +311,7 @@ public function check(array $credentials): Result
         // logged in.
         if ($passwords->needsRehash($user->password_hash)) {
             $user->password_hash = $passwords->hash($givenPassword);
-            $this->provider->save($user);
+            $this->provider->saveWithEmailIdentity($user);
         }
 
         return new Result([
@@ -804,7 +804,7 @@ public function recordActiveDate(): void
 
         $this->user->last_active = Time::now();
 
-        $this->provider->save($this->user);
+        $this->provider->saveWithEmailIdentity($this->user);
     }
 
     /**

src/Controllers/RegisterController.php

@@ -70,9 +70,7 @@ public function registerAction(): RedirectResponse
             $user->username = null;
         }
 
-        if (! $users->save($user)) {
-            return redirect()->back()->withInput()->with('errors', $users->errors());
-        }
+        $users->saveWithEmailIdentity($user);
 
         // To get the complete user object with ID, we need to get from the database
         $user = $users->findById($users->getInsertID());

src/Models/UserModel.php

@@ -184,21 +184,14 @@ public function activate(User $user): void
     {
         $user->active = true;
 
-        $return = $this->save($user);
-
-        $this->checkQueryReturn($return);
+        $this->saveWithEmailIdentity($user);
     }
 
     /**
-     * Override the BaseModel's `save()` method to allow
-     * updating of user email, password, or password_hash
-     * fields if they've been modified.
-     *
-     * @param array|User $data
-     *
-     * @TODO can't change the return type to void.
+     * Save User and its Email Identity (email, password, or password_hash fields)
+     * if they've been modified.
      */
-    public function save($data): bool
+    public function saveWithEmailIdentity(User $data): void
     {
         try {
             /** @throws DataException */
@@ -210,13 +203,10 @@ public function save($data): bool
             ];
             if (in_array($e->getMessage(), $messages, true)) {
                 // Save updated email identity
-                if ($data instanceof User) {
-                    $user = $data;
-
-                    $user->saveEmailIdentity();
-                }
+                $user = $data;
+                $user->saveEmailIdentity();
 
-                return true;
+                return;
             }
 
             throw $e;
@@ -238,7 +228,5 @@ public function save($data): bool
 
             $user->saveEmailIdentity();
         }
-
-        return true;
     }
 }

tests/Controllers/ActionsTest.php

@@ -247,7 +247,7 @@ public function testEmailActivateVerify(): void
 
         $this->user->active = false;
         $model              = auth()->getProvider();
-        $model->save($this->user);
+        $model->saveWithEmailIdentity($this->user);
 
         $result = $this->actingAs($this->user, true)
             ->withSession($this->getSessionUserInfo(EmailActivator::class))

tests/Unit/UserModelTest.php

@@ -28,7 +28,7 @@ public function testSaveInsertUser(): void
 
         $user = $this->createNewUser();
 
-        $users->save($user);
+        $users->saveWithEmailIdentity($user);
 
         $user = $users->findByCredentials(['email' => '[email protected]']);
         $this->seeInDatabase('auth_identities', [
@@ -56,15 +56,15 @@ public function testSaveUpdateUserWithUserDataToUpdate(): void
     {
         $users = $this->createUserModel();
         $user  = $this->createNewUser();
-        $users->save($user);
+        $users->saveWithEmailIdentity($user);
 
         $user = $users->findByCredentials(['email' => '[email protected]']);
 
         $user->username = 'bar';
         $user->email    = '[email protected]';
         $user->active   = 1;
 
-        $users->save($user);
+        $users->saveWithEmailIdentity($user);
 
         $this->seeInDatabase('auth_identities', [
             'user_id' => $user->id,
@@ -80,13 +80,13 @@ public function testSaveUpdateUserWithNoUserDataToUpdate(): void
     {
         $users = $this->createUserModel();
         $user  = $this->createNewUser();
-        $users->save($user);
+        $users->saveWithEmailIdentity($user);
 
         $user = $users->findByCredentials(['email' => '[email protected]']);
 
         $user->email = '[email protected]';
 
-        $users->save($user);
+        $users->saveWithEmailIdentity($user);
 
         $this->seeInDatabase('auth_identities', [
             'user_id' => $user->id,

tests/Unit/UserTest.php

@@ -112,7 +112,7 @@ public function testUpdateEmail(): void
         $this->user->active = 0;
 
         $users = model(UserModel::class);
-        $users->save($this->user);
+        $users->saveWithEmailIdentity($this->user);
 
         $user = $users->find($this->user->id);
 
@@ -134,7 +134,7 @@ public function testUpdatePassword(): void
         $this->user->active   = 0;
 
         $users = model(UserModel::class);
-        $users->save($this->user);
+        $users->saveWithEmailIdentity($this->user);
 
         $user = $users->find($this->user->id);
 
@@ -153,7 +153,7 @@ public function testUpdatePasswordHash(): void
         $this->user->active        = 0;
 
         $users = model(UserModel::class);
-        $users->save($this->user);
+        $users->saveWithEmailIdentity($this->user);
 
         $user = $users->find($this->user->id);