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

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

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Add tests for your changes
4. Ensure all tests pass: composer test
5. 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.