README

Perfect Authentication

A lightweight, standalone PHP authentication library focused on secure password hashing and verification. Zero dependencies, 100% test coverage, and PHP 8.1+ compatible.

Features

🔐 Secure Password Hashing using PHP's built-in password_hash() functions
✅ 100% Test Coverage with PHPUnit 12
📊 PHPStan Level 10 - Maximum static analysis quality
🚀 Zero Dependencies - Pure PHP implementation
🎯 PHP 8.3+ with strict types and modern features
🔧 Flexible Algorithm Support (BCRYPT, ARGON2I, ARGON2ID)
🛡️ Exception-Based Error Handling for robust security
📦 PSR-4 Compliant

Installation

  composer require krubio/perfect-authentication

Requirements

PHP 8.3 or higher
PHP password hashing functions (enabled by default)

Quick Start

Basic Password Operations

<?php

require 'vendor/autoload.php';

use PerfectApp\Auth\PasswordHasher;
use PerfectApp\Auth\AuthenticationService;

// Initialize services
$passwordHasher = new PasswordHasher();
$authService = new AuthenticationService($passwordHasher);

// Hash a password
$hashedPassword = $authService->hashPassword('securepassword123');

// Verify credentials
if ($authService->verifyCredentials('securepassword123', $hashedPassword)) {
    echo "Authentication successful!";
}

// Check if rehashing needed
if ($authService->needsRehash($hashedPassword)) {
    $newHash = $authService->hashPassword('securepassword123');
}

Database Integration

<?php

use PerfectApp\Auth\AuthenticationService;
use PerfectApp\Auth\PasswordHasher;
use PDO;

// Setup
$pdo = new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');
$authService = new AuthenticationService(new PasswordHasher());

// User registration
function registerUser($pdo, $authService, $username, $password) {
    
    $hash = $authService->hashPassword($password);
    $stmt = $pdo->prepare('INSERT INTO users (username, password_hash) VALUES (?, ?)');
    return $stmt->execute([$username, $hash]);
}

// User login
function loginUser($pdo, $authService, $username, $password) {
    
    $stmt = $pdo->prepare('SELECT password_hash FROM users WHERE username = ?');
    $stmt->execute([$username]);
    $user = $stmt->fetch();
    
    return $user && $authService->verifyCredentials($password, $user['password_hash']);
}

API Reference

PasswordHasher

$hasher = new PasswordHasher(string $algorithm = PASSWORD_DEFAULT);

// Methods
$hasher->hash(string $password): string;
$hasher->verify(string $password, string $hash): bool;
$hasher->needsRehash(string $hash): bool;

AuthenticationService

$authService = new AuthenticationService(PasswordHasherInterface $passwordHasher);

// Methods
$authService->verifyCredentials(string $password, string $hashedPassword): void;
$authService->hashPassword(string $password): string;
$authService->needsRehash(string $hash): bool;

Supported Algorithms

PASSWORD_DEFAULT (Recommended)
PASSWORD_BCRYPT
PASSWORD_ARGON2I
PASSWORD_ARGON2ID

Error Handling

<?php

use PerfectApp\Auth\Exceptions\InvalidCredentialsException;

try {
    $authService->verifyCredentials('wrongpassword', $hashedPassword);
} catch (InvalidCredentialsException $e) {
    echo "Authentication failed: " . $e->getMessage();
    // HTTP 401: Unauthorized
}
?>

<?php

use PerfectApp\Auth\Exceptions\InvalidCredentialsException;

try {
    $authService->verifyCredentials('wrongpassword', $hashedPassword);
} catch (InvalidCredentialsException $e) {
    echo "Authentication failed: " . $e->getMessage();
    // HTTP 401: Unauthorized
}

Testing

Run tests with coverage

  composer test

Generate HTML coverage report

  composer test-coverage

Security Best Practices

Always use the latest algorithm (PASSWORD_DEFAULT)
Let passwords be rehashed automatically when algorithms improve
Never store plain text passwords
Use proper error handling with exceptions
Validate input before hashing

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/new-feature
Add tests for your changes
Ensure all tests pass: composer test
Submit a pull request

License

MIT License. See LICENSE file for details.

Support

Create an issue on GitHub
Ensure you include PHP version and error details
Provide reproducible test cases

Changelog

v0.1.0

Initial release
Complete test coverage
Zero dependencies
PHP 8.3+ support

Perfect Authentication - Simple, secure authentication for modern PHP applications.

krubio / perfect-authentication

Maintainers

Details