Merge branch 'codeigniter4:develop' into userentity

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)

src/Commands/Setup.php

@@ -256,10 +256,8 @@ private function setAutoloadHelpers(): void
         $helpers    = $config->helpers;
         $newHelpers = array_unique(array_merge($helpers, ['auth', 'setting']));
 
-        $pattern = '/^    public \$helpers = \[.*\];/mu';
-        $replace = '    public $helpers = [\'' . implode("', '", $newHelpers) . '\'];';
         $content = file_get_contents($path);
-        $output  = preg_replace($pattern, $replace, $content);
+        $output  = $this->updateAutoloadHelpers($content, $newHelpers);
 
         // check if the content is updated
         if ($output === $content) {
@@ -277,6 +275,18 @@ private function setAutoloadHelpers(): void
         }
     }
 
+    /**
+     * @param string       $content    The content of Config\Autoload.
+     * @param list<string> $newHelpers The list of helpers.
+     */
+    private function updateAutoloadHelpers(string $content, array $newHelpers): string
+    {
+        $pattern = '/^    public \$helpers = \[.*?\];/msu';
+        $replace = '    public $helpers = [\'' . implode("', '", $newHelpers) . '\'];';
+
+        return preg_replace($pattern, $replace, $content);
+    }
+
     private function removeHelperLoadingInBaseController(): void
     {
         $file = 'Controllers/BaseController.php';

src/Language/de/Auth.php

@@ -30,16 +30,16 @@
     'throttled'             => 'Es wurden zu viele Anfragen von dieser IP-Adresse gestellt. Sie können es in {0} Sekunden erneut versuchen.',
     'notEnoughPrivilege'    => 'Sie haben nicht die erforderliche Berechtigung, um den gewünschten Vorgang auszuführen.',
     // JWT Exceptions
-    'invalidJWT'     => '(To be translated) The token is invalid.',
-    'expiredJWT'     => '(To be translated) The token has expired.',
-    'beforeValidJWT' => '(To be translated) The token is not yet available.',
+    'invalidJWT'     => 'Der Token ist ungültig.',
+    'expiredJWT'     => 'Der Token ist abgelaufen.',
+    'beforeValidJWT' => 'Der Token ist noch nicht verfügbar.',
 
     'email'           => 'E-Mail-Adresse',
     'username'        => 'Benutzername',
     'password'        => 'Passwort',
     'passwordConfirm' => 'Passwort (erneut)',
     'haveAccount'     => 'Haben Sie bereits ein Konto?',
-    'token'           => '(To be translated) Token',
+    'token'           => 'Token',
 
     // Buttons
     'confirm' => 'Bestätigen',
@@ -61,7 +61,7 @@
     'magicLinkExpired'   => 'Sorry, der Link ist abgelaufen.',
     'checkYourEmail'     => 'Prüfen Sie Ihre E-Mail!',
     'magicLinkDetails'   => 'Wir haben Ihnen gerade eine E-Mail mit einem Login-Link geschickt. Er ist nur für {0} Minuten gültig.',
-    'magicLinkDisabled'  => '(To be translated) Use of MagicLink is currently not allowed.',
+    'magicLinkDisabled'  => 'Die Verwendung von MagicLink ist derzeit nicht erlaubt.',
     'successLogout'      => 'Sie haben sich erfolgreich abgemeldet.',
     'backToLogin'        => 'Zurück zur Anmeldung',
 

tests/Commands/SetupTest.php

@@ -131,6 +131,41 @@ public function testRunEmailConfigIsFine(): void
         );
     }
 
+    public function testUpdateAutoloadHelpers(): void
+    {
+        $command = new Setup(Services::logger(), Services::commands());
+
+        $updateAutoloadHelpers = $this->getPrivateMethodInvoker($command, 'updateAutoloadHelpers');
+
+        $content = <<<'EOL'
+            class Autoload extends AutoloadConfig
+            {
+                /**
+                 * -------------------------------------------------------------------
+                 * Helpers
+                 * -------------------------------------------------------------------
+                 * Prototype:
+                 *   $helpers = [
+                 *       'form',
+                 *   ];
+                 *
+                 * @var list<string>
+                 */
+                public $helpers = [
+                    'text',
+                    'form',
+                ];
+            }
+            EOL;
+        $helpers = ['text', 'form', 'auth', 'setting'];
+        $output  = $updateAutoloadHelpers($content, $helpers);
+
+        $this->assertStringContainsString(
+            "public \$helpers = ['text', 'form', 'auth', 'setting'];",
+            $output
+        );
+    }
+
     /**
      * @return string app folder path
      */

tests/Language/GermanTranslationTest.php

@@ -18,4 +18,7 @@
  */
 final class GermanTranslationTest extends AbstractTranslationTestCase
 {
+    protected array $excludedLocaleKeyTranslations = [
+        'Auth.token',
+    ];
 }