diff --git a/README.md b/README.md index 60e56d3..d42076b 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,8 @@ catch (\Delight\Auth\TooManyRequestsException $e) { } ``` +If you want to sign in with usernames on the other hand, either in addition to the login via email address or as a replacement, that's possible as well. Simply call the method `loginWithUsername` instead of method `login`. Then, instead of catching `InvalidEmailException`, make sure to catch both `UnknownUsernameException` and `AmbiguousUsernameException`. You may also want to read the notes about the uniqueness of usernames in the section that explains how to [sign up new users](#registration-sign-up). + ### Email verification Extract the selector and token from the URL that the user clicked on in the verification email. diff --git a/src/Auth.php b/src/Auth.php index 04fcce1..dfa9d3c 100644 --- a/src/Auth.php +++ b/src/Auth.php @@ -254,7 +254,7 @@ class Auth { } /** - * Attempts to sign in a user + * Attempts to sign in a user with their email address and password * * @param string $email the user's email address * @param string $password the user's password @@ -268,6 +268,26 @@ class Auth { $this->authenticateUserInternal($password, $email, null, $rememberDuration); } + /** + * Attempts to sign in a user with their username and password + * + * When using this method to authenticate users, you should ensure that usernames are unique + * + * Consistently using {@see registerWithUniqueUsername} instead of {@see register} can be helpful + * + * @param string $username the user's username + * @param string $password the user's password + * @param int|bool|null $rememberDuration (optional) the duration in seconds to keep the user logged in ("remember me"), e.g. `60 * 60 * 24 * 365.25` for one year + * @throws UnknownUsernameException if the specified username does not exist + * @throws AmbiguousUsernameException if the specified username is ambiguous, i.e. there are multiple users with that name + * @throws InvalidPasswordException if the password was invalid + * @throws EmailNotVerifiedException if the email address has not been verified yet via confirmation email + * @throws AuthError if an internal problem occurred (do *not* catch) + */ + public function loginWithUsername($username, $password, $rememberDuration = null) { + $this->authenticateUserInternal($password, null, $username, $rememberDuration); + } + /** * Validates an email address *