Acgranter Symfony Hasher Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acgranter/acgranter-symfony-hasher
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Acgranter\SymfonyHasher\SymfonyHasherServiceProvider::class,
   ],
   

2. Basic Usage Register the hasher in your AuthServiceProvider (or equivalent):

   use Acgranter\SymfonyHasher\Hasher;
   
   public function boot()
   {
       $this->app->bind(Hasher::class, function ($app) {
           return new Hasher($app['hashing']);
       });
   }
   

3. First Use Case Hash a password (e.g., in a registration controller):

   use Acgranter\SymfonyHasher\Hasher;
   
   public function register(Request $request, Hasher $hasher)
   {
       $hashed = $hasher->hash($request->input('password'));
       // Store $hashed in DB
   }
   

Key Files to Review

• Service Provider: SymfonyHasherServiceProvider.php (configures Symfony’s PasswordHasherInterface).
• Hasher Class: Hasher.php (wrapper for Symfony’s hashing logic).
• Config: Check for customizable defaults (e.g., config/acgranter.php if published).

Implementation Patterns

Workflows

1. Password Hashing/Verification

   // Hashing
   $hashed = $hasher->hash('plain_password');
   
   // Verification (e.g., in login logic)
   if ($hasher->verify('plain_password', $stored_hash)) {
       // Authenticate user
   }
   

2. Integration with Laravel Auth Extend Laravel’s Authenticatable trait or use middleware:

   use Acgranter\SymfonyHasher\Hasher;
   
   public function validateLogin(Request $request, Hasher $hasher)
   {
       $user = User::where('email', $request->email)->first();
       return $hasher->verify($request->password, $user->password);
   }
   

3. Custom Algorithms Configure Symfony’s PasswordHasher to use specific algorithms (e.g., auto, bcrypt, argon2i):

   $hasher = new Hasher($app['hashing'], 'argon2i');
   

Integration Tips

• Migrations: Use password column with string type (adjust length based on algorithm, e.g., 255 for Argon2).
• Testing: Mock Hasher in unit tests:

  $mockHasher = Mockery::mock(Hasher::class);
  $mockHasher->shouldReceive('verify')->andReturn(true);
  

• Legacy Systems: For upgrading from Laravel’s default hasher, replace:

  // Old
  Hash::make('password');
  
  // New
  $hasher->hash('password');
  

Gotchas and Tips

Pitfalls

1. Algorithm Mismatch

   • Issue: Hashing with argon2i but verifying with bcrypt fails silently.
   • Fix: Ensure consistent algorithm usage or rely on Symfony’s auto mode (detects algorithm from hash).

2. Memory/CPU Limits

   • Issue: Argon2 may fail on low-resource environments (e.g., shared hosting).
   • Fix: Configure memory cost in config/acgranter.php (if published):

     'argon2' => [
         'memory_cost' => 65536, // 64MB
     ],
     

3. Deprecation Warnings

   • Issue: Symfony’s PasswordHasher may log deprecations for older algorithms (e.g., sha256).
   • Fix: Use auto or explicitly enable modern algorithms (bcrypt, argon2i).

Debugging

• Verify Hash Format:

  $hasher->needsRehash($stored_hash, 'plain_password');
  // Returns true if the hash needs rehashing (e.g., algorithm upgrade).
  

• Log Hashing Errors: Wrap hashing in a try-catch to log Symfony-specific exceptions (e.g., InvalidArgumentException).

Extension Points

1. Custom Hashers Implement Symfony\Component\PasswordHasher\PasswordHasherInterface and bind it:

   $this->app->bind(Hasher::class, function ($app) {
       return new CustomHasher($app['hashing']);
   });
   

2. Event Listeners Trigger events for hash upgrades (e.g., after algorithm changes):

   event(new HashUpgradeRequired($user, $newHash));
   

3. Configuration Publish the config for customization:

   php artisan vendor:publish --provider="Acgranter\SymfonyHasher\SymfonyHasherServiceProvider"