docs: split customization.md

Author: kenjis

docs/customization.md

@@ -0,0 +1,31 @@
+# Extending the Controllers
+
+Shield has the following controllers that can be extended to handle
+various parts of the authentication process:
+
+-   **ActionController** handles the after-login and after-registration actions, like Two Factor Authentication and Email Verification.
+-   **LoginController** handles the login process.
+-   **RegisterController** handles the registration process. Overriding this class allows you to customize the User Provider, the User Entity, and the validation rules.
+-   **MagicLinkController** handles the "lost password" process that allows a user to login with a link sent to their email. This allows you to
+    override the message that is displayed to a user to describe what is happening, if you'd like to provide more information than simply swapping out the view used.
+
+It is not recommended to copy the entire controller into **app/Controllers** and change its namespace. Instead, you should create a new controller that extends
+the existing controller and then only override the methods needed. This allows the other methods to stay up to date with any security
+updates that might happen in the controllers.
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use CodeIgniter\Shield\Controllers\LoginController as ShieldLogin;
+use CodeIgniter\HTTP\RedirectResponse;
+
+class LoginController extends ShieldLogin
+{
+    public function logoutAction(): RedirectResponse
+    {
+        // new functionality
+    }
+}
+```

docs/customization/extending_controllers.md

@@ -0,0 +1,18 @@
+# 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 `view()` 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 = []): string
+    {
+        return $this->themedView($view, $data, $options);
+    }
+}
+```

docs/customization/integrating_custom_view_libs.md

@@ -0,0 +1,34 @@
+# Customizing Login Identifier
+
+If your application has a need to use something other than `email` or `username`, you may specify any valid column within the `users` table that you may have added. This allows you to easily use phone numbers, employee or school IDs, etc as the user identifier. You must implement the following steps to set this up:
+
+This only works with the Session authenticator.
+
+1. Create a [migration](http://codeigniter.com/user_guide/dbmgmt/migration.html) that adds a new column to the `users` table.
+2. Edit `app/Config/Auth.php` so that the new column you just created is within the `$validFields` array.
+
+    ```php
+    public array $validFields = [
+        'employee_id'
+    ];
+    ```
+
+    If you have multiple login forms on your site that use different credentials, you must have all of the valid identifying fields in the array.
+
+    ```php
+    public array $validFields = [
+        'email',
+        'employee_id'
+    ];
+    ```
+    > **Warning**
+    > It is very important for security that if you add a new column for identifier you must write a new **Validation Rules** and then set it using the [custom-validation-rules](https://github.com/codeigniter4/shield/blob/develop/docs/customization.md#custom-validation-rules) description.
+
+3. Edit the login form to change the name of the default `email` input to the new field name.
+
+    ```php
+    <!-- Email -->
+    <div class="mb-2">
+        <input type="text" class="form-control" name="employee_id" autocomplete="new-employee-id" placeholder="12345" value="<?= old('employee_id') ?>" required />
+    </div>
+    ```