Version 6.0 - Major Architecture Refactoring and Enhanced Documentation

[byjg]

This major release introduces significant architectural improvements to the PHP AuthUser library, transitioning from closure-based field mapping to a more robust MapperFunctionInterface system. The release also includes
comprehensive Docusaurus documentation, password validation features, and updated dependencies.

🎯 Major Changes

1. Mapper System Refactoring

• Migrated from closure-based field mapping to MapperFunctionInterface for better extensibility and type safety
• Introduced new mapper classes:
  • PasswordSha1Mapper - SHA-1 password hashing (with deprecation notice)
  • UserIdGeneratorMapper - Custom user ID generation
  • ClosureMapper - Backward compatibility wrapper for legacy closures
• Added entity processors:
  • PassThroughEntityProcessor - No-op processor
  • ClosureEntityProcessor - Closure-based entity processing

2. Password Validation System

• New PasswordDefinition class with configurable password policies:
  • Minimum character requirements
  • Uppercase/lowercase/symbol/number requirements
  • Whitespace, sequential, and repeated character controls
  • Automatic password generation based on rules

3. Database Layer Improvements

• UsersDBDataset constructor now accepts DatabaseExecutor or DbDriverInterface
• Automatic conversion from DbDriverInterface to DatabaseExecutor for backward compatibility
• Enhanced type safety with strict typing throughout

4. JWT Authentication Prioritization

• Documentation now recommends JWT tokens over session-based authentication
• SessionContext marked as deprecated (legacy support maintained)
• Updated authentication flow examples to favor JWT

5. Comprehensive Documentation

• Complete Docusaurus documentation site with 11 new documentation files:
  • Getting Started & Installation guides
  • Authentication patterns (JWT & session-based)
  • User Management & Properties
  • Custom Fields & Mappers
  • Password Validation
  • Database Storage
  • Comprehensive examples
• README refactored to focus on quick start with links to detailed docs

6. Dependency Updates

• Updated to PHP 8.1-8.4 (previously 8.1-8.3)
• Updated core dependencies to version 6.0:
  • byjg/micro-orm: ^6.0
  • byjg/cache-engine: ^6.0
  • byjg/jwt-wrapper: ^6.0
• Updated dev dependencies (PHPUnit ^11, Psalm ^6.13)

⚠️ Breaking Changes

Change	Impact	Migration Path
UserDefinition::defineClosureForUpdate() → defineMapperForUpdate()	Method signature changed from Closure to MapperFunctionInterface|string	Replace closure with mapper class:
$def->defineMapperForUpdate('field', new ClosureMapper($closure)) or use mapper class names
UserDefinition::defineClosureForSelect() → defineMapperForSelect()	Method signature changed from Closure to MapperFunctionInterface|string	Same as above - use mapper classes instead of closures
UserDefinition::getClosureForUpdate() → getMapperForUpdate()	Return type changed from Closure to MapperFunctionInterface|string	Update code to work with mapper instances instead of closures
UserDefinition::defineGenerateKeyClosure() removed	Method throws InvalidArgumentException	Use defineGenerateKey(MapperFunctionInterface|string) instead
UserDefinition::existsClosure() → existsMapper()	Method renamed	Update method calls to use new name (old method exists but deprecated)
UserDefinition::beforeInsert / beforeUpdate	Changed from Closure to EntityProcessorInterface	Wrap closures with new ClosureEntityProcessor($closure)
UsersDBDataset constructor parameter order	Constructor type changed: DbDriverInterface → DatabaseExecutor|DbDriverInterface	No immediate breaking change - automatic conversion provided, but update type hints
for future compatibility
Core dependencies updated to ^6.0	byjg/micro-orm, byjg/cache-engine, byjg/jwt-wrapper all require version 6.0	Update all ByJG dependencies to version 6.0
Password hashing default (SHA-1)	Still uses SHA-1 by default but with prominent deprecation warnings	Implement custom password mapper using bcrypt or Argon2 for new projects

✨ New Features

• Password generation - Generate secure passwords that comply with validation rules
• Flexible mapper system - Easy to create custom field mappers for any transformation logic
• Entity processors - Pre-insert/update hooks with proper interfaces
• Enhanced type safety - Full PHP 8.1+ type hints throughout the codebase
• Comprehensive test coverage - New tests for password validation, mappers, and core functionality

📚 Documentation

All documentation is now available in the /docs folder and ready for Docusaurus deployment:

• Complete API documentation with examples
• Migration guides for breaking changes
• Security best practices
• Real-world usage examples

🔄 Backward Compatibility

Legacy methods are maintained with deprecation notices:

• defineClosureForUpdate() - wraps closure in ClosureMapper
• defineClosureForSelect() - wraps closure in ClosureMapper
• getClosureForUpdate() - returns closure wrapper for mappers
• existsClosure() - calls existsMapper() internally
• UsersDBDataset auto-converts DbDriverInterface to DatabaseExecutor

🧪 Testing

• All existing tests updated and passing
• New test suites for:
  • PasswordDefinition validation and generation
  • MD5 password mapper
  • Updated dataset tests with new mapper system

📦 Installation

composer require byjg/authuser:^6.0

🔗 Related PRs

This PR consolidates multiple feature branches and improvements into the 6.0 release.