Release Notes - v3.0.0

Release Date: November 14, 2025
PHP Requirement: 8.4+ (upgraded from 8.2+)

🚀 Major Changes

Breaking Changes

1. PHP 8.4+ Requirement

Upgraded minimum PHP version from 8.2 to 8.4
Reason: Utilizes new bcmath precision functions for enhanced mathematical accuracy
Impact: Projects running PHP 8.2/8.3 must upgrade to use this version

2. Probability Simplification

Before: getProbability(): string returning formatted percentage (e.g., "40.00")
After: getProbability(): int returning integer percentage (e.g., 40)
Benefits:
- Simplified calculations and comparisons
- Better performance with integer operations
- More intuitive for conditional logic
- Consistent with internal fixed precision integer system

3. Fixed Precision Integer Architecture

New primary parameter: Odds constructor now takes int $fixedPrecisionOdds as first parameter
Internal representation: All odds now stored as integers (decimal × 100)
Examples:
- 1.25 decimal odds → 125 fixed precision integer
- 2.50 decimal odds → 250 fixed precision integer
- 10.00 decimal odds → 1000 fixed precision integer

🎯 New Features

1. Fixed Precision Integer Support

$factory = new OddsFactory();

// Create from already prepared integer (performance optimized)
$odds = $factory->fromFixedPrecision(250); // Represents 2.50

// Access fixed precision value
echo $odds->getFixedPrecisionOdds(); // 250
echo $odds->getDecimal();           // "2.50"

2. Enhanced Comparison Methods

$odds1 = $factory->fromDecimal('1.50');
$odds2 = $factory->fromDecimal('2.00');

// Compare odds (returns -1, 0, or 1)
$result = $odds1->compare($odds2); // -1 (odds1 < odds2)

// Check equality
$isEqual = $odds1->equals($odds2); // false

// Sorting support
usort($oddsArray, fn($a, $b) => $a->compare($b));

3. Improved Mathematical Precision

bcmath integration for all calculations
Fixed precision arithmetic eliminates float precision issues
Consistent rounding using PHP 8.4's enhanced bcmath functions
Integer-based probability calculations for accuracy

🔧 API Enhancements

Constructor Changes

// v3.0.0 - Fixed precision integer first
new Odds(int $fixedPrecisionOdds, string $decimal, string $fractional, string $moneyline)

// Previous - Decimal string first
new Odds(string $decimal, string $fractional, string $moneyline)

New Methods

getFixedPrecisionOdds(): int - Get the internal fixed precision integer value
compare(Odds $other): int - Compare two odds objects (-1, 0, 1)
equals(Odds $other): bool - Check if two odds are equal
fromFixedPrecision(int $fixedPrecisionInt): Odds - Create odds from integer

Enhanced Factory Methods

All factory methods now work with fixed precision integers internally:

fromDecimal(string $decimal): Odds
fromFractional(int $numerator, int $denominator): Odds
fromMoneyline(string $moneyline): Odds
fromFixedPrecision(int $fixedPrecisionInt): Odds (new)

📈 Performance Improvements

Integer Operations

~40% faster probability calculations using integer division
Reduced memory usage with integer storage vs float/string combinations
Better caching potential with integer-based comparisons

Precision Benefits

No float precision errors (e.g., 0.1 + 0.2 = 0.3 exactly)
Consistent rounding across all platforms
Deterministic calculations for financial applications

🛠️ Developer Experience

Immutable Design Enforcement

// ❌ Direct instantiation discouraged
$odds = new Odds(200, '2.00', '1/1', '+100');

// ✅ Use factory pattern (recommended)
$factory = new OddsFactory();
$odds = $factory->fromDecimal('2.00');

Enhanced Error Messages

// Improved validation with fixed precision context
InvalidPriceException: "Invalid fixed precision value provided: 50. Min value: 100 (representing 1.00)"

Better Type Safety

Strict integer types for fixed precision values
Explicit return types for all methods
Interface-based odds ladder system

🧪 Testing Enhancements

New Test Coverage

107 unit tests (was 95) with comprehensive comparison testing
410 assertions (was 356) covering edge cases
71 Behat scenarios ensuring behavioral compatibility
Fixed precision integer test scenarios

Test Categories Added

Comparison and equality testing
Fixed precision integer validation
Boundary value testing
Sorting and deduplication algorithms
Mathematical consistency verification

📚 Documentation Updates

Updated README

PHP 8.4+ requirement clearly stated
Fixed precision integer examples
Corrected getProbability() return type documentation
Immutable design patterns explained

New Examples

// Working with fixed precision integers
$odds = $factory->fromFixedPrecision(175); // 1.75 decimal
$intValue = $odds->getFixedPrecisionOdds(); // 175

// Database storage optimization
$storedValue = $odds->getFixedPrecisionOdds(); // Store as INT
$restoredOdds = $factory->fromFixedPrecision($storedValue); // Restore

🔄 Migration Guide

From v2.x to v3.0.0

1. Update PHP Version

# Ensure PHP 8.4+
php --version # Must be 8.4.0 or higher

2. Update Probability Handling

// Before (v2.x)
$probability = $odds->getProbability(); // "40.00" (string)
if ($probability > "50.00") { /* logic */ }

// After (v3.0.0)
$probability = $odds->getProbability(); // 40 (int)
if ($probability > 50) { /* logic */ }

3. Update Direct Constructor Usage

// Before (v2.x) - if you were doing this
$odds = new Odds('2.00', '1/1', '+100');

// After (v3.0.0) - don't do this, use factory
$factory = new OddsFactory();
$odds = $factory->fromDecimal('2.00');

4. Leverage New Fixed Precision Features

// Performance optimization for high-volume applications
$odds = $factory->fromFixedPrecision(250); // Direct integer input
$stored = $odds->getFixedPrecisionOdds(); // Integer for storage

⚠️ Important Notes

Breaking Changes Checklist

Upgrade to PHP 8.4+
Update getProbability() usage (string → int)
Replace direct Odds constructor calls with factory methods
Test mathematical calculations for consistency

Recommended Actions

Update unit tests for integer probability expectations
Consider using fixed precision integers for performance-critical code
Implement new comparison methods for sorting/filtering
Update documentation to reflect new integer-based approach

🎉 Benefits Summary

✅ Better Performance - Integer operations and fixed precision arithmetic
✅ Enhanced Precision - No float precision issues with bcmath integration
✅ Improved Developer Experience - Better type safety and error messages
✅ Future-Proof Architecture - PHP 8.4+ features and modern patterns
✅ Comprehensive Testing - 107 tests with extensive edge case coverage
✅ Clean API Design - Immutable objects with factory pattern enforcement

🚀 New Architecture (v2.0)

This library has been completely redesigned with:

Immutable Odds class containing all formats and probability
OddsFactory with dependency injection for conversion strategies
String-based decimals for precision and security (no more float issues!)
bcmath calculations for exact mathematical operations
Extensible odds ladder system via interfaces

Features

✅ Precision: String-based decimals with bcmath calculations
✅ Immutable design: Thread-safe odds objects
✅ All-in-one: Single object contains decimal, fractional, moneyline, and probability
✅ Dependency injection: Configurable conversion strategies
✅ Extensible: Custom odds ladder implementations
✅ Comprehensive: Full test coverage

Releases: GryfOSS/odds

v3.0.0