README

Official SDK for integrating Unikhorn's horse coat color calculator API into your PHP applications.

🚀 Installation

Install via Composer:

composer require unikhorn/coat-calculator-sdk

🔑 Getting Started

First, get your API key from Unikhorn.

Note: For local development, you can use any API key value since local requests (localhost, 127.0.0.1, private networks) bypass API key validation.

<?php
require_once 'vendor/autoload.php';

use Unikhorn\CoatCalculator\UnikhornClient;
use Unikhorn\CoatCalculator\UnikhornException;

// Initialize the SDK
$unikhorn = new UnikhornClient('your-api-key-here', [ // Required for external requests
    'language' => 'en' // or 'fr'
]);

// Verify your API key and check available endpoints
try {
    $apiInfo = $unikhorn->getApiInfo();
    echo "API Status: " . ($apiInfo['authenticated'] ? 'Connected' : 'Failed') . "\n";
    echo "Available endpoints:\n";
    foreach ($apiInfo['endpoints'] as $name => $endpoint) {
        echo "  - {$name}: {$endpoint}\n";
    }
} catch (UnikhornException $e) {
    echo "API authentication failed: " . $e->getMessage() . "\n";
}

📖 Usage Examples

Calculate a Single Horse's Coat Color

$horseGenes = [
    'base' => [
        'extension' => ['E', 'e'],
        'agouti' => ['A', 'a']
    ],
    'others' => [
        'matp' => ['Cr', 'n'],
        'dun' => ['D', 'nd2']
    ],
    'lang' => 'en'
];

try {
    $result = $unikhorn->calculateSingleCoat($horseGenes);
    echo "Coat color: " . $result['translate'] . "\n";
    echo "Base: " . $result['base']['name'] . " (" . $result['base']['translation'] . ")\n";
} catch (UnikhornException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Calculate Offspring Possibilities

$offspringData = [
    'mother' => [
        'base' => [
            'extension' => ['e', 'e'],
            'agouti' => ['a', 'a']
        ],
        'others' => [
            'matp' => ['Cr', 'Cr']
        ]
    ],
    'father' => [
        'base' => [
            'extension' => ['E', 'e'],
            'agouti' => ['A', 'A']
        ],
        'others' => [
            'grey' => ['G', 'n']
        ]
    ],
    'lang' => 'en'
];

try {
    $offspring = $unikhorn->calculateOffspring($offspringData);
    
    foreach ($offspring['results'] as $result) {
        echo "{$result['translate']}: {$result['percentage']}%\n";
    }
} catch (UnikhornException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Batch Calculate Multiple Horses

$horses = [
    [
        'id' => 'horse1', 
        'genes' => [
            'base' => ['extension' => ['E', 'E'], 'agouti' => ['A', 'A']],
            'lang' => 'en'
        ]
    ],
    [
        'id' => 'horse2', 
        'genes' => [
            'base' => ['extension' => ['e', 'e'], 'agouti' => ['a', 'a']],
            'lang' => 'en'
        ]
    ],
    [
        'id' => 'horse3', 
        'genes' => [
            'base' => ['extension' => ['E', 'e'], 'agouti' => ['A', 'a']],
            'others' => ['matp' => ['Cr', 'Cr']],
            'lang' => 'en'
        ]
    ]
];

try {
    $results = $unikhorn->batchCalculate($horses);
    foreach ($results as $result) {
        echo "{$result['id']}: {$result['result']['translate']}\n";
    }
} catch (UnikhornException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Validate Genetic Input

$genes = [
    'base' => [
        'extension' => ['E', 'e'],
        'agouti' => ['A', 'a']
    ]
];

try {
    $validation = $unikhorn->validateGenes($genes);
    if ($validation['valid']) {
        echo "Genes are valid!\n";
    } else {
        echo "Validation errors:\n";
        foreach ($validation['errors'] as $error) {
            echo "- {$error}\n";
        }
    }
} catch (UnikhornException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

🧬 Supported Genes

Base Colors

• Extension (E): Controls black/red pigment
• Agouti (A): Controls black pigment distribution

Genes

• Grey (G)
• MATP (Cr & Prl): Cream and Pearl dilutions
• KIT : Tobiano, Roan, Sabino, DW, PATN1
• Leopard Complex (LP)
• Dun (D)
• Silver (Z)
• Champagne (Ch)
• Mushroom (Mu)
• Splash: MIFT & PAX3

🌍 Language Support

The SDK supports both English and French:

// Set language globally
$unikhorn->setLanguage('fr');

// Or per instance
$unikhornFR = new UnikhornClient('your-api-key', [
    'language' => 'fr'
]);

📊 Monitor Your Usage

// Note: Usage stats endpoint is not available in current API version
try {
    $stats = $unikhorn->getUsageStats();
    echo "Requests used: " . $stats['totalRequests'] . "\n";
} catch (UnikhornException $e) {
    echo "Usage stats not available: " . $e->getMessage() . "\n";
}

⚙️ Configuration Options

$unikhorn = new UnikhornClient('your-api-key', [
    'language' => 'en',                     // Optional: 'en' or 'fr'
    'base_url' => 'https://api.unikhorn.io/v1', // Optional (default shown)
    'timeout' => 30                         // Optional: timeout in seconds
]);

🐛 Error Handling

The SDK throws UnikhornException for API-related errors:

use Unikhorn\CoatCalculator\UnikhornException;

try {
    $result = $unikhorn->calculateSingleCoat($genes);
} catch (UnikhornException $e) {
    echo "API Error ({$e->getCode()}): {$e->getMessage()}\n";
    
    // Check error type
    if ($e->isValidationError()) {
        echo "This is a validation error\n";
    } elseif ($e->isAuthenticationError()) {
        echo "Check your API key\n";
    } elseif ($e->isRateLimitError()) {
        echo "Rate limit exceeded\n";
    }
    
    // Get additional error data
    $errorData = $e->getErrorData();
    if (!empty($errorData)) {
        print_r($errorData);
    }
}

🧪 Development

Requirements

• PHP 7.4 or higher
• Guzzle HTTP client
• JSON extension

Running Tests

composer test

🔗 Links

• API Documentation
• Support
• Unikhorn Agency
• GitHub

📄 License

MIT License - see LICENSE file for details.