README

Framework-neutral password strength checking for vanilla PHP, with an optional Laravel integration.

$checker = new RonaldPh\StrongPass\PasswordChecker();
$result = $checker->inspect($password);

It judges a password against a standard you select (NIST SP 800-63B, OWASP, PCI DSS, or your own), scores it 0–4, and blocks commonly used passwords. In Laravel, an optional adapter also reads requests, integrates with validation, and redirects weak-password submissions with a useful message.

Requirements

PHP 7.1 or newer (7.x and 8.x)
No framework is required
Optional: Laravel / Illuminate 5.5 through 12.x for the Laravel integration

Installation

composer require ronald-ph/strong-pass

Vanilla PHP

Create a checker and pass it an ordinary string. No Laravel application, container, request object, facade, or global helper is involved:

use RonaldPh\StrongPass\PasswordChecker;

$checker = new PasswordChecker();
$result = $checker->inspect($_POST['password'] ?? '');

if ($result->failed()) {
    echo htmlspecialchars($result->message(), ENT_QUOTES, 'UTF-8');
}

Configuration is an ordinary PHP array merged over the package defaults:

$checker = new PasswordChecker([
    'standard' => 'basic',
    'context' => ['words' => ['your-company-name']],
    'blocklist' => [
        'config' => ['words' => ['project-name']],
    ],
]);

The standalone checker supports the built-in file/config blocklist. Custom drivers can implement Blocklists\Blocklist and be injected with useBlocklist(). Laravel's optional pwned driver remains available through the Laravel integration.

Laravel

The service provider and the StrongPass facade are auto-discovered on Laravel 5.5+.

Publish the config file if you want to change anything:

php artisan vendor:publish --tag=strong-pass-config

Usage

In a controller

use RonaldPh\StrongPass\Facades\StrongPass;

public function register(Request $request)
{
    StrongPass::check($request);

    // Only reached when the password passed.
    $user = User::create($request->all());

    return redirect()->route('dashboard');
}

That is the whole call. check($request) reads the password and its confirmation, and when the password is weak it throws a WeakPasswordException whose render() method sends the user back with the error flashed to the session. On a JSON request it returns a 422 instead.

The message is the password's own — the first rule it broke, such as The password must be at least 15 characters long., or the breach notice when it was found on a blocklist. It is flashed under error by default, which @error('error') in Blade picks up; change the key with strong-pass.flash_key.

The password and its confirmation are stripped from the flashed input, so a weak password is never written back into the form in plain text.

check() returns the PasswordResult, so you can still look at it after the fact:

$result = StrongPass::check($request);   // only returns if it passed
$result->score;

A form with no confirmation field

A confirmation field that is absent is skipped rather than treated as a mismatch, so a form that asks for the password once works as it is:

StrongPass::check($request);   // password only, no password_confirmation

But a strength check belongs on registration and password change, not on login. Rejecting a login because the password is weak locks out existing users whose passwords predate your policy — they cannot get in to change it. At login, verify the credentials as usual; if you want to check for breaches there, let the user in and prompt them to reset rather than refusing the login.

Validating rather than redirecting

If you prefer Laravel's validation, use the rule:

$request->validate([
    'email'    => ['required', 'email'],
    'password' => ['required', 'confirmed', new StrongPasswordRule],
]);

Checking a password directly

$result = StrongPass::inspect('correct horse battery staple');

$result->passed();       // bool
$result->score;          // 0-4
$result->entropy;        // estimated bits
$result->feedback;       // array of suggestions
$result->blockedBy;      // 'config', 'pwned', or null
$result->standard;       // which standard judged it

Configuration

The standard key selects the ruleset. Five are included:

Standard	Min length	Character classes	Blocklist	Min score
`nist`	15	not required	yes	1
`nist_mfa`	8	not required	yes	1
`owasp`	12	not required	yes	2
`pci`	12	letters and numbers	no	2
`basic` (default)	8	lower, upper, digit, symbol	yes	2
`custom`	your call	your call	your call	your call

basic is the default and requires at least eight characters with lower-case, upper-case, numeric, and symbol characters. For standards-based policies, NIST SP 800-63B Revision 4 requires 15 characters when the password is the sole authentication factor and 8 when it is one factor among several; select nist or nist_mfa explicitly for those policies.

NIST deliberately forbids character-class rules, which is why nist, nist_mfa and owasp do not require a symbol. If you want the older "must contain a symbol" behaviour, use basic. PCI DSS v4.0 (§8.3.6) asks for 12 characters containing both letters and numbers — not a symbol — which is what pci enforces.

composition accepts false, true (or 'all') for lower + upper + digit + symbol, or 'letters_numbers'. An unrecognised value is an error rather than a silent "no rules", so a typo cannot quietly weaken the policy.

Any key can be overridden at runtime, which is what makes per-tenant rulesets possible:

config()->set('strong-pass.standard', 'pci');

Field names

If your form does not use password / password_confirmation:

'fields' => [
    'password'     => 'new_password',
    'confirmation' => 'new_password_confirmation',
],

Blocking weak passwords

Two drivers ship, and they can be chained — the first one to match wins, and the match is reported in $result->blockedBy.

config (on by default) checks a bundled starter list plus any words you add. Add words that matter to your application:

'blocklist' => [
    'drivers' => ['config'],
    'config'  => [
        'use_builtin' => true,
        'words'       => ['yourcompany', 'yourdomain'],
    'match'       => 'exact',  // or 'contains'; also catches "Password123!" and "P@ssw0rd"
    ],
],

In contains mode, matching is case-insensitive and recognises common leetspeak substitutions (@/4 as a, 0 as o, $/5 as s, and similar forms). Separators are ignored during this comparison, so a configured word such as Password also rejects P@ssw0rd and P\@ssw0rd. exact mode continues to compare the literal password without this broader normalisation.

The bundled list is deliberately small — around 550 passwords, a starter set rather than a corpus. For real coverage use the pwned driver or download a corpus:

php artisan strong-pass:fetch-blocklist

That writes a SecLists top-10,000 password list to storage/app/strong-pass/blocklist.txt (override with --url and --path). Point the config driver's file key at it to use it.

pwned (off by default) checks HaveIBeenPwned's Pwned Passwords range API. Only the first five characters of the password's SHA-1 hash are ever sent, so neither the password nor its full hash leaves your server. It needs an HTTP client:

composer require guzzlehttp/guzzle

'blocklist' => [
    'drivers' => ['config', 'pwned'],
    'pwned'   => [
        'enabled'   => true,
        'fail_open' => true,   // see below
        'cache_ttl' => 86400,
        'timeout'   => 3,
    ],
],

fail_open defaults to true: if HaveIBeenPwned is unreachable the password is allowed through and a warning is logged. The alternative turns an outage on their end into an outage on yours, which is the worse failure — but set it to false if you would rather reject than admit a breached password while the API is down.

Scoring

Passwords are scored 0–4 from an entropy estimate (charset size × length, in bits) discounted for structure that adds no real entropy: repeated characters, sequences, keyboard runs, trailing years, and words from your context list. The thresholds are roughly 28 / 36 / 60 / 128 bits.

Context words are the personal details a password should not contain — the authenticated user's name and email are included automatically, and you can add your own:

'context' => [
    'use_authenticated_user' => true,
    'words'                  => ['acme', 'springfield'],
],

This scorer is a heuristic, not zxcvbn. It has no dictionary and no l33t-speak table, so it will overrate something like Tr0ub4dor. It is good at catching the obvious failures — aaaaaaaa, 123456, qwertyuiop, Summer2024! — and it is swappable: implement RonaldPh\StrongPass\Scorers\Scorer and point 'scorer' at it if you need more.

License

MIT. See LICENSE.md.

ronald-ph / strong-pass

Package info

Security

Statistics