feat: UserModel::save() can save Email Identity again

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 `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()`.
+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()`.
 
 ## Password Validators
 

docs/quickstart.md

@@ -274,7 +274,7 @@ $user = new User([
     'email'    => 'foo.bar@example.com',
     'password' => 'secret plain text password',
 ]);
-$users->saveWithEmailIdentity($user);
+$users->save($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::saveWithEmailIdentity()` method ensures that an email or password previously set on the `User` entity will be automatically updated in the correct `UserIdentity` record.
+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.
 
 ```php
 $users = model('UserModel');
@@ -307,7 +307,7 @@ $user->fill([
     'email' => 'joe.smith@example.com',
     'password' => 'secret123'
 ]);
-$users->saveWithEmailIdentity($user);
+$users->save($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->saveWithEmailIdentity($this->user);
+        $this->provider->save($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->saveWithEmailIdentity($user);
+            $this->provider->save($user);
         }
 
         return new Result([
@@ -804,7 +804,7 @@ public function recordActiveDate(): void
 
         $this->user->last_active = Time::now();
 
-        $this->provider->saveWithEmailIdentity($this->user);
+        $this->provider->save($this->user);
     }
 
     /**

src/Controllers/RegisterController.php

@@ -72,7 +72,7 @@ public function registerAction(): RedirectResponse
         }
 
         try {
-            $users->saveWithEmailIdentity($user);
+            $users->save($user);
         } catch (ValidationException $e) {
             return redirect()->back()->withInput()->with('errors', $users->errors());
         }

src/Models/UserModel.php

@@ -6,6 +6,7 @@
 use CodeIgniter\Model;
 use CodeIgniter\Shield\Authentication\Authenticators\Session;
 use CodeIgniter\Shield\Entities\User;
+use CodeIgniter\Shield\Exceptions\ValidationException;
 use Faker\Generator;
 use InvalidArgumentException;
 
@@ -187,9 +188,29 @@ public function activate(User $user): void
         $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 User $data
+     *
+     * @throws ValidationException
+     */
+    public function save($data): bool
+    {
+        assert($data instanceof User);
+
+        $this->saveWithEmailIdentity($data);
+
+        return true;
+    }
+
     /**
      * Save User and its Email Identity (email, password, or password_hash fields)
      * if they've been modified.
+     *
+     * @throws ValidationException
      */
     public function saveWithEmailIdentity(User $data): void
     {

tests/Unit/UserModelTest.php

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