Merge pull request #1109 from kenjis/docs-improve-banning_users

docs: improve banning users

Author: kenjis

docs/references/authentication/authentication.md

@@ -29,28 +29,42 @@ public string $defaultAuthenticator = 'session';
 
 ## Auth Helper
 
-The auth functionality is designed to be used with the `auth_helper` that comes with Shield. This
-helper method provides the `auth()` function which returns a convenient interface to the most frequently
-used functionality within the auth libraries.
+The auth functionality is designed to be used with the `auth_helper` that comes
+with Shield.
+
+!!! note
+
+    The `auth_helper` is autoloaded by CodeIgniter's autoloader if you follow the
+    installation instruction. If you want to *override* the functions, create
+    **app/Helpers/auth_helper.php**.
+
+### Getting the Current User
+
+The `auth()` function returns a convenient interface to the most frequently used
+functionality within the auth libraries.
+
+You can get the current `User` entity.
 
 ```php
 // get the current user
-auth()->user();
+$user = auth()->user();
 
 // get the current user's id
-auth()->id();
+$user_id = auth()->id();
 // or
-user_id();
-
-// get the User Provider (UserModel by default)
-auth()->getProvider();
+$user_id = user_id();
 ```
 
-!!! note
+The `user_id()` function returns the current user's id.
 
-    The `auth_helper` is autoloaded by CodeIgniter's autoloader if you follow the
-    installation instruction. If you want to *override* the functions, create
-    **app/Helpers/auth_helper.php**.
+### Getting the User Provider
+
+You can also get the User Provider.
+
+```php
+// get the User Provider (UserModel by default)
+$users = auth()->getProvider();
+```
 
 ## Authenticator Responses
 

docs/user_management/banning_users.md

@@ -2,6 +2,12 @@
 
 Shield provides a way to ban users from your application. This is useful if you need to prevent a user from logging in, or logging them out in the event that they breach your terms of service.
 
+!!! note
+
+    Before using the following methods, you need to get the `User` entity. See
+    [Getting the Current User](../references/authentication/authentication.md#getting-the-current-user)
+    or [Finding a User](./managing_users.md#finding-a-user) for details.
+
 ### Check if a User is Banned
 
 You can check if a user is banned using `isBanned()` method on the `User` entity. The method returns a boolean `true`/`false`.

docs/user_management/forcing_password_reset.md

@@ -8,6 +8,12 @@ compromised.
 
 This guide provides you with ways to achieve this.
 
+!!! note
+
+    Before using the following methods, you need to get the `User` entity. See
+    [Getting the Current User](../references/authentication/authentication.md#getting-the-current-user)
+    or [Finding a User](./managing_users.md#finding-a-user) for details.
+
 ## Available Methods
 
 Shield provides a way to enforce password resets throughout your application.
@@ -32,7 +38,7 @@ if ($user->requiresPasswordReset()) {
 
 !!! note
 
-    You can use the [force-reset](../../references/controller_filters/#forcing-password-reset)
+    You can use the [force-reset](../references/controller_filters/#forcing-password-reset)
     filter to check.
 
 ### Force Password Reset On a User

docs/user_management/managing_users.md

@@ -4,9 +4,26 @@ Since Shield uses a more complex user setup than many other systems, separating
 
 ## Managing Users by Code
 
+### Finding a User
+
+You can find an existing user from the User Provider. It returns a `User`
+[entity](https://codeigniter.com/user_guide/models/entities.html).
+
+```php
+// Get the User Provider (UserModel by default)
+$users = auth()->getProvider();
+
+// Find by the user_id
+$user = $users->findById(123);
+// Find by the user email
+$user = $users->findByCredentials(['email' => 'user@example.com']);
+```
+
 ### Creating Users
 
-By default, the only values stored in the users table is the username. The first step is to create the user record with the username. If you don't have a username, be sure to set the value to `null` anyway, so that it passes CodeIgniter's empty data check.
+By default, the only values stored in the users table is the username.
+
+The first step is to create the user record with the username. If you don't have a username, be sure to set the value to `null` anyway, so that it passes CodeIgniter's empty data check.
 
 ```php
 use CodeIgniter\Shield\Entities\User;
@@ -30,7 +47,9 @@ $users->addToDefaultGroup($user);
 
 ### Deleting Users
 
-A user's data can be spread over a few different tables so you might be concerned about how to delete all of the user's data from the system. This is handled automatically at the database level for all information that Shield knows about, through the `onCascade` settings of the table's foreign keys. You can delete a user like any other entity.
+A user's data can be spread over a few different tables so you might be concerned about how to delete all of the user's data from the system. This is handled automatically at the database level for all information that Shield knows about, through the `onCascade` settings of the table's foreign keys.
+
+You can delete a user like any other entity.
 
 ```php
 // Get the User Provider (UserModel by default)