Merge pull request #44 from kenjis/add-types

refactor: add type declarations

Author: kenjis

src/Auth.php

@@ -6,9 +6,24 @@
 use CodeIgniter\Shield\Authentication\Authentication;
 use CodeIgniter\Shield\Authentication\AuthenticationException;
 use CodeIgniter\Shield\Authentication\AuthenticatorInterface;
-use CodeIgniter\Shield\Interfaces\Authenticatable;
-use CodeIgniter\Shield\Interfaces\UserProvider;
-
+use CodeIgniter\Shield\Entities\User;
+use CodeIgniter\Shield\Models\UserModel;
+
+/**
+ * AuthenticatorInterface:
+ *
+ * @method Result    attempt(array $credentials)
+ * @method Result    check(array $credentials)
+ * @method User|null getUser()
+ * @method bool      loggedIn()
+ * @method bool      login(User $user)
+ * @method void      loginById($userId)
+ * @method bool      logout()
+ * @method void      recordActive()
+ *
+ * Authenticators\Session:
+ * @method $this remember(bool $shouldRemember = true)
+ */
 class Auth
 {
     protected Authentication $authenticate;
@@ -18,8 +33,8 @@ class Auth
      */
     protected ?string $alias = null;
 
-    protected ?Authenticatable $user      = null;
-    protected ?UserProvider $userProvider = null;
+    protected ?User $user              = null;
+    protected ?UserModel $userProvider = null;
 
     public function __construct(Authentication $authenticate)
     {
@@ -28,8 +43,10 @@ public function __construct(Authentication $authenticate)
 
     /**
      * Sets the Authenticator alias that should be used for this request.
+     *
+     * @return $this
      */
-    public function setAuthenticator(?string $alias = null)
+    public function setAuthenticator(?string $alias = null): self
     {
         if (! empty($alias)) {
             $this->alias = $alias;
@@ -40,21 +57,17 @@ public function setAuthenticator(?string $alias = null)
 
     /**
      * Returns the current authentication class.
-     *
-     * @return AuthenticatorInterface
      */
-    public function getAuthenticator()
+    public function getAuthenticator(): AuthenticatorInterface
     {
         return $this->authenticate
             ->factory($this->alias);
     }
 
     /**
      * Returns the current user, if logged in.
-     *
-     * @return Authenticatable|null
      */
-    public function user()
+    public function user(): ?User
     {
         return $this->getAuthenticator()->loggedIn()
             ? $this->getAuthenticator()->getUser()
@@ -64,7 +77,7 @@ public function user()
     /**
      * Returns the current user's id, if logged in.
      *
-     * @return mixed|null
+     * @return int|string|null
      */
     public function id()
     {
@@ -73,7 +86,7 @@ public function id()
             : null;
     }
 
-    public function authenticate(array $credentials)
+    public function authenticate(array $credentials): Result
     {
         $response = $this->authenticate
             ->factory($this->alias)
@@ -94,11 +107,11 @@ public function authenticate(array $credentials)
      *      - auth()->routes($routes);
      *      - auth()->routes($routes, ['except' => ['login', 'register']])
      */
-    public function routes(RouteCollection &$routes, array $config = [])
+    public function routes(RouteCollection &$routes, array $config = []): void
     {
         $authRoutes = config('AuthRoutes')->routes;
 
-        $routes->group('/', ['namespace' => 'CodeIgniter\Shield\Controllers'], static function ($routes) use ($authRoutes, $config) {
+        $routes->group('/', ['namespace' => 'CodeIgniter\Shield\Controllers'], static function (RouteCollection $routes) use ($authRoutes, $config) {
             foreach ($authRoutes as $name => $row) {
                 if (! isset($config['except']) || (isset($config['except']) && ! in_array($name, $config['except'], true))) {
                     foreach ($row as $params) {
@@ -116,10 +129,8 @@ public function routes(RouteCollection &$routes, array $config = [])
      * Returns the Model that is responsible for getting users.
      *
      * @throws AuthenticationException
-     *
-     * @return mixed|UserProvider
      */
-    public function getProvider()
+    public function getProvider(): UserModel
     {
         if ($this->userProvider !== null) {
             return $this->userProvider;
@@ -143,12 +154,11 @@ public function getProvider()
      * own, additional, features on top of the required ones,
      * like "remember-me" functionality.
      *
-     * @param string $method
-     * @param array  $args
+     * @param string[] $args
      *
      * @throws AuthenticationException
      */
-    public function __call($method, $args)
+    public function __call(string $method, array $args)
     {
         $authenticate = $this->authenticate->factory($this->alias);
 

src/Authentication/Actions/ActionInterface.php

@@ -3,6 +3,7 @@
 namespace CodeIgniter\Shield\Authentication\Actions;
 
 use CodeIgniter\HTTP\IncomingRequest;
+use CodeIgniter\HTTP\Response;
 
 /**
  * Interface ActionInterface
@@ -18,14 +19,14 @@ interface ActionInterface
      * This might be asking for the user's email to reset a password,
      * or asking for a cell-number for a 2FA.
      *
-     * @return mixed
+     * @return Response|string
      */
     public function show();
 
     /**
      * Processes the form that was displayed in the previous form.
      *
-     * @return mixed
+     * @return Response|string
      */
     public function handle(IncomingRequest $request);
 
@@ -35,7 +36,7 @@ public function handle(IncomingRequest $request);
      * from clicking the 'confirm my email' action or
      * following entering a code sent in an SMS.
      *
-     * @return mixed
+     * @return Response|string
      */
     public function verify(IncomingRequest $request);
 }

src/Authentication/Actions/Email2FA.php

@@ -3,6 +3,7 @@
 namespace CodeIgniter\Shield\Authentication\Actions;
 
 use CodeIgniter\HTTP\IncomingRequest;
+use CodeIgniter\HTTP\RedirectResponse;
 use CodeIgniter\Shield\Models\UserIdentityModel;
 
 /**
@@ -15,10 +16,8 @@ class Email2FA implements ActionInterface
     /**
      * Displays the "Hey we're going to send you an number to your email"
      * message to the user with a prompt to continue.
-     *
-     * @return mixed
      */
-    public function show()
+    public function show(): string
     {
         $user = auth()->user();
 
@@ -48,7 +47,7 @@ public function show()
      * with the user, and fires off an email to the user with the code,
      * then displays the form to accept the 6 digits
      *
-     * @return mixed
+     * @return RedirectResponse|string
      */
     public function handle(IncomingRequest $request)
     {
@@ -83,7 +82,7 @@ public function handle(IncomingRequest $request)
     /**
      * Attempts to verify the code the user entered.
      *
-     * @return mixed
+     * @return RedirectResponse|string
      */
     public function verify(IncomingRequest $request)
     {

src/Authentication/Actions/EmailActivator.php

@@ -4,6 +4,7 @@
 
 use CodeIgniter\Exceptions\PageNotFoundException;
 use CodeIgniter\HTTP\IncomingRequest;
+use CodeIgniter\HTTP\RedirectResponse;
 use CodeIgniter\Shield\Models\UserIdentityModel;
 
 class EmailActivator implements ActionInterface
@@ -12,10 +13,8 @@ class EmailActivator implements ActionInterface
      * Shows the initial screen to the user telling them
      * that an email was just sent to them with a link
      * to confirm their email address.
-     *
-     * @return mixed
      */
-    public function show()
+    public function show(): string
     {
         $user = auth()->user();
 
@@ -47,13 +46,11 @@ public function show()
             ->send();
 
         // Display the info page
-        echo view(setting('Auth.views')['action_email_activate_show'], ['user' => $user]);
+        return view(setting('Auth.views')['action_email_activate_show'], ['user' => $user]);
     }
 
     /**
      * This method is unused.
-     *
-     * @return mixed
      */
     public function handle(IncomingRequest $request)
     {
@@ -64,7 +61,7 @@ public function handle(IncomingRequest $request)
      * Verifies the email address and code matches an
      * identity we have for that user.
      *
-     * @return mixed
+     * @return RedirectResponse|string
      */
     public function verify(IncomingRequest $request)
     {

src/Authentication/Authentication.php

@@ -3,19 +3,19 @@
 namespace CodeIgniter\Shield\Authentication;
 
 use CodeIgniter\Shield\Config\Auth as AuthConfig;
-use CodeIgniter\Shield\Interfaces\UserProvider;
+use CodeIgniter\Shield\Models\UserModel;
 
 class Authentication
 {
     /**
      * Instantiated Authenticator objects,
      * stored by Authenticator alias.
      *
-     * @var array<string, AuthenticatorInterface>
+     * @var array<string, AuthenticatorInterface> [Authenticator_alias => Authenticator_instance]
      */
     protected array $instances = [];
 
-    protected ?UserProvider $userProvider = null;
+    protected ?UserModel $userProvider = null;
     protected AuthConfig $config;
 
     public function __construct(AuthConfig $config)
@@ -33,10 +33,8 @@ public function __construct(AuthConfig $config)
      * @param string|null $alias Authenticator alias
      *
      * @throws AuthenticationException
-     *
-     * @return AuthenticatorInterface
      */
-    public function factory(?string $alias = null)
+    public function factory(?string $alias = null): AuthenticatorInterface
     {
         // Determine actual Authenticator alias
         $alias ??= $this->config->defaultAuthenticator;
@@ -53,7 +51,7 @@ public function factory(?string $alias = null)
 
         $className = $this->config->authenticators[$alias];
 
-        assert($this->userProvider !== null, '$userProvider must be set.');
+        assert($this->userProvider !== null, 'You must set $this->userProvider.');
 
         $this->instances[$alias] = new $className($this->userProvider);
 
@@ -65,7 +63,7 @@ public function factory(?string $alias = null)
      *
      * @return $this
      */
-    public function setProvider(UserProvider $provider)
+    public function setProvider(UserModel $provider): self
     {
         $this->userProvider = $provider;
 

src/Authentication/AuthenticationException.php

@@ -12,22 +12,22 @@ class AuthenticationException extends Exception
     /**
      * @param string $alias Authenticator alias
      */
-    public static function forUnknownAuthenticator(string $alias)
+    public static function forUnknownAuthenticator(string $alias): self
     {
         return new self(lang('Auth.unknownAuthenticator', [$alias]));
     }
 
-    public static function forUnknownUserProvider()
+    public static function forUnknownUserProvider(): self
     {
         return new self(lang('Auth.unknownUserProvider'));
     }
 
-    public static function forInvalidUser()
+    public static function forInvalidUser(): self
     {
         return new self(lang('Auth.invalidUser'));
     }
 
-    public static function forNoEntityProvided()
+    public static function forNoEntityProvided(): self
     {
         return new self(lang('Auth.noUserEntity'), 500);
     }

src/Authentication/AuthenticatorInterface.php

@@ -2,7 +2,8 @@
 
 namespace CodeIgniter\Shield\Authentication;
 
-use CodeIgniter\Shield\Interfaces\Authenticatable;
+use CodeIgniter\Shield\Entities\User;
+use CodeIgniter\Shield\Result;
 
 interface AuthenticatorInterface
 {
@@ -11,18 +12,14 @@ interface AuthenticatorInterface
      * Logs the user in with a successful check.
      *
      * @throws AuthenticationException
-     *
-     * @return mixed
      */
-    public function attempt(array $credentials);
+    public function attempt(array $credentials): Result;
 
     /**
      * Checks a user's $credentials to see if they match an
      * existing user.
-     *
-     * @return mixed
      */
-    public function check(array $credentials);
+    public function check(array $credentials): Result;
 
     /**
      * Checks if the user is currently logged in.
@@ -34,10 +31,8 @@ public function loggedIn(): bool;
      * On success this must trigger the "login" Event.
      *
      * @see https://codeigniter4.github.io/CodeIgniter4/extending/authentication.html
-     *
-     * @return mixed
      */
-    public function login(Authenticatable $user);
+    public function login(User $user): bool;
 
     /**
      * Logs a user in based on their ID.
@@ -54,22 +49,16 @@ public function loginById($userId): void;
      * On success this must trigger the "logout" Event.
      *
      * @see https://codeigniter4.github.io/CodeIgniter4/extending/authentication.html
-     *
-     * @return mixed
      */
-    public function logout();
+    public function logout(): bool;
 
     /**
      * Returns the currently logged in user.
-     *
-     * @return Authenticatable|null
      */
-    public function getUser();
+    public function getUser(): ?User;
 
     /**
      * Updates the user's last active date.
-     *
-     * @return mixed
      */
-    public function recordActive();
+    public function recordActive(): void;
 }