README

PHP package for dealing with different formats of betting odds: decimal (European), fractional (British), and moneyline (American).

🚀 New Architecture (v2.0)

This library has been completely redesigned with:

• Immutable Odds class containing all formats and probability (not meant for direct instantiation - use OddsFactory)
• 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
• Fixed precision integer support for performance-critical applications

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

Requirements

• PHP 8.4+ (required for bcmath precision functions)
• bcmath extension (standard in most installations)
• Composer

Installation

composer require gryfoss/odds

Quick Start

require 'vendor/autoload.php';

use GryfOSS\Odds\OddsFactory;

$factory = new OddsFactory();

// Create from string decimal (secure, precise)
$odds = $factory->fromDecimal('2.50');

echo $odds->getDecimal();     // "2.50"
echo $odds->getFractional();  // "3/2"
echo $odds->getMoneyline();   // "+150"
echo $odds->getProbability(); // 40 (integer percentage)

Usage Examples

Basic Conversions

$factory = new OddsFactory();

// From decimal
$odds = $factory->fromDecimal('1.75');

// From fractional
$odds = $factory->fromFractional(3, 4);

// From moneyline
$odds = $factory->fromMoneyline('-133');

// From fixed precision integer (advanced usage)
$odds = $factory->fromFixedPrecision(250); // Represents 2.50

With Odds Ladder

use GryfOSS\Odds\Utils\OddsLadder;

$oddsLadder = new OddsLadder();
$factory = new OddsFactory($oddsLadder);

$odds = $factory->fromDecimal('2.00');
echo $odds->getFractional(); // Uses odds ladder lookup

Custom Odds Ladder

use GryfOSS\Odds\Utils\OddsLadder;

class MyCustomLadder extends OddsLadder
{
    protected function getLadder(): array
    {
        return [
            '1.50' => 'evens',
            '2.00' => '1/1',
            '3.00' => '2/1',
        ];
    }
}

$factory = new OddsFactory(new MyCustomLadder());
$odds = $factory->fromDecimal('1.90');
echo $odds->getFractional(); // "evens"

Working with Fixed Precision Integers

For performance-critical applications, you can work directly with fixed precision integers (decimal * 100):

$factory = new OddsFactory();

// Create from already prepared integer (2.50 = 250)
$odds = $factory->fromFixedPrecision(250);
echo $odds->getDecimal();           // "2.50"
echo $odds->getFixedPrecisionOdds(); // 250

// Useful for database storage or API responses
$integerOdds = $odds->getFixedPrecisionOdds(); // Store as integer
$restoredOdds = $factory->fromFixedPrecision($integerOdds); // Restore later

Migration from old odds-formatter.

See STRING_DECIMAL_GUIDE.md for detailed migration instructions.

Key Changes:

• Use OddsFactory instead of individual odd classes
• Pass decimals as strings: '2.50' instead of 2.50
• All return values are strings for precision (except getProbability() which returns integer)
• Single Odds object contains all formats
• Odds class is immutable and should not be instantiated directly

Documentation

• String Decimal Guide - Precision and migration
• NEW_API.md - Complete API documentation

License

This is an open-sourced software licensed under the MIT license.