## Getting Started

### Minimal Setup in Laravel
1. **Install the package** (if not already included via Symfony/Laravel):
   ```bash
   composer require symfony/password-hasher:^8.1.0-BETA3

Note: Laravel 8+ includes this as a dependency; ensure you’re on ^8.1.0-BETA3 or later for new features.

Configure algorithms in config/password-hasher.php (or create it):

return [
    'default' => 'bcrypt',
    'algorithms' => [
        'bcrypt' => ['cost' => 12],
        'argon2id' => [
            'memory_cost' => 65536,
            'time_cost' => 4,
            'threads' => 2,
        ],
        'sodium' => [],
    ],
];

First use case: Interactive password hashing Use the new security:hash-password Artisan command (via Symfony CLI integration):
```
php artisan security:hash-password
```
- Supports stdin input (pipe passwords directly):
```
echo "my_secure_password" | php artisan security:hash-password
```
- Outputs hashed password to stdout (useful for scripts).

First use case: Replace Laravel’s Hash facade

use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactory;

// In AppServiceProvider
$this->app->singleton(UserPasswordHasherInterface::class, function ($app) {
    $factory = new PasswordHasherFactory($app['config']['password-hasher.algorithms']);
    return new UserPasswordHasherInterface($factory, $app['config']['password-hasher.default']);
});

Implementation Patterns

Core Workflows

1. Algorithm-Specific Hashing

Use case: Dynamic algorithm selection per user role.

$factory = new PasswordHasherFactory(config('password-hasher.algorithms'));
$hasher = $factory->getPasswordHasher('argon2id'); // Explicit selection
$hash = $hasher->hashPassword($user, $plainPassword);

2. Legacy Hash Migration

Use case: Auto-detect and rehash old passwords during login.

public function login(Request $request, UserPasswordHasherInterface $hasher) {
    $user = User::where('email', $request->email)->first();
    if ($user && $hasher->isPasswordValid($user, $request->password)) {
        // Rehash on login (optional)
        $user->password = $hasher->hashPassword($user, $user->password);
        $user->save();
    }
}

3. Bulk Hashing with CLI

Use case: Rehash all users via Artisan command.

php artisan tinker
>>> $factory = new \Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactory(config('password-hasher.algorithms'));
>>> $hasher = $factory->getPasswordHasher('default');
>>> User::chunk(100, function ($users) use ($hasher) {
...     $users->each(function ($user) use ($hasher) {
...         $user->password = $hasher->hashPassword($user, $user->password);
...     });
...     $users->save();
... });

4. Interactive Hashing in Tinker

Use case: Test hashing interactively.

php artisan tinker
>>> $hasher = app(\Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface::class);
>>> $hash = $hasher->hashPassword((object) [], readline("Enter password: "));

Laravel-Specific Patterns

1. Replacing Laravel’s `Hash` Facade

Extend Laravel’s Hash facade to use Symfony’s UserPasswordHasherInterface:

// app/Providers/AppServiceProvider.php
public function register() {
    $this->app->bind(\Illuminate\Contracts\Hashing\Hasher::class, function ($app) {
        $factory = new PasswordHasherFactory($app['config']['password-hasher.algorithms']);
        return new class($factory, $app['config']['password-hasher.default']) implements \Illuminate\Contracts\Hashing\Hasher {
            public function make($value, array $options = []) {
                return $this->hasher->hashPassword((object) [], $value, $options);
            }
            // Delegate other methods...
        };
    });
}

2. Algorithm Rotation

Use case: Deprecate bcrypt in favor of Argon2id.

public function hashPassword(User $user, string $plain) {
    $algorithm = $user->isAdmin() ? 'argon2id' : 'bcrypt';
    $hasher = $this->passwordHasherFactory->getPasswordHasher($algorithm);
    return $hasher->hashPassword($user, $plain);
}

3. Testing with Stdin

Unit tests: Simulate stdin input for security:hash-password.

public function test_stdin_hashing() {
    $command = new \Symfony\Component\PasswordHasher\Command\HashPasswordCommand();
    $input = new \Symfony\Component\Console\Tester\CommandTester($command);
    $input->setInput('my_password');
    $input->execute([]);
    $this->assertStringStartsWith('$2y$', $input->getDisplay());
}

4. Performance Optimization

Benchmark algorithms with the new CLI tool:

# Compare bcrypt vs. argon2id
hyperfine --warmup 3 'php artisan security:hash-password --algorithm=bcrypt'
hyperfine --warmup 3 'php artisan security:hash-password --algorithm=argon2id'

Gotchas and Tips

Pitfalls

1. Stdin Input Quirks

Issue: security:hash-password may hang if stdin is not properly piped (e.g., in some IDEs).

Fix: Use --interactive flag for manual input:

php artisan security:hash-password --interactive

CI/CD: Avoid stdin in automated pipelines; use --password option:
```
php artisan security:hash-password --password="my_secret"
```

2. Algorithm Mismatch Errors

Issue: getPasswordHasherFromHash() fails on unsupported algorithms (e.g., SHA-1).

Fix: Implement a fallback:

try {
    $hasher = $factory->getPasswordHasherFromHash($hash);
} catch (\Symfony\Component\PasswordHasher\Exception\UnsupportedAlgorithmException) {
    $hasher = $factory->getPasswordHasher('bcrypt');
    Log::warning("Legacy hash detected for user ID {$user->id}");
}

3. Argon2id/Sodium Blocking

Issue: High CPU usage under load.
Fix:
- Reduce memory_cost/time_cost temporarily during migration.
- Offload to queues:
```
Queue::push(new RehashUserPassword($userId, $plainPassword));
```

4. Laravel Cache Key Collisions

Issue: Caching hashed passwords may cause race conditions.

Fix: Use unique cache keys with user context:

cache()->put("user:{$user->id}:password_hash", $hash, now()->addDays(30));

Tips

1. New CLI Features

Hash from file: Pipe a file containing passwords:

cat passwords.txt | xargs -I {} php artisan security:hash-password --password="{}"

Algorithm selection: Specify algorithm directly:

php artisan security:hash-password --algorithm=argon2id

2. Security Best Practices

Never log plain passwords: Use readline() or --interactive for manual input.
Rotate algorithms gradually: Monitor performance with hyperfine before full migration.

3. Extension Points

Custom hashers: Implement PasswordHasherInterface for proprietary algorithms.

Pre-hashing: Add metadata to hashes via options:

$hash = $hasher->hashPassword($user, $plain, [
    'user_id' => $user->id,
    'timestamp' => now()->timestamp,
]);

4. Debugging

Verify hash compatibility:

$hasher = $factory->getPasswordHasherFromHash($hash);

Password Hasher Laravel Package