Phpass Laravel Package

Getting Started

Minimal Setup

1. Installation: Add to composer.json:

   "require": {
       "bordoni/phpass": "^0.3.6"
   }
   

   Run composer install or composer update.

2. Autoloading: Ensure vendor/autoload.php is included (Laravel handles this via composer.json autoloading).

3. First Use Case: Hash and verify a password in a Laravel controller or service:

   use Hautelook\Phpass\PasswordHash;
   
   $hasher = new PasswordHash(8, false); // 8 = cost factor (1-31), false = portable hashes
   $hash = $hasher->HashPassword('user_input_password');
   

Implementation Patterns

Core Workflows

1. Password Hashing:

   • Use in User model registration or password reset logic:

     public function setPasswordAttribute($password) {
         $this->attributes['password'] = app(PasswordHash::class)->HashPassword($password);
     }
     

   • Store only the hash in the database (e.g., users.password column).

2. Password Verification:

   • Integrate with Laravel’s auth system (e.g., AuthenticatesUsers trait):

     public function validateCredentials($request) {
         $hasher = app(PasswordHash::class);
         return $hasher->CheckPassword(
             $request->password,
             $this->password
         );
     }
     

3. Service Container Binding (Laravel): Bind the hasher in AppServiceProvider for dependency injection:

   public function register() {
       $this->app->singleton(PasswordHash::class, function () {
           return new PasswordHash(config('hash.cost'), config('hash.portable'));
       });
   }
   

Integration Tips

• Configuration: Define cost factor and portability in config/hash.php:

  return [
      'cost' => 10, // Higher = more secure but slower
      'portable' => false, // Set true for cross-language compatibility
  ];
  

• Migrations: Update users table to store hashes (e.g., password column as varchar(255)).

• Testing: Mock PasswordHash in unit tests:

  $hasher = $this->createMock(PasswordHash::class);
  $hasher->method('CheckPassword')->willReturn(true);
  

Gotchas and Tips

Pitfalls

1. Cost Factor:

   • Default cost (8) may be too low for modern security. Use 10+ for production.
   • Changing cost requires rehashing all passwords (use Laravel’s Hash::needsRehash() pattern).

2. Portability:

   • Set portable: true only if hashes must work outside PHP (e.g., Python). Reduces security slightly.

3. PHP 8.1+:

   • Use ^0.3.6 to avoid intval deprecation warnings (fixed in #5).

4. Database Storage:

   • Hashes are ~60 chars long. Use varchar(255) to avoid truncation.

Debugging

• Hash Mismatches: Verify the exact hash string (whitespace/case-sensitive) when comparing.

  // Debug helper
  dd($hasher->CheckPassword('input', $storedHash)); // Returns bool
  

• Performance: High cost factors slow down hashing. Benchmark with php -r 'hash("sha256", str_repeat("a", 60));' for reference.

Extension Points

1. Custom Hashing Logic: Extend PasswordHash to add pre/post-processing:

   class CustomPasswordHash extends PasswordHash {
       public function HashPassword($password) {
           $password = strtolower($password); // Force lowercase
           return parent::HashPassword($password);
       }
   }
   

2. Laravel Hash Facade: Create a facade for consistency with Laravel’s Hash facade:

   // app/Providers/AppServiceProvider.php
   use Illuminate\Support\Facades\Facade;
   
   Facade::register('Phpass', function () {
       return app(PasswordHash::class);
   });
   

   Usage:

   $hash = Phpass::HashPassword('secret');
   

3. Password Policies: Combine with Laravel’s Password validator for complexity rules:

   $request->validate([
       'password' => 'required|min:8|confirmed|string',
   ]);