Zxcvbn Php Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require bjeavons/zxcvbn-php:^1.4.2
   

2. Basic Usage (Updated for Type Clarity)

   use Zxcvbn\Zxcvbn;
   
   $zxcvbn = new Zxcvbn();
   $result = $zxcvbn->calculate('Tr0ub4dour&3');
   

   • Note: Internal factorial() now explicitly returns float (PR #75), ensuring precision in crackTimes calculations.

3. First Use Case: Password Validation (Unchanged)

   $result = $zxcvbn->calculate($password);
   if ($result->score < 3) {
       return back()->withErrors(['Password too weak']);
   }
   

Where to Look First

• Documentation (updated changelog for 1.4.2).
• src/Zxcvbn.php (verify factorial() type declaration and crackTimes precision).
• tests/ for edge cases (e.g., factorial() with weak passwords like 'a').

Implementation Patterns

1. Real-Time Feedback in Forms (Unchanged)

// Laravel Form Request Validation
public function withValidator($validator) {
    $validator->after(function ($validator) {
        $result = (new Zxcvbn())->calculate($this->password);
        if ($result->score < 3) {
            $validator->errors()->add('password', 'Password is too weak.');
        }
    });
}

2. Password Strength Meter (Frontend Integration) (Unchanged)

• Note: Backend type changes (PR #75) do not affect frontend JS integration.
• Sync with PHP validation as before.

3. Password Policy Enforcement (Unchanged)

$zxcvbn = new Zxcvbn();
$result = $zxcvbn->calculate($password);

if ($result->score < 2) {
    abort(422, 'Password must meet minimum strength requirements.');
}

4. Integration with Laravel Auth (Unchanged)

• Custom Validator (unchanged):

  Validator::extend('zxcvbn', function ($attribute, $value, $parameters) {
      return (new Zxcvbn())->calculate($value)->score >= (int)($parameters[0] ?? 3);
  });
  

5. Password Breach Checks (Updated for Precision)

• New Consideration: Leverage crackTimes with confidence due to fixed factorial() precision.

  $result = $zxcvbn->calculate($password);
  if ($result->crackTimes['offline_slow_hashing_1e4_per_second'] < 1e6) {
      // Password is too weak for offline attacks
  }
  

Gotchas and Tips

Pitfalls

1. Factorial Precision Fix (NEW)

   • Issue: PR #75 ensures factorial() returns float, resolving potential integer overflow in crackTimes.
   • Impact: No breaking change, but improves accuracy for edge cases (e.g., 'a' or '123456').
   • Debugging: Compare crackTimes before/after 1.4.2:

     $result = $zxcvbn->calculate('a');
     logger()->debug('Offline slow hashing (fixed):', $result->crackTimes['offline_slow_hashing_1e4_per_second']);
     

2. Performance on Weak Passwords (Unchanged)

   • Cache results for repeated checks (e.g., form retries).
   • Example:

     $cacheKey = 'zxcvbn:'.$password;
     $result = Cache::remember($cacheKey, now()->addMinutes(5), fn() => $zxcvbn->calculate($password));
     

3. False Positives for Complex but Short Passwords (Unchanged)

   • Combine with strlen() if strict length is required.

4. User Dictionary Overrides (Unchanged)

   • Extend dictionaries dynamically:

     $zxcvbn->addUserDictionary(['AcmeCorp', 'ProjectX']);
     

Debugging

• Inspect Factorial Precision (NEW)
  • Log crackTimes for weak passwords:

    $result = $zxcvbn->calculate('password123');
    logger()->debug('Crack times (float precision):', $result->crackTimes);
    

• Log Matched Patterns (Unchanged)

  $matches = $result->sequence;
  logger()->debug('Matched patterns:', $matches);
  

Extension Points

1. Custom Scoring Logic (Unchanged)

   • Override calculate() or extend the class:

     class CustomZxcvbn extends Zxcvbn {
         public function calculate($password) {
             $result = parent::calculate($password);
             // Adjust score (e.g., penalize sequential chars)
             return $result;
         }
     }
     

2. Plugin System (Unchanged)

   • Add pre/post-processing hooks:

     $zxcvbn->addPlugin(function ($password, $result) {
         if (str_contains($password, '123')) {
             $result->feedback->suggestions[] = 'Avoid sequential numbers';
         }
         return $result;
     });
     

3. Localization (Unchanged)

   • Override feedback messages:

     $zxcvbn->setFeedbackMessages([
         'too_short' => 'Contraseña muy corta',
     ]);
     

Config Quirks

• Dictionary Path (Unchanged)
  • Symlink custom dictionaries to:

    vendor/bjeavons/zxcvbn-php/resources/dictionaries/
    

• Type Declarations (NEW)
  • Note: Internal type hints (e.g., factorial(): float) are now consistent.
  • Impact: No changes required for users, but useful for contributors extending the package.

New Contributor Highlights

• PR #75 by @gjcarrette fixed a type-declaration issue in factorial().
  • Why it matters: Ensures crackTimes calculations use float precision, improving accuracy for edge cases (e.g., very weak passwords).
  • Test it: Compare crackTimes before/after 1.4.2 for passwords like 'a' or '123456'.
  • Example:

    $result = $zxcvbn->calculate('a');
    logger()->debug('Offline slow hashing (1.4.2):', $result->crackTimes['offline_slow_hashing_1e4_per_second']);