README

🏁 iRacing API SDK (PHP)

Zero-dependency PHP SDK for iRacing OAuth2 Authentication & Data API

⭐ If you find this project useful, please give it a star! ⭐

📖 Documentation • 🚀 Examples • 🔒 Security • 🤝 Contributing

🎯 What is this?

iracing-api-sdk-php is a zero-dependency PHP SDK that provides primitives for:

• OAuth2 Authentication: Password Limited, Authorization Code + PKCE, token refresh
• Data API Client: Access to iRacing's Data API (with typed generated services)
• Session Management: List and revoke OAuth2 sessions
• Security First: Credential masking, safe auth header forwarding, secure file caches

It is framework-agnostic by design: you bring your own logger and storage, while the library focuses on secure OAuth flows, token handling, and HTTP interactions.

✨ Features

• ✅ Zero runtime dependencies - Pure PHP at runtime
• ✅ Security built-in - Never logs secrets, credential masking utilities
• ✅ OAuth2 complete - Password Limited, Authorization Code + PKCE, token refresh
• ✅ Typed services - Generated service wrappers under IracingApiSdk\Data\Services\*
• ✅ Flexible storage - File-based storage + interfaces for custom implementations
• ✅ Production friendly - Explicit error handling, rate limit utilities, and tests

📦 Installation

composer require manujoz/iracing-api-sdk-php

🚀 Quick Start

1. Configure Environment

Create a local .env from .env.example and set your iRacing OAuth credentials.

cp .env.example .env

2. Authenticate & Access Data

The repository ships runnable CLI examples. Recommended first run:

php examples/10-auth-password-limited.php
php examples/20-data-car-get.php

Minimal bootstrap (same classes used by the examples):

<?php

declare(strict_types=1);

use IracingApiSdk\Config\Config;
use IracingApiSdk\Http\HttpClient;
use IracingApiSdk\OAuth\OAuthClient;

$config = Config::fromEnv();
$http = new HttpClient();

$oauth = new OAuthClient($config, $http);

// Authenticate using Password Limited (credentials are loaded from env).
// Important: never print or log tokens/secrets.
// $tokenSet = $oauth->authenticatePasswordLimited(/* ... */);

📚 Documentation

Core Guides

Advanced Topics

Examples

See examples/ for runnable code samples:

• OAuth2 authentication flows
• Token refresh patterns
• Data API calls
• Session management

🛡️ Security

This SDK follows strict security practices:

• Never logs secrets - Client secrets, passwords, and tokens must never be logged
• Credential masking - Helpers for iRacing's password masking requirements
• Authorization header protection - Auth headers are forwarded only to trusted origins
• Secure file storage - Token/session caches should be stored with restrictive permissions

See Security Documentation for details.

🧪 Development

Prerequisites

• PHP ≥ 8.3
• Composer

Commands

composer install
composer validate --no-check-all --strict
composer test
composer test:unit
composer test:integration
composer test:all

Integration tests are opt-in and only run when IRACING_RUN_INTEGRATION=1 is set (and valid credentials exist in .env).

Project Structure

src/
├── Config/          # Configuration management
├── Crypto/          # Credential masking
├── Data/            # Data API client + generated services
├── Errors/          # Exception handling
├── Http/            # HTTP client abstraction
├── Log/             # Logger interfaces and default error_log logger
├── OAuth/           # OAuth2 flows (password_limited, auth code + PKCE) + sessions
├── RateLimit/       # Rate limiting helpers
├── Response/        # Response wrappers
├── Token/           # Token storage and expiration handling
└── Utils/           # File/HTTP/token utilities

🤝 Contributing

Please see CONTRIBUTING.md for:

• Development workflow
• Code standards
• Testing requirements
• Commit message format
• Pull request process

📄 License

MIT © Manu Overa

See LICENSE for details.