feat(browser): Modern PSR-4 conversion with wrapper strategy

[ralflang]

Summary

This PR converts the Horde/Browser library from legacy PSR-0 to modern PSR-4 implementation while maintaining 100% backward compatibility through a wrapper pattern.

Approach

Test-Driven Development

1. First: Created comprehensive test coverage for legacy behavior (25 tests)
2. Then: Implemented modern PSR-4 Browser with improved detection (27 tests)
3. Finally: Converted lib/ to thin wrapper around modern implementation (4 educational tests)

Wrapper Strategy

• Modern implementation in src/ (682 lines) - native behavior
• Legacy wrapper in lib/ (593 lines, 55% reduction from 1,320 lines)
• Wrapper delegates to modern implementation and maps values to legacy format

Key Improvements

1. Browser Detection (Native Values)

Modern API returns distinct browsers:

• Chrome → BrowserFamily::Chrome (not generic 'webkit')
• Safari → BrowserFamily::Safari (not generic 'webkit')
• Edge → BrowserFamily::Edge (not generic 'webkit')
• Firefox → BrowserFamily::Firefox (not generic 'mozilla')

Legacy wrapper maintains BC:

• Maps Chrome/Safari/Edge → 'webkit'
• Maps Firefox → 'mozilla'

2. Platform Detection (Native Values)

Modern API distinguishes mobile platforms:

• iPhone → Platform::IPhone (not generic 'mac')
• iPad → Platform::IPad (not generic 'mac')
• Android → Platform::Android (not generic 'unix')
• macOS → Platform::MacOS

Legacy wrapper maintains BC:

• Maps iPhone/iPad/macOS → 'mac'
• Maps Android/Linux → 'unix'

3. Version Numbers (Native Integers)

Modern API returns integers for proper comparison:

$browser->getMajorVersion(); // 120 (int)
if ($browser->getMajorVersion() >= 120) { ... } // Works!

Legacy wrapper returns strings for BC:

$browser->getMajor(); // '120' (string)

Improvement: Firefox version now correct!

• Legacy returned Mozilla version '5'
• Modern returns actual Firefox version '121'

4. Tablet Detection (Now Works!)

Modern API properly detects tablets:

$browser->tablet(); // true for iPad, Android tablets

Legacy wrapper provides working tablet detection:

$browser->isTablet(); // true for iPad (was false/broken in pure legacy!)

Technical Details

New Files

• src/Browser.php - Modern readonly class with PHP 8.2+ features
• src/BrowserFamily.php - Enum for browser types
• src/Platform.php - Enum for platforms with helper methods
• test/unit/BrowserTest.php - 31 tests for modern implementation
• test/unit/classic/BrowserTest.php - 25 tests for legacy wrapper
• phpunit.xml.dist - PHPUnit 11-13 configuration

Modified Files

• lib/Horde/Browser.php - Converted to 593-line wrapper (55% reduction)
• composer.json - PHP 8.2+, PSR-4 autoloading, PHPUnit dependency

Documentation

• Extensive class-level documentation explaining native vs legacy differences
• Method-level documentation showing value mapping
• Educational test methods demonstrating improvements

Test Coverage

56 tests, 194 assertions - all passing

PHPUnit 11.5.3

Browser Classic (Horde_Browser)             25 / 25 (100%)
Browser Modern (Horde\Browser\Browser)      31 / 31 (100%)

OK (56 tests, 194 assertions)

Test Suites

1. Classic (test/unit/classic/) - Tests legacy wrapper with BC values
2. Modern (test/unit/) - Tests native implementation with modern values

Commits

1. test(browser): add PHPUnit test coverage for legacy Browser class
2. feat(browser): implement Modern PSR-4 Browser with improved detection
3. refactor(browser): convert lib/ to wrapper around modern implementation
4. docs(browser): extensively document native vs legacy value differences
5. test(browser): add tests demonstrating native vs legacy value differences

Migration Path

Using Legacy API (No Changes Required)

$browser = new Horde_Browser();
$browser->getBrowser();    // 'webkit' (legacy value)
$browser->getMajor();      // '120' (string)
$browser->getPlatform();   // 'mac' (legacy value)
$browser->isTablet();      // true (now works for iPad!)

Using Modern API (Recommended)

$browser = new \Horde\Browser\Browser();
$browser->getBrowser();       // BrowserFamily::Chrome (native enum)
$browser->getBrowserName();   // 'chrome' (native string)
$browser->getMajorVersion();  // 120 (int for comparison)
$browser->getPlatform();      // Platform::IPhone (native enum)
$browser->tablet();           // true (properly detected)

Backward Compatibility

✅ 100% backward compatible

• All legacy methods preserved with exact signatures
• Legacy values maintained (with improvements underneath)
• Manual overrides (setBrowser, setMobile, setTablet) still work
• Custom features and quirks supported

Breaking Changes: None

Benefits

1. Reduced Code Complexity: 55% reduction in lib/ (1,320 → 593 lines)
2. Improved Detection: iPad/Android tablets now properly detected
3. Correct Versions: Firefox returns actual version, not Mozilla version
4. Type Safety: Modern API uses enums for browsers and platforms
5. Better DX: Integer versions allow proper numeric comparison
6. Comprehensive Tests: 56 tests document both APIs
7. PHP 8.2+ Features: readonly classes, enums, strict types

Related Documentation

See ~/horde-development/ for conversion planning documents.

Testing

cd ~/git/horde/Browser
composer install
vendor/bin/phpunit