SessionLoginThrottle

Configuration is managed in the admin at Modules > Configure > SessionLoginThrottle, or programmatically:

$module = $modules->get('SessionLoginThrottle');
$module->set('seconds', 10);
$module->set('maxSeconds', 300);
$module->set('checkIP', true);
$module->set('logFails', true);
$modules->saveModuleConfigData($module, $module->getArray());

Wait time calculation

After N failed attempts, the required wait before the next attempt is:

wait = min((N - 1) × seconds, maxSeconds)

If maxSeconds have elapsed since the last attempt, the counter resets and the next attempt is treated as the first.

Hook into Session

The module hooks Session::allowLoginAttempt in its init() method. This hook fires before a user object is loaded — the module only needs the login name, not the user.

// In SessionLoginThrottle::init():
$this->wire()->session->addHookAfter(
    'allowLoginAttempt',
    $this,
    'hookSessionAllowLoginAttempt'
);

The hook checks whether the login name (and optionally IP) has exceeded the allowed attempt frequency. If another module has already disallowed the login, this module does nothing (it only acts when $event->return is true).

Database table

On install, the module creates the session_login_throttle table:

Expired rows (last_attempt older than maxSeconds) are deleted on each check.

Error behavior

When a login is blocked:

• In the admin login (ProcessLogin): An error notice is shown to the user.
• In other contexts (API usage): A SessionLoginThrottleException is thrown to ensure the error cannot be missed.

Request caching

The allowLogin() method caches results per name for the lifetime of the request. This prevents multiple hook invocations from double-counting an attempt within a single request.

SessionLoginThrottle does not expose its own hookable methods. It works by hooking into Session:

If you need custom throttling logic, hook Session::allowLoginAttempt yourself. SessionLoginThrottle respects the existing return value — if another module has already set it to false, this module does nothing.

// Custom IP blocklist, runs before SessionLoginThrottle
$wire->addHookBefore('Session::allowLoginAttempt', function(HookEvent $event) {
    $name = $event->arguments(0);
    $ip = $event->wire()->session->getIP();
    $blocked = ['10.0.0.1', '192.168.1.100'];
    if(in_array($ip, $blocked)) {
        $event->return = false;
    }
});

A custom exception thrown when a non-ProcessLogin context triggers a throttle block.

try {
    $session->login('username', 'password');
} catch(SessionLoginThrottleException $e) {
    // Login blocked by throttle
    echo $e->getMessage();
}

This exception extends WireException.

• The module does not run when $config->demo is enabled (prevents interference with the demo site).
• The module is singular: true — no more than one instance can be loaded.
• autoload is conditional: the module only loads when $_POST is not empty (a form submission is in progress).
• The database table is indexed by name (primary key), so lookups are fast even with many tracked usernames.
• Expired entries are cleaned up on every check, so the table stays small.
• IP-based throttling is unreliable on mobile/cellular networks where IPs change frequently. Use it as a secondary signal, not a primary defense.
• See Session for the full authentication API, including login(), logout(), and the complete list of hookable methods.
• Source file: wire/modules/Session/SessionLoginThrottle/SessionLoginThrottle.module