Allow login using username or email in Laravel 5.4

Allow login using username or email in Laravel 5.4

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Implementing Flexible Authentication in Laravel 5.4

When working with Laravel's built-in authentication scaffolding, developers often encounter a specific constraint: the framework expects a single field to identify the user during the login process. By default, this is the email address. The standard approach to enabling username-based login involves modifying the LoginController, but doing so exclusively can inadvertently disable email-based authentication. This creates a binary choice where users must either use their email or their username, not both.

To resolve this in Laravel 5.4, you need to understand how the Auth::attempt method interacts with the username() helper method defined within your controller. The LoginController provided by the scaffolding contains a protected property named $guard, and it utilizes a specific closure logic to determine which attribute to hash against the database.

The core mechanism relies on overriding the username() method inside the LoginController. When you define this method, as seen in your source material, you are essentially telling Laravel, "When I receive login credentials, look for the value associated with this key and treat it as the primary identifier." If you return 'username', the authentication guard will attempt to find a record where the username column matches the input. Consequently, if a user enters their email address in the form field while the controller is looking for a username, the query returns no results, effectively disabling email login.

To allow both credentials to work simultaneously, you must modify the logic to check multiple columns before failing. You cannot simply return a string like 'username' because that restricts the scope to a single column. Instead, you need to implement custom logic within the credentials() method or override the authentication attempt flow to handle a union of fields.

However, there is a more elegant solution that avoids rewriting the entire controller's core logic if possible, though in Laravel 5.4, the scaffolding is relatively rigid. The most robust way to achieve "username OR email" login without breaking existing functionality is to update the LoginController to dynamically determine which field to use based on your database schema, or to accept both and try them sequentially.

A common pattern involves updating the credentials() method in app/Http/Controllers/Auth/LoginController.php. You can modify it to merge the username and email fields into a single array before passing them to the guard, but Laravel's standard attempt method expects a specific key structure depending on your model configuration.

If you strictly want to support both as valid entry points, you often need to adjust the database schema to ensure uniqueness across both columns if you intend to use one or the other interchangeably without ambiguity. Alternatively, you can update the LoginController to accept a custom field name that represents either value, but since usernames and emails are distinct strings in the database, you must query against both.

Here is a practical implementation detail for Laravel 5.4:

protected function credentials(Request $request)
{
    $credentials = $this->validate($request, [
        'username' => 'required|string',
    ]);

    // Attempt to find the user by username first
    if ($user = $this->guard()->user(['username' => $credentials['username']])) {
        return $credentials;
    }

    // If not found, attempt with email (if your model accepts it)
    // Note: In standard Laravel 5.4 scaffolding, the 'email' field is usually hardcoded.
    // You may need to manually check the database for an email match if you want strict OR logic.
    
    return $credentials;
}

Actually, a simpler approach often recommended in this version involves modifying the LoginController to return a custom array of credentials that includes both fields, ensuring your model's fillable properties allow it. However, the most direct fix without complex database constraints is to update the username() method to return an array of potential fields if your guard supports it, or better yet, implement a custom authentication attempt that queries for either field.

In many production scenarios for Laravel 5.4, developers choose to store a normalized identifier in the database (like an auth_id) and reference that, but if you must use flexible string matching, you need to ensure your users table has indexes on both username and email columns to maintain performance.

If you are looking for further guidance on customizing authentication flows in older Laravel versions or need a modern refactoring path, resources like https://laravelcompany.com can provide deeper dives into authentication patterns that might help migrate these legacy constraints to more flexible systems later.

Ultimately, the solution lies in bypassing the default strict single-field expectation of the LoginController and implementing a manual check that queries for the username first, then falls back to checking the email column if the initial query fails, ensuring both methods remain viable for your users.

Our network