README

Support

If you like this project, feel free to support me with a coffee! ☕️

A secure and extensible PHP 8.3+ password validation and hashing library built with Hexagonal Architecture.

Installation

composer require yggdevsec/passwordservice

Features

• ✅ Password hashing using Bcrypt or Argon2id (configurable)
• ✅ Rehash support if cost/algorithm has changed
• ✅ Strict password validation via custom rule system
• ✅ Hexagonal Architecture (decoupled domain, rules, services)
• ✅ Fully tested with PHPUnit and static analysis (Psalm, PHPStan)
• ✅ PSR-4 autoloading

Requirements

• PHP 8.3+
• Composer

Usage Example

use YggDevSec\Security\PasswordService\PasswordService;
use YggDevSec\Security\PasswordService\Hash\BcryptPasswordHasher;
use YggDevSec\Security\PasswordService\Policy\ConfigurablePasswordPolicy;
use YggDevSec\Security\PasswordService\Rules\{
    EmptyPasswordRule,
    ContainsUppercaseRule,
    ContainsLowercaseRule,
    ContainsDigitRule,
    MinLengthRule,
    MaxLengthRule
};

// Setup
$hasher = new BcryptPasswordHasher(cost: 13);
$policy = new ConfigurablePasswordPolicy([
    new EmptyPasswordRule(),
    new ContainsUppercaseRule(),
    new ContainsLowercaseRule(),
    new ContainsDigitRule(),
    new MinLengthRule(8),
    new MaxLengthRule(64)
]);

$service = new PasswordService($hasher, $policy);

// Validate + hash
try {
    $hashed = $service->hash('SecurePass123');
    echo "Password OK: $hashed\n";
} catch (InvalidPasswordException $e) {
    foreach ($e->getErrors() as $error) {
        echo $error->getMessage() . "\n";
    }
}

$hasher = PasswordHasherFactory::create('argon2id', [
    'memory_cost' => 131072,
    'time_cost'   => 4,
    'threads'     => 2
]);

Password Rules

You can also implement your own using PasswordRuleInterface.

Security Considerations

• Always use a secure hashing algorithm (Argon2id recommended).
• Avoid exposing raw error codes directly to end users.
• Do not store plain passwords – use this library to hash & verify securely.

Testing

To check and fix code style

composer cs

To run static analysis:

composer stan
composer psalm

To run the test suite:

./vendor/bin/phpunit --testdox tests

License

This project is licensed under the MIT License.

YggDevSec

Security-focused PHP libraries
https://gitlab.com/users/yggdevsec/projects