Skip to content

How To Sign In with an Email

Dory Azar edited this page Nov 15, 2026 · 1 revision

How to let people sign in with their email address. The simplest way keeps the users table as it is: the username column holds the address, in lower case. Route::auth, passkeys, the throttle and $user['username'] keep working, with no new column. It takes a wider column, two rules, two form fields and two messages. Since 2.19.0.


With Claude

Say it in your idea or your request:

"people sign in with their email, kept in the username column"

/caligrafy-quill:idea puts it in the plan and writes the steps below.

Check: a sign-up with Ada@Example.COM lands in users.username as ada@example.com, and signing in as ADA@example.com works.


By hand

  1. The column. An address can be 254 characters. Before the table exists, write username varchar(254) NOT NULL in application/models/Auth/create_db.sql. For a table that exists, run docker compose exec dev-box php caligrafer.php migrate make username_holds_email, write in the file it names:
    -- username_holds_email
    ALTER TABLE users MODIFY username varchar(254) NOT NULL;
    and run docker compose exec dev-box php caligrafer.php migrate.
  2. The rules. In application/services/Users/CaligrafyRegisterUser.php, replace the $rules line with:
    public $rules = array('username' => 'required|valid_email|max_len,254', 'passcode' => 'required|min_len,8|max_len,72');
    public $filters = array('username' => 'trim|lower_case');
    and in application/services/Users/CaligrafyUpdateUser.php make the rule of username 'valid_email|max_len,254' and add public $filters = array('username' => 'trim|lower_case');. A later update keeps these two files and writes the release's copies next to them as .caligrafy-new.
  3. The forms. In application/views/Auth/login.pug, replace the - $field, - $isEmail lines and the .cq-field of the identifier with:
            .cq-field
              label(for='username') Email
              input#username.form-control(type='email', name='username', value=isset($user) && is_object($user) ? ($user->username ?? '') : '', required, autocomplete='email', autocapitalize='none', maxlength='254')
    In application/views/Auth/register.pug, change the p.cq-lead line to p.cq-lead Your email address, and at least 8 characters for the password. and the first .cq-field to:
          .cq-field
            label(for='username') Email
            input#username.form-control(type='email', name='username', value=$user->username?? '', required, autocomplete='email', autocapitalize='none', maxlength='254')
            if isset($errors['username'])
              p.cq-field-error= $errors['username']
    The field stays named username. A sign-up page of your own changes the same way.
  4. The words, in the messages of Route::auth:
    Route::auth(['home' => '/books', 'messages' => [
        'invalid' => 'Invalid email or password',
        'register_taken' => 'An account already uses this email',
    ]]);
  5. Try it.
You do You get
Create account with not an email A few details need a fix: see the notes under the fields., with the field's message under it
Create account with Ada@Example.COM 302 to /login; SELECT username FROM users shows ada@example.com
The same address again An account already uses this email
Sign in as ADA@example.com 302 to home: the username column ignores case
A wrong password Invalid email or password

Another way: a separate email column

When you need both a username and an address, Route::auth(['identifier' => 'email']) signs in with the email column, and the shipped login.pug names its field after $identifier. The shipped users table has no email column and register_user asks for a username: add the column in a migration and write your own sign-up capability ('register' => 'register_reader') whose $rules declare email. The lookup is the model's findBy($column, $value) (the shipped User has it), else a bound query on its table.


Common mistakes

  • 'identifier' => 'email' with the shipped views and table (G133): the POST field is named after the identifier, so a username field no longer signs in; and the table needs an email column.
  • The sign-up refuses an address (G75): the shipped register_user accepts letters and digits only, until its rules change as in step 2.
  • A mixed-case address in the table: the lower_case filter keeps them all in lower case.

Related pages

Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.

Start here

Why Caligrafy: the benefits, the measurements, and what it is not yet

  1. Quickstart with Claude: describe it, approve it, ship it

    or the Quickstart: the same three steps by hand, in 5 minutes

  2. How Caligrafy works: the ideas in 5 minutes
  3. Your first capability: build a feature, page included

Capabilities

Experiences

Data and people

  1. Models
  2. Relationships
  3. Queries: filters, paging, related rows
  4. Sign-in, users and tokens

Built-in features

Put it online

Build with AI

Reference

Clone this wiki locally