Hashing Laravel Package

Getting Started

Start by installing the package via Composer: composer require illuminate/hashing. In a Laravel app, it's already included by default—no extra setup needed. Begin by using the Hash facade or the HasherInterface to hash or verify passwords:

use Illuminate\Support\Facades\Hash;

$hashed = Hash::make('password123');
$isValid = Hash::check('password123', $hashed);

The default driver is bcrypt, but argon and argon2id are also supported out of the box.

Implementation Patterns

• Password Management: Always use Hash::make() for storing passwords and Hash::check() for verification—never store plain-text passwords.
• Configuration-Driven Drivers: Adjust hashing behavior in config/hashing.php (or .env), e.g., HASH_DRIVER=argon2id, or customize bcrypt cost/argon memory/threads.
• Rehashing on Login: Leverage Hash::needsRehash($hashed) to detect outdated hashes and rehash silently during authentication:

  if (Hash::check($password, $user->password) && Hash::needsRehash($user->password)) {
      $user->password = Hash::make($password);
      $user->save();
  }
  

• Dependency Injection: For testability or non-Laravel apps, inject Illuminate\Contract\Hashing\Hasher into services instead of using the facade.
• Testing: Mock HasherInterface to avoid hashing during unit tests:

  $this->mock(Hasher::class)->shouldReceive('make')->andReturn('mocked_hash');
  

Gotchas and Tips

• No Direct Comparison: Never use === to compare hashes—always use Hash::check(); even identical passwords produce different hashes due to salting.
• Driver Compatibility: argon2id requires PHP ≥7.3 and may fail silently or throw ValueError on older PHP versions—always wrap Hash::make() in try/catch or check password_algos() first.
• Performance Trade-offs: Increase bcrypt cost for security, but it exponentially increases compute time; test with production-like loads. Argon is memory-hard—ensure your server has sufficient RAM.
• Custom Drivers: Extend with Hash::extend('custom', fn() => new MyHasher()) before any hashing occurs (e.g., in a service provider), but note this package is frozen—prefer upgrading to full Laravel if deep customization is needed.
• Laravel Integration: If using outside Laravel (e.g., standalone PHP), bootstrap with a Container and register the hashing service manually; otherwise, use Laravel’s full stack for seamless integration.