Allow easier overriding of views in developer applications. Fixes #555

Author: lonnieezell

docs/customization.md

@@ -4,6 +4,7 @@
   - [Route Configuration](#route-configuration)
   - [Custom Redirect URLs](#custom-redirect-urls)
   - [Extending the Controllers](#extending-the-controllers)
+  - [Integrating Custom View Libraries](#integrating-custom-view-libraries)
   - [Custom Validation Rules](#custom-validation-rules)
     - [Registration](#registration)
     - [Login](#login)
@@ -90,6 +91,25 @@ class LoginController extends ShieldLogin
 }
 ```
 
+## Integrating Custom View Libraries
+
+If your application uses a different method to convert view files to HTML than CodeIgniter's built-in `view()` helper you can easily integrate your system anywhere that a view is rendered within Shield. All controllers and actions use the `CodeIgniter\Shield\Traits\Viewable` trait which provides a simple `renderView()` method that takes the same arguments as the `view()` helper. This allows you to extend the Action or Controller and only change the single method of rendering the view, leaving all of the logic untouched so your app will not need to maintain Shield logic when it doesn't need to change it.
+
+```php
+use Acme\Themes\Traits\Themeable;
+use CodeIgniter\Shield\Controllers\LoginController;
+
+class MyLoginController extends LoginController
+{
+    use Themable;
+
+    protected function view(string $view, array $data=[], array $options=[])
+    {
+        return $this->themedView($view, $data, $options);
+    }
+}
+```
+
 ## Custom Validation Rules
 
 ### Registration
@@ -149,7 +169,7 @@ Similar to the process for validation rules in the **Registration** section, you
 
 ```php
     //--------------------------------------------------------------------
-    // Rules For Login 
+    // Rules For Login
     //--------------------------------------------------------------------
     public $login = [
         // 'username' => [

src/Authentication/Actions/Email2FA.php

@@ -12,6 +12,7 @@
 use CodeIgniter\Shield\Entities\UserIdentity;
 use CodeIgniter\Shield\Exceptions\RuntimeException;
 use CodeIgniter\Shield\Models\UserIdentityModel;
+use CodeIgniter\Shield\Traits\Viewable;
 
 /**
  * Class Email2FA
@@ -20,6 +21,8 @@
  */
 class Email2FA implements ActionInterface
 {
+    use Viewable;
+
     private string $type = Session::ID_TYPE_EMAIL_2FA;
 
     /**
@@ -38,7 +41,7 @@ public function show(): string
 
         $this->createIdentity($user);
 
-        return view(setting('Auth.views')['action_email_2fa'], ['user' => $user]);
+        return $this->renderView(setting('Auth.views')['action_email_2fa'], ['user' => $user]);
     }
 
     /**
@@ -81,7 +84,7 @@ public function handle(IncomingRequest $request)
         $email = emailer()->setFrom(setting('Email.fromEmail'), setting('Email.fromName') ?? '');
         $email->setTo($user->email);
         $email->setSubject(lang('Auth.email2FASubject'));
-        $email->setMessage(view(setting('Auth.views')['action_email_2fa_email'], ['code' => $identity->secret, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
+        $email->setMessage($this->renderView(setting('Auth.views')['action_email_2fa_email'], ['code' => $identity->secret, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
 
         if ($email->send(false) === false) {
             throw new RuntimeException('Cannot send email for user: ' . $user->email . "\n" . $email->printDebugger(['headers']));
@@ -90,7 +93,7 @@ public function handle(IncomingRequest $request)
         // Clear the email
         $email->clear();
 
-        return view(setting('Auth.views')['action_email_2fa_verify']);
+        return $this->renderView(setting('Auth.views')['action_email_2fa_verify']);
     }
 
     /**
@@ -116,7 +119,7 @@ public function verify(IncomingRequest $request)
         if (! $authenticator->checkAction($identity, $postedToken)) {
             session()->setFlashdata('error', lang('Auth.invalid2FAToken'));
 
-            return view(setting('Auth.views')['action_email_2fa_verify']);
+            return $this->renderView(setting('Auth.views')['action_email_2fa_verify']);
         }
 
         // Get our login redirect url

src/Authentication/Actions/EmailActivator.php

@@ -15,9 +15,12 @@
 use CodeIgniter\Shield\Exceptions\LogicException;
 use CodeIgniter\Shield\Exceptions\RuntimeException;
 use CodeIgniter\Shield\Models\UserIdentityModel;
+use CodeIgniter\Shield\Traits\Viewable;
 
 class EmailActivator implements ActionInterface
 {
+    use Viewable;
+
     private string $type = Session::ID_TYPE_EMAIL_ACTIVATE;
 
     /**
@@ -55,7 +58,7 @@ public function show(): string
         $email = emailer()->setFrom(setting('Email.fromEmail'), setting('Email.fromName') ?? '');
         $email->setTo($userEmail);
         $email->setSubject(lang('Auth.emailActivateSubject'));
-        $email->setMessage(view(setting('Auth.views')['action_email_activate_email'], ['code' => $code, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
+        $email->setMessage($this->renderView(setting('Auth.views')['action_email_activate_email'], ['code' => $code, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
 
         if ($email->send(false) === false) {
             throw new RuntimeException('Cannot send email for user: ' . $user->email . "\n" . $email->printDebugger(['headers']));
@@ -65,7 +68,7 @@ public function show(): string
         $email->clear();
 
         // Display the info page
-        return view(setting('Auth.views')['action_email_activate_show'], ['user' => $user]);
+        return $this->renderView(setting('Auth.views')['action_email_activate_show'], ['user' => $user]);
     }
 
     /**
@@ -102,7 +105,7 @@ public function verify(IncomingRequest $request)
         if (! $authenticator->checkAction($identity, $postedToken)) {
             session()->setFlashdata('error', lang('Auth.invalidActivateToken'));
 
-            return view(setting('Auth.views')['action_email_activate_show']);
+            return $this->renderView(setting('Auth.views')['action_email_activate_show']);
         }
 
         $user = $authenticator->getUser();

src/Controllers/LoginController.php

@@ -7,9 +7,12 @@
 use App\Controllers\BaseController;
 use CodeIgniter\HTTP\RedirectResponse;
 use CodeIgniter\Shield\Authentication\Authenticators\Session;
+use CodeIgniter\Shield\Traits\Viewable;
 
 class LoginController extends BaseController
 {
+    use Viewable;
+
     protected $helpers = ['setting'];
 
     /**
@@ -31,7 +34,7 @@ public function loginView()
             return redirect()->route('auth-action-show');
         }
 
-        return view(setting('Auth.views')['login']);
+        return $this->renderView(setting('Auth.views')['login']);
     }
 
     /**

src/Controllers/MagicLinkController.php

@@ -13,6 +13,7 @@
 use CodeIgniter\Shield\Models\LoginModel;
 use CodeIgniter\Shield\Models\UserIdentityModel;
 use CodeIgniter\Shield\Models\UserModel;
+use CodeIgniter\Shield\Traits\Viewable;
 
 /**
  * Handles "Magic Link" logins - an email-based
@@ -24,6 +25,8 @@
  */
 class MagicLinkController extends BaseController
 {
+    use Viewable;
+
     /**
      * @var UserModel
      */
@@ -48,7 +51,7 @@ public function loginView()
             return redirect()->to(config('Auth')->loginRedirect());
         }
 
-        return view(setting('Auth.views')['magic-link-login']);
+        return $this->renderView(setting('Auth.views')['magic-link-login']);
     }
 
     /**
@@ -102,7 +105,7 @@ public function loginAction()
         $email = emailer()->setFrom(setting('Email.fromEmail'), setting('Email.fromName') ?? '');
         $email->setTo($user->email);
         $email->setSubject(lang('Auth.magicLinkSubject'));
-        $email->setMessage(view(setting('Auth.views')['magic-link-email'], ['token' => $token, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
+        $email->setMessage($this->renderView(setting('Auth.views')['magic-link-email'], ['token' => $token, 'ipAddress' => $ipAddress, 'userAgent' => $userAgent, 'date' => $date]));
 
         if ($email->send(false) === false) {
             log_message('error', $email->printDebugger(['headers']));
@@ -121,7 +124,7 @@ public function loginAction()
      */
     protected function displayMessage(): string
     {
-        return view(setting('Auth.views')['magic-link-message']);
+        return $this->renderView(setting('Auth.views')['magic-link-message']);
     }
 
     /**

src/Controllers/RegisterController.php

@@ -11,6 +11,7 @@
 use CodeIgniter\Shield\Entities\User;
 use CodeIgniter\Shield\Exceptions\ValidationException;
 use CodeIgniter\Shield\Models\UserModel;
+use CodeIgniter\Shield\Traits\Viewable;
 
 /**
  * Class RegisterController
@@ -20,6 +21,8 @@
  */
 class RegisterController extends BaseController
 {
+    use Viewable;
+
     protected $helpers = ['setting'];
 
     /**
@@ -47,7 +50,7 @@ public function registerView()
             return redirect()->route('auth-action-show');
         }
 
-        return view(setting('Auth.views')['register']);
+        return $this->renderView(setting('Auth.views')['register']);
     }
 
     /**

src/Traits/Viewable.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CodeIgniter\Shield\Traits;
+
+trait Viewable
+{
+    /**
+     * Provides a way for third-party systems to simply override
+     * the way the view gets converted to HTML to integrate with their
+     * own templating systems.
+     */
+    protected function renderView(string $view, array $data = [], array $options = []): string
+    {
+        return view($view, $data, $options);
+    }
+}