DEV Community: Vinicius

CakeDC/Users: why "Remember me" sets a cookie but never logs you back in

Vinicius — Sat, 31 Oct 2026 17:10:10 +0000

My users kept complaining that the admin panel logged them out "all the time", even with Remember me checked. I assumed it was just the PHP session expiring. Half of that was right. The other half was a quiet configuration trap in the CakePHP authentication stack. It probably affects other CakePHP 5 apps that use cakedc/users with the default authenticators.

TL;DR: the Cookie authenticator in CakeDC/Users' default config has no identifier of its own. In cakephp/authentication 3.3, an authenticator without one inherits the identifier of the previous authenticator that had one. In the default order, that's the Token authenticator, which looks users up by api_token. So the remember-me cookie is written but never matches anyone. Give Cookie its own identifier and it works.

Versions where I hit it: CakePHP 5.4, cakedc/users 16.0.4, cakedc/auth (its CookieAuthenticator), cakephp/authentication 3.3.7.

The symptoms

You sign in with Remember me checked.
The browser does get a cookie. It's called CookieAuth; remember_me is only the name of the form checkbox. It's httponly and expires in one month.
Once the PHP session ends (garbage collection, server restart, deploy, or you delete the session cookie), the next request redirects to /login. The remember-me cookie is still there, but it is ignored.
Nothing is logged. To the framework, a cookie that matches no user is just a failed authentication, so it moves on to the next authenticator.

To reproduce it quickly, sign in with Remember me, delete only the session cookie (CAKEPHP by default) in devtools, and reload. If you land on the login page, you have this problem.

How authenticators get their identifier

cakephp/authentication separates authenticators (where the credentials come from: session, form, token, cookie…) from identifiers (how those credentials become a user: password check, token lookup…).

Since 3.3, the recommended style is to put the identifier inside each authenticator's config. loadIdentifier() is deprecated. Here is how the collection builds each authenticator (src/Authenticator/AuthenticatorCollection.php):

protected function _create(object|string $class, string $alias, array $config): AuthenticatorInterface
{
    if (is_string($class)) {
        if (!empty($config['identifier'])) {
            $this->_identifiers = new IdentifierCollection((array)$config['identifier']);
        }

        return new $class($this->_identifiers, $config);
    }

    return $class;
}

$this->_identifiers is a property of the collection, shared by every authenticator it creates. An authenticator with an identifier replaces it. An authenticator without one gets whatever the previous one left there.

The default CakeDC/Users config

Here is the relevant part of vendor/cakedc/users/config/users.php, trimmed and in the order it appears:

'Authenticators' => [
    'Session' => [...],                       // no identifier (doesn't need one)
    'Form' => [
        'className' => 'CakeDC/Auth.Form',
        'identifier' => ['Authentication.Password' => [...]],   // ① sets Password
    ],
    'Token' => [
        'className' => 'Authentication.Token',
        'identifier' => ['Authentication.Token' => [
            'tokenField' => 'api_token',                         // ② replaces it with Token
        ]],
    ],
    'Cookie' => [
        'className' => 'CakeDC/Auth.Cookie',
        'rememberMeField' => 'remember_me',
        'cookie' => ['expires' => new \DateTime('+1 month'), 'httponly' => true],
        // ③ no identifier → inherits the Token identifier from ②
    ],
    'Social' => [...],
    // ...
],

The remember-me token is [username, expires, hmac]. When the cookie authenticator sees one, it asks its identifier for the user with that username and then checks the HMAC against the user's password hash. Its identifier, though, is the TokenIdentifier, which searches the api_token column. No user has their username as an API token, so the result is FAILURE_IDENTITY_NOT_FOUND and you're logged out.

Nothing in the remember-me code itself is broken. The cookie authenticator just ends up with the wrong identifier, because of where it sits in the array.

The fix

Give the Cookie authenticator an identifier of its own, in your app's users config. That's the file you pass in Users.config, loaded after the plugin's, for example config/users.php or config/app_users.php:

return [
    'Auth' => [
        'Authenticators' => [
            // "Remember me": the Cookie authenticator needs its OWN identifier.
            // Without one, cakephp/authentication 3.3 hands it the identifier
            // of the previous authenticator that had one (Token / api_token),
            // and the cookie never finds the user.
            'Cookie' => [
                'identifier' => [
                    'Authentication.Password' => [
                        'fields' => [
                            'username' => 'username',
                            'password' => 'password',
                        ],
                        'resolver' => [
                            'className' => 'Authentication.Orm',
                            'finder' => 'active',
                        ],
                    ],
                ],
            ],
        ],
        // ... the rest of your Auth config
    ],
];

Some notes on this block:

It merges with the plugin's config. You only add the identifier key; className, cookie options and rememberMeField stay as the plugin defines them. Check with debug(Configure::read('Auth.Authenticators.Cookie')) if your config loading is unusual.
The username field must be what the cookie stores. The token is built from the cookie authenticator's fields.username, which defaults to username. If your users sign in by e-mail and the username column holds the e-mail, this works as is. If you changed the cookie authenticator's fields, use the same column here.
Keep the active finder, so a disabled user can't come back in through an old cookie.
You don't need to clear existing cookies. Tokens that were already issued start working, as long as they haven't expired.

A regression test

This bug fails silently, so it's worth a test that would have caught it. With IntegrationTestTrait:

public function testCookieSignsBackInAfterTheSessionEnds(): void
{
    $this->enableCsrfToken();
    $this->enableSecurityToken();
    $this->post('/login', [
        'username' => 'staff@example.com',
        'password' => 'secret',
        'remember_me' => '1',
    ]);
    $this->assertRedirectContains('/dashboard');

    // Pull the remember-me cookie out of the response
    $cookie = null;
    foreach ($this->_response->getHeader('Set-Cookie') as $header) {
        if (str_starts_with($header, 'CookieAuth=')) {
            $cookie = urldecode(explode(';', substr($header, strlen('CookieAuth=')))[0]);
        }
    }
    $this->assertNotEmpty($cookie);

    // "The session died": drop it, keep only the cookie
    $this->_session = [];
    $_SESSION = [];
    $this->cookie('CookieAuth', $cookie);

    $this->get('/dashboard');
    $this->assertResponseOk();
}

Add a second test with remember_me => '0' that expects a redirect to /login after the session is dropped, so you know the cookie is the only thing letting the user back in.

Two notes on the test:

$this->_response->getCookie('remember_me') returns null, because the cookie isn't called remember_me. Read the Set-Cookie headers, or use the configured cookie.name.
The test failed before the fix and passed after it. Check that it fails without the fix (git stash), or it isn't proving anything.

The same trap elsewhere

The underlying rule is general: in cakephp/authentication 3.3, an authenticator without identifier uses the identifier of the last authenticator above it that had one. So:

If you add or enable an authenticator that identifies users (a custom one, LDAP, JWT…), give it an explicit identifier, even if it "obviously" uses the same one as Form.
If you reorder Auth.Authenticators, or remove Token because you don't use API keys, which identifier each one inherits can change without anything telling you.
When an authentication "just fails", look at the Result status. FAILURE_IDENTITY_NOT_FOUND with valid credentials points at the wrong identifier, not at a bad password. You can inspect it with $this->Authentication->getResult() in a controller (->getStatus(), ->getErrors()).

The other half: the PHP session itself

Once remember-me works, a short session is only a small annoyance. It's still worth fixing, because it was the reason people noticed the bug in the first place:

PHP's default session.gc_maxlifetime is 1440 seconds (24 minutes).
On shared hosting, sessions often live in a shared directory where another site's lower gc_maxlifetime, or a system cron, can delete yours early.

In config/app.php:

'Session' => [
    'defaults' => 'cake',   // files in TMP/sessions, not the server-wide dir
    'timeout' => 120,       // minutes of inactivity (sets gc_maxlifetime)
],

'defaults' => 'cake' keeps the session files inside your app, out of the shared directory. Two things to keep in mind:

tmp/ usually isn't in git, so create tmp/sessions on deploy, or with a guarded mkdir in config/bootstrap.php. It has to be writable by the web server user.
With Deployer or similar, make sure tmp is a shared dir, or every deploy logs everyone out.
Moving the session directory invalidates the current sessions once. With remember-me fixed, users who checked the box won't even notice.

Checklist for your own CakePHP apps

composer show cakedc/users cakephp/authentication. Are you on cakephp/authentication 3.3+ with CakeDC's default Authenticators?
debug(Configure::read('Auth.Authenticators')). Does Cookie have an identifier? Which authenticator with an identifier comes before it?
Manual test: sign in with Remember me, delete only the session cookie, reload.
Add the Cookie.identifier block above. Use the same username column the cookie uses and keep the active finder.
Add the regression test, and make sure it fails without the fix.
Optionally, set Session.defaults = 'cake' and a timeout, and make tmp/sessions writable and shared between deploys.

If you know whether this also happens in older cakephp/authentication versions, or whether CakeDC plans to add an identifier to the default Cookie config, let me know in the comments.

Per-user two-factor auth in CakePHP with CakeDC/Users (opt-in, one method)

Vinicius — Tue, 25 Aug 2026 00:52:51 +0000

CakeDC/Users gives you TOTP two-factor authentication almost for free: flip one config key and every login grows a "enter your 6-digit code" step. The catch is that word every. The built-in flow is all-or-nothing — turn it on and all your users are forced through the OTP challenge on their next login, whether they ever set up an authenticator app or not. Lock yourself out on a fresh install and you'll find out fast.

What most apps actually want is the model you see everywhere else: 2FA is off by default, and each user opts in from their own account settings. This post shows how to get there with a surprisingly small change — one overridden method — plus a self-service enrolment screen and one QR-code gotcha that will bite you on modern dependencies.

The one insight: `isRequired()`

CakeDC/Users decides whether to demand the OTP step through an
OneTimePasswordAuthenticationCheckerInterface. The default implementation,
DefaultOneTimePasswordAuthenticationChecker, answers "is 2FA required for this
request?" — and once the authenticator is enabled in the login flow, it answers
yes for everybody.

That checker is a swappable dependency. So "per-user 2FA" reduces to: keep the
default behaviour, but also require that this specific user has opted in. One
method:

<?php
declare(strict_types=1);

namespace App\Authentication;

use CakeDC\Auth\Authentication\DefaultOneTimePasswordAuthenticationChecker;

class PerUserOneTimePasswordAuthenticationChecker extends DefaultOneTimePasswordAuthenticationChecker
{
    /**
     * @param array<mixed>|null $user User data.
     */
    public function isRequired(?array $user = null): bool
    {
        // Default rules AND the user enrolled.
        return parent::isRequired($user) && !empty($user['two_steps']);
    }
}

parent::isRequired() keeps every rule CakeDC already applies (the authenticator
is on, the user has a verified secret, remember-me isn't skipping it, …). We just
&& a per-user flag on top. Users who never enrolled fail the two_steps check
and log in normally; users who did get challenged. That's the whole hook.

The `two_steps` flag

CakeDC's own initial migration already gives the users table the columns the TOTP
flow needs — secret (the shared TOTP secret) and secret_verified (proof the
user typed a valid code at least once). The only thing it doesn't have is a column
that means "this user wants 2FA." Add it:

<?php
declare(strict_types=1);

use Migrations\BaseMigration;

class AddTwoStepsToUsers extends BaseMigration
{
    public function up(): void
    {
        $this->table('users')
            ->addColumn('two_steps', 'boolean', ['default' => false, 'null' => false])
            ->update();
    }

    public function down(): void
    {
        $this->table('users')->removeColumn('two_steps')->update();
    }
}

default => false is the important part: existing users are untouched and new
users start with 2FA off. Nobody is forced into anything.

Wiring the checker (and the QR gotcha)

Point the OTP authenticator at your checker in config/users.php. This is also
where you enable the authenticator in the login flow (login => true):

use App\Authentication\PerUserOneTimePasswordAuthenticationChecker;
use RobThree\Auth\Providers\Qr\BaconQrCodeProvider;

$config['OneTimePasswordAuthenticator'] = [
    'checker' => PerUserOneTimePasswordAuthenticationChecker::class,
    'login' => true,
    'issuer' => 'My App', // the label users see in their authenticator app
    'qrcodeprovider' => new BaconQrCodeProvider(format: 'svg'),
];

That last line is the gotcha. CakeDC defaults the QR provider to robthree's
EndroidQrCodeProvider, which calls QrCode::setSize() — a method removed in
endroid/qr-code v6. On a modern install you'll get a fatal the moment you try
to render the enrolment QR. Swap in the BaconQrCodeProvider with format: 'svg':
it's pure PHP (no ext-imagick), and the SVG embeds cleanly as a data: URI, so
the QR drops straight into your template with no file writes. digits, period
and algorithm inherit from CakeDC's defaults.

Self-service enrolment

Now the part that makes it per-user in practice: a screen where a signed-in user
turns 2FA on for themselves, no logout round-trip. The flow is:

GET — make sure a secret exists (unverified), show the QR + the manual key + a 6-digit code field.
POST — verify the typed code against the secret; if it checks out, flip secret_verified and two_steps on and refresh the identity.

public function twoFactor(): ?Response
{
    $userId = $this->getRequest()->getAttribute('identity')?->getIdentifier();
    if ($userId === null) {
        return $this->redirect(['action' => 'login']);
    }

    $table = $this->getUsersTable();
    $user = $table->get($userId);

    if ($user->get('secret_verified') && $user->get('two_steps')) {
        $this->Flash->success(__('Two-factor authentication is already enabled.'));

        return $this->redirect(['action' => 'profile']);
    }

    // Create a secret to display, but keep it unverified until the user proves
    // they can generate a valid code from it.
    $secret = (string)$user->get('secret');
    if ($secret === '') {
        $secret = $this->OneTimePasswordAuthenticator->createSecret();
        $user->set('secret', $secret);
        $user->set('secret_verified', false);
        $user->set('two_steps', false);
        $table->saveOrFail($user);
    }

    if ($this->getRequest()->is(['post', 'put'])) {
        $code = (string)$this->getRequest()->getData('code');
        if ($this->OneTimePasswordAuthenticator->verifyCode($secret, $code)) {
            $user->set('secret_verified', true);
            $user->set('two_steps', true);
            $table->saveOrFail($user);
            $this->Authentication->setIdentity($user); // so this session sees the change
            $this->Flash->success(__('Two-factor authentication is now enabled.'));

            return $this->redirect(['action' => 'profile']);
        }
        $this->Flash->error(__('That code is not valid. Please try again.'));
    }

    $secretDataUri = $this->OneTimePasswordAuthenticator->getQRCodeImageAsDataUri(
        (string)$user->get('email'),
        $secret,
    );
    $this->set(compact('user', 'secret', 'secretDataUri'));

    return null;
}

Two details worth calling out:

The secret is written before it's verified, but two_steps stays false until the code checks out. So a half-finished enrolment never arms the login challenge — the user can't lock themselves out by navigating away.
$this->Authentication->setIdentity($user) after saving refreshes the identity in the current session, so the new flags are live immediately instead of on the next request.

The OneTimePasswordAuthenticator component gives you createSecret(),
verifyCode() and getQRCodeImageAsDataUri() — load it (CakeDC/Auth.OneTimePasswordAuthenticator)
in the controller that hosts this action.

Let users turn it off, too

Opt-in implies opt-out. Clear the secret and both flags, refresh the identity, and
the next login skips the challenge:

public function disableTwoFactor(): ?Response
{
    $this->getRequest()->allowMethod(['post', 'delete']);

    $userId = $this->getRequest()->getAttribute('identity')?->getIdentifier();
    $table = $this->getUsersTable();
    $user = $table->get($userId);
    $user->set('secret', null);
    $user->set('secret_verified', false);
    $user->set('two_steps', false);
    $table->save($user);
    $this->Authentication->setIdentity($user);
    $this->Flash->success(__('Two-factor authentication has been disabled.'));

    return $this->redirect(['action' => 'profile']);
}

Render it as a POST link on the profile so it can't be triggered by a stray GET.

Keep the whole thing behind a switch

Because the wiring adds an authenticator to the login flow, guard it so apps that
don't want 2FA are completely unaffected. A single config flag, read in both
config/users.php (to decide whether to register the authenticator) and the
controller (to 404 the enrolment action when off), keeps it a clean opt-in:

if (Configure::read('MyApp.TwoFactor.enable', false)) {
    $config['OneTimePasswordAuthenticator'] = [ /* …as above… */ ];
}

Recap

Per-user 2FA on CakeDC/Users comes down to four small pieces:

A two_steps boolean on users, defaulting to false.
A checker subclass that &&s that flag onto parent::isRequired().
A self-service enrol/disable pair that flips the flag after verifying a code.
BaconQrCodeProvider(format: 'svg') to dodge the endroid/qr-code v6 breakage.

No forked plugin, no reimplemented TOTP — you keep every rule CakeDC already
enforces and add exactly one: did this user ask for it? That's the difference
between "2FA is on" and "2FA is available," which is almost always what you
actually want.

The Active Flag Trap: unvalidated-but-logged-in in CakeDC/Users

Vinicius — Thu, 20 Aug 2026 21:44:16 +0000

If you ship email validation with CakeDC/Users, you eventually hit a question the plugin quietly hands back to you: what should happen when someone registers, never clicks the validation link, and then tries to log in?

The honest answer is that CakeDC/Users doesn't decide for you. Out of the box you get a database column, a couple of behaviors, and a set of events — but the experience is yours to assemble. Get it wrong and you land in one of two bad places: a user silently logged in without ever validating, or a user who typed the right password and is told "username or password is incorrect." Neither is what you want.

This post walks through why that happens in v16, and a clean way to wire the flow using the events the plugin already dispatches — no core hacks, no schema surgery.

One flag, two meanings

Everything starts with a single boolean column on the users table: active. When email validation is on, registration creates the account with active = 0 and only flips it to 1 when the user clicks the link in the validation email. You can trace it in BaseTokenBehavior::_updateActive():

// $user['validated'] is a transient flag set to false during register()
$emailValidated = $user['validated'];
if (!$emailValidated && $validateEmail) {
    $user['active'] = false;      // registered → inactive + token emailed
    $user->updateToken($tokenExpiration);
} else {
    $user['active'] = true;       // clicked the link → active
    $user['activation_date'] = new DateTime();
}

Notice there is no separate validated column in the database — $user['validated'] is a transient property used only during registration. The persisted truth is active, and it is doing two jobs at once:

"Has this person confirmed their email?" — set by the validation flow.
"Is this account enabled?" — the thing an admin toggles to ban or suspend someone.

That conflation is the root of everything below. Hold onto it; we'll come back to it.

How the finder decides who exists

Login in CakeDC/Users runs through cakephp/authentication's password identifier, which resolves the user with a finder. The finder you choose changes the entire shape of the problem:

finder	Behaviour for an inactive account (`active = 0`)
`'active'`	The `WHERE active = 1` clause means the row is never found. The password is never checked. The user gets the generic "username or password is incorrect" — even with the correct password.
`'all'`	The row is found and the password is verified. With a correct password the identifier succeeds — so an unvalidated user is technically authenticated.

Here's the counter-intuitive part. It's tempting to reach for finder => 'active' — surely inactive users just shouldn't log in? But that choice produces the second bad experience: a real user, with the right password, whose only sin is not clicking an email that probably landed in spam, is told their credentials are wrong. They'll try again, reset their password, and file a support ticket. They have no way of knowing the real problem.

Common myth: "finder => 'all' is there to prevent user enumeration." It isn't. The form login failure maps both "user not found" and "wrong password" to the same generic message anyway (LoginComponentLoader::forForm wires no distinct not-active message). So 'active' leaks nothing — it just also blocks the legitimate not-yet-validated user with a confusing message.

The better flow: authenticate, then decide

The move that fixes both bad outcomes: keep finder => 'all' so the password is verified, then intercept the result after authentication and branch on active. That's the only point where you can tell "wrong password" apart from "correct password, not validated" — and give each a truthful message.

CakeDC/Users hands you the exact hook. LoginComponent::afterIdentifyUser() dispatches Users.Authentication.afterLogin, and if a listener returns an array, that array becomes the redirect, short-circuiting the normal login redirect:

public function afterLogin(EventInterface $event): ?array
{
    $user = $event->getData('user');
    if ($user === null || !empty($user['active'])) {
        return null;                     // active → let normal login proceed
    }

    // Inactive account must never keep a session. The auth middleware
    // already persisted the identity — drop it right back.
    $this->Authentication->logout();
    $this->getRequest()->getSession()->delete('Flash'); // drop the "Welcome" flash

    if (Configure::read('Users.Email.validate')) {
        $this->Flash->error(__(
            'Your account is not validated yet. Click the link in the ' .
            'email we sent you — check spam, or request a new one below.'
        ));

        return ['action' => 'resendTokenValidation'];
    }

    // validation off ⇒ active=0 can only mean an admin disabled the account
    $this->Flash->error(__('Your account is disabled. Please contact an administrator.'));

    return ['action' => 'login'];
}

Two details make this safe. First, the auth middleware has already written the identity to the session by the time your action runs, so simply redirecting isn't enough — you must call $this->Authentication->logout() to drop it. An unvalidated account should never hold a session, not even for one request. Second, LoginComponent queues a "Welcome" success flash before this event fires, so you clear it before setting your own.

Here are the three outcomes at /login:

Credentials	`active`	Result
correct password	`1`	Logged in. Normal redirect to the dashboard.
correct password	`0`	Session dropped. Redirected to the resend page with a specific "validate your account" message.
wrong password / no such user	—	Generic error. "Username or password is incorrect." No session, no enumeration leak.

Why this doesn't leak: the specific "not validated" message only ever appears after a correct password — i.e. to someone who has already proven the account exists. Wrong-password and unknown-user still collapse into one generic message. You get honesty for real users and opacity for attackers.

After register: tell them to check their email

The other half of the problem is that a fresh registrant has no idea a validation email is even coming. By default the plugin flashes "please validate your account before log in" and drops them on the login screen — where the resend option is nowhere in sight. So send them somewhere that explains the next step.

RegisterTrait::_afterRegister() dispatches Users.Global.afterRegister. Careful: unlike the login hook, this one only honours a return value that is a Response instance — an array is ignored. So return a redirect response, not a URL array:

public function afterRegister(EventInterface $event): ?Response
{
    if (!Configure::read('Users.Email.validate')) {
        return null;   // nothing to validate → default "log in" redirect stands
    }

    $this->Flash->success(__(
        'Almost done! We sent a validation link to your email. Click it ' .
        'to activate your account — check spam, or request a new link below.'
    ));

    return $this->redirect(['action' => 'resendTokenValidation']);
}

Both listeners land on the same destination: resendTokenValidation. That action already ships with the plugin (in UserValidationTrait) — it takes an email or username, regenerates the token, and re-sends the validation email, refusing if the account is already active. You just need a themed template for it. Wiring both events is a two-line job in your controller's initialize():

$this->getEventManager()->on(
    UsersPlugin::EVENT_AFTER_LOGIN,
    fn(EventInterface $e) => $this->afterLogin($e),
);
$this->getEventManager()->on(
    UsersPlugin::EVENT_AFTER_REGISTER,
    fn(EventInterface $e) => $this->afterRegister($e),
);

Mind the return contracts: afterLogin must return an array (afterIdentifyUser checks is_array()). afterRegister must return a Response (_afterRegister checks instanceof Response). Same pattern, two different types — mixing them up gives you a listener that silently does nothing.

The caveat you've only postponed

Remember the two jobs active is doing? This flow leans on the "email confirmed" meaning, but the column can't tell that apart from the "admin disabled this account" meaning. Both are active = 0. Which means:

A user an admin deliberately banned can visit the resend page, request a "validation" email, click the link, and re-activate their own account. The resendTokenValidation action only checks that the account isn't already active — it can't know why it's inactive.

The real fix: split the concepts. Add a dedicated enabled column (admin on/off), keep active for email confirmation, and require both in your login finder. Now "never validated" and "banned" are distinct states, and a resend can't undo a ban. Until you do that, only offer resend when email validation is on — and bounce a disabled account (validation off) straight back to login with a neutral message, as the listener above does.

For an existing app, adding a column is a migration and a finder tweak. For a greenfield build it's nearly free — so if you're starting fresh, separate them from day one and skip the trap entirely.

The short version

Keep finder => 'all'. You need the password verified to distinguish "wrong password" from "not validated." It costs you no enumeration protection.
Branch after authentication, not before. The Users.Authentication.afterLogin event is where the truthful decision lives.
Always drop the session for an inactive account — the middleware already created it.
Guide the registrant. Redirect after register to a page that explains the email and offers a resend.
Don't trust one flag with two meanings. An enabled column is the difference between "restart validation" and "let a banned user back in."

None of this requires forking the plugin. CakeDC/Users gives you the seams — the events, the finder switch, the built-in resend action. It just leaves the last mile, the part your users actually feel, for you to build.

Built against CakeDC/Users v16 on CakePHP 5. The event names and method signatures referenced here are from that line; earlier majors dispatch similar events under different names. Spot something I got wrong? Drop a comment.

FormValidation is discontinued — here's the TypeScript successor I built

Vinicius — Thu, 18 Jun 2026 22:32:52 +0000

If you've ever worked on a complex form without a framework, there's a good chance you've used or at least heard of FormValidation. It was the go-to solution for plugin-based, framework-agnostic form validation for years.

Then it went silent. No updates, no responses to issues. Just an archived library slowly rotting against modern JavaScript.

I needed a replacement for a project. I couldn't find one that matched the flexibility of the plugin model, so I built Validare — a modern TypeScript rewrite of the same architecture, from scratch.

What Validare is

@validare/core is a form validation library with:

51 built-in validators — from notEmpty and email to iban, creditCard, uuid, vin, and more
17 plugins — UI feedback, accessibility, CSS framework integrations, async flows
TypeScript-first — full type safety, no @types/* packages needed
Zero dependencies — no jQuery, no frameworks, no polyfills
ESM + CJS + UMD — works everywhere

The core idea is the same as FormValidation: a small engine that does nothing on its own, extended entirely through plugins. You add exactly what you need.

Quick start

npm install @validare/core

<form id="myForm" novalidate>
  <input type="email" name="email" />
  <div class="vd-plugins-message-container"></div>
  <button type="submit">Submit</button>
</form>

import { validare, Trigger, Message, SubmitButton } from '@validare/core';

const fv = validare(document.getElementById('myForm'), {
  fields: {
    email: {
      validators: {
        notEmpty: { message: 'Email is required' },
        email:    { message: 'Please enter a valid email address' },
      },
    },
  },
  plugins: {
    trigger:      new Trigger({ event: 'blur' }),
    message:      new Message(),
    submitButton: new SubmitButton(),
  },
});

document.getElementById('myForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  const result = await fv.validate(); // 'Valid' | 'Invalid' | 'NotValidated'
  if (result === 'Valid') {
    // safe to submit
  }
});

That's it. The Trigger plugin wires up DOM events, Message renders error messages, and SubmitButton disables the button during validation.

The plugin model

Plugins are where Validare earns its keep. Each one is a focused, composable unit:

Plugin	What it does
`Trigger`	Validates on DOM events (`blur`, `input`, `change`)
`Message`	Renders error messages in the DOM
`Icon`	Shows ✓ / ✗ icons next to fields
`Bootstrap5`	Applies `is-valid` / `is-invalid` classes
`Tailwind`	Applies configurable Tailwind utility classes
`Aria`	Adds `aria-invalid` and `aria-describedby` automatically
`Sequence`	Stops at the first failing validator per field
`Excluded`	Skips disabled or hidden fields
`Declarative`	Configures validators via `data-vd-*` HTML attributes
`PasswordStrength`	Scores password strength (0–4)
`CharCounter`	Live character counter with overflow state
`Summary`	Renders a consolidated error list in a container
`Transformer`	Normalises field values before validation (trim, strip, etc.)

You compose only what your project needs:

plugins: {
  trigger:   new Trigger({ event: 'input' }),
  message:   new Message(),
  ui:        new Bootstrap5(),
  aria:      new Aria(),
  sequence:  new Sequence(),
  excluded:  new Excluded(),
}

51 validators, organized by category

Core (23): notEmpty, blank, email, creditCard, date, digits, integer, numeric, regexp, uri, identical, different, between, greaterThan, lessThan, stringLength, stringCase, choice, file, callback, promise, remote, ip

Format & Encoding: base64, hex, mac, bic, uuid, color

Financial: iban, vat, cusip, isin, sedol, grid

Publication: ean, isbn, ismn, issn

Device & Vehicle: imei, imo, meid, step, vin

Tax & Business: ein, rtn, siren, siret

Identity & Geographic: id, phone, zipCode

Async validation and remote checks

The remote validator hits an endpoint and expects { valid: boolean }:

username: {
  validators: {
    notEmpty: { message: 'Username is required' },
    remote: {
      url: '/api/check-username',
      method: 'POST',
      message: 'This username is already taken',
    },
  },
},

Or write your own async validator with callback or promise:

validators: {
  callback: {
    message: 'Invalid value',
    callback: async ({ value }) => {
      const res = await fetch(`/api/validate?q=${value}`);
      const { valid } = await res.json();
      return { valid };
    },
  },
},

Writing a custom validator

Every validator is a zero-argument factory:

import type { ValidatorFactory } from '@validare/core';

export const noSpaces: ValidatorFactory = () => ({
  validate({ value }) {
    return { valid: !value.includes(' '), message: 'No spaces allowed' };
  },
});

Use it directly in your config — no registration needed:

import { noSpaces } from './validators/noSpaces';

fields: {
  username: {
    validators: {
      notEmpty: { message: 'Required' },
      noSpaces: noSpaces,
    },
  },
},

Coming from FormValidation?

The architecture is intentionally familiar. The main differences:

Package name: @validare/core (not @form-validation/cjs)
CSS classes: vd-plugins-* instead of fv-plugins-*
HTML attributes (Declarative plugin): data-vd-* instead of data-fv-*
Native TypeScript — no extra type packages

A full migration guide is available in MIGRATING.md.

Try it

npm: npm install @validare/core
Docs: validare.js.org
GitHub: github.com/validarejs/validare
CDN: https://unpkg.com/@validare/core/dist/index.umd.js

Feedback, issues, and PRs are very welcome. This is an active project and I'm happy to prioritize validators or plugins based on what people actually need.