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";
    }
}

Algorithm	Class	Notes
Bcrypt	`BcryptPasswordHasher`	Adjustable `cost`
Argon2id	`Argon2idPasswordHasher`	Adjustable memory, time, threads


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

Password Rules

Rule	Description
`EmptyPasswordRule`	Password must not be empty
`ContainsUppercaseRule`	Must include at least one uppercase letter
`ContainsLovercaseRule`	Must include at least one lowercase letter
`ContainsDigitRule`	Must include at least one digit
`ContainsSpecialCharRule`	Must include at least one special character
`MinLengthRule`	Minimum length requirement
`MaxLengthRule`	Maximum length requirement
`RegexRule`	Custom pattern validator

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

yggdevsec / passwordservice

Maintainers

Details