feat: add custom exception hierarchy for better error handling

[Spomky]

Summary

This PR introduces a comprehensive custom exception system to replace generic PHP exceptions with specific, meaningful exception types while maintaining full backward compatibility.

New Exception Types

• OTPExceptionInterface: Marker interface for all OTPHP exceptions - allows catching all library exceptions with one catch block
• InvalidParameterException: For parameter validation errors (secret, digits, algorithm, period, epoch, counter, timestamp, leeway, secretSize, etc.)
• InvalidLabelException: For label/issuer format validation errors
• InvalidProvisioningUriException: For URI parsing and validation errors
• ParameterNotFoundException: For accessing non-existent parameters
• SecretDecodingException: For Base32 decoding failures

Key Features

🎯 Better Error Handling

• Catch specific exceptions instead of generic ones
• Access parameter name and value via public readonly properties for debugging
• OTPExceptionInterface allows catching all OTPHP exceptions

📖 Comprehensive Documentation

• New doc/Exceptions.md with complete exception guide
• Detailed examples for each exception type
• Migration guide and best practices
• Updated doc/index.md to reference exception handling

✅ Code Quality

• Replaced all assert() calls in src/ with proper exception throws
• All exceptions validated by PHPStan
• 133 tests pass (100% coverage maintained)
• Updated PHPStan baseline

🔄 Backward Compatibility

• All custom exceptions extend PHP built-in exceptions
• Existing catch (InvalidArgumentException $e) still works
• Existing catch (RuntimeException $e) still works
• Exception messages unchanged
• No code changes required for existing users

Examples

Before (still works)

try {
    $totp = TOTP::createFromSecret($secret);
    $totp->setDigits(0);
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Digits must be at least 1."
}

After (enhanced debugging)

try {
    $totp = TOTP::createFromSecret($secret);
    $totp->setDigits(0);
} catch (\OTPHP\Exception\InvalidParameterException $e) {
    echo $e->getMessage();      // "Digits must be at least 1."
    echo $e->parameterName;     // "digits"
    echo $e->parameterValue;    // 0
}

Catch All OTPHP Exceptions

try {
    $otp = Factory::loadFromProvisioningUri($uri);
} catch (\OTPHP\Exception\OTPExceptionInterface $e) {
    // Catches all OTPHP-specific exceptions
    log("OTPHP Error: " . $e->getMessage());
}

Test Plan

• All 133 PHPUnit tests pass
• PHPStan analysis passes with baseline
• Backward compatibility verified
• Documentation complete and accurate
• No assert() calls remaining in src/
• All exception types have public readonly properties

Breaking Changes

None - this PR is 100% backward compatible.

🤖 Generated with Claude Code