Implement Username or Email Authentication in Laravel
Introduction
Laravel’s authentication system handles logins using an email address by default. However, many applications provide better flexibility by letting users authenticate using either their email address or a unique username.
In this tutorial, you’ll learn how to implement username or email authentication seamlessly in a Laravel application.
Prerequisites: Before getting started, make sure you have:
- PHP 8.2 or later
- Composer
- Laravel 10 or later
- A configured database
If you are creating a fresh project for this, spin it up using Composer:
composer create-project laravel/laravel username-auth
---
title: "Implement Username or Email Authentication in Laravel"
description: "Learn how to allow users to log in with either their email address or username in a modern Laravel application."
date: 2023-05-04
summary: "A step-by-step guide to implementing username or email authentication in Laravel."
cover: "/images/post/laravel.jpeg"
thumbnail: "/images/post/laravel.jpeg"
categories:
- Laravel
tags:
- Laravel
- Authentication
- PHP
- Laravel Breeze
authors:
- Tejiri Mayone
featured: true
draft: false
---
## Introduction
Laravel's authentication system handles logins using an email address by default. However, many applications provide better flexibility by letting users authenticate using either their email address or a unique username.
In this tutorial, you'll learn how to implement username or email authentication seamlessly in a Laravel application.
> **Prerequisites:** Before getting started, make sure you have:
> * PHP 8.2 or later
> * Composer
> * Laravel 10 or later
> * A configured database
If you are creating a fresh project for this, spin it up using Composer:
```bash
composer create-project laravel/laravel username-auth
```markdown
---
title: "Implement Username or Email Authentication in Laravel"
description: "Learn how to allow users to log in with either their email address or username in a modern Laravel application."
date: 2023-05-04
summary: "A step-by-step guide to implementing username or email authentication in Laravel."
cover: "/images/blog/laravel.jpeg"
thumbnail: "/images/blog/laravel.jpeg"
categories:
- Laravel
tags:
- Laravel
- Authentication
- PHP
- Laravel Breeze
authors:
- Tejiri Mayone
featured: true
draft: false
---
## Introduction
Laravel's authentication system handles logins using an email address by default. However, many applications provide better flexibility by letting users authenticate using either their email address or a unique username.
In this tutorial, you'll learn how to implement username or email authentication seamlessly in a Laravel application.
> **Prerequisites:** Before getting started, make sure you have:
> * PHP 8.2 or later
> * Composer
> * Laravel 10 or later
> * A configured database
If you are creating a fresh project for this, spin it up using Composer:
```bash
composer create-project laravel/laravel username-auth
Step 1: Install Authentication
For modern Laravel applications, Laravel Breeze provides an excellent, lightweight starting point. Run the following commands in your project root to scaffold the auth system:
composer require laravel/breeze --dev
php artisan breeze:install
php artisan migrate
npm install
npm run dev
You should now have a fully functional login and registration system.
Step 2: Add a Username Column
Next, we need to ensure our database schema accommodates a username field. open your users migration file and add:
$table->string('username')->unique();
If your application is already running in production, generate a new migration instead of modifying the existing one:
php artisan make:migration add_username_to_users_table
Inside your new migration file, define the schema change:
Schema::table('users', function (Blueprint $table) {
$table->string('username')->unique()->after('email');
});
Apply the database changes:
php artisan migrate
Step 3: Update the Login Controller
We need to capture the incoming input and determine whether the user typed an email structure or a username string.
Modify the store() method inside app/Http/Controllers/Auth/AuthenticatedSessionController.php:
public function store(LoginRequest $request)
{
$field = filter_var($request->email, FILTER_VALIDATE_EMAIL) ? 'email' : 'username';
$request->merge([
$field => $request->email,
]);
$request->authenticate();
$request->session()->regenerate();
return redirect()->intended(RouteServiceProvider::HOME);
}
How it works:
The FILTER_VALIDATE_EMAIL constant natively inspects the input text. If it formats properly as an email, we pass it forward via the standard 'email' array path. If it fails, Laravel implicitly assumes the value is a 'username'.
Step 4: Update LoginRequest
Now we need to update the request validator so it attempts authentication using our dynamic field keys.
Open app/Http/Requests/Auth/LoginRequest.php and replace the original authenticate() method:
public function authenticate(): void
{
$this->ensureIsNotRateLimited();
$field = $this->has('username') ? 'username' : 'email';
if (! Auth::attempt($this->only($field, 'password'), $this->boolean('remember'))) {
RateLimiter::hit($this->throttleKey());
throw ValidationException::withMessages([
'email' => trans('auth.failed'),
]);
}
RateLimiter::clear($this->throttleKey());
}
Step 5: Update the Login Form
The beauty of this approach is that you don’t need to bloat your UI with separate email and username inputs. Keep your generic string attribute named "email", but update the placeholders to reflect the new functionality.
<input
type="text"
name="email"
id="email"
placeholder="Email or Username"
required
autofocus>
Your controller will automatically parse the input type behind the scenes!
Login Flow Breakdown
When a user submits the form, the lifecycle behaves as follows:
- The user logs in with either an email address or username.
- The custom logic evaluates the input using native PHP string filters.
- If it looks like an email, authentication is routed to match the
emailtable column. - If it doesn’t match email validation patterns, authentication routes to the
usernamecolumn instead.
Conclusion
Allowing users to authenticate with either a username or an email address provides an intuitive, friction-free login experience without heavily complicating your codebase.
By combining Laravel’s underlying Auth::attempt mechanisms with PHP’s native validation flags, you gain dual-method processing while keeping your front-end architecture perfectly clean.