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

Guide	Description
📖 Documentation Index	Complete documentation overview
⚙️ Configuration	Environment variables and config setup
🔐 OAuth Flows	Authentication methods and token management
📡 Data API	Accessing iRacing Data API with typed services
🔒 Security	Security features and best practices

Advanced Topics

Guide	Description
📋 Sessions	OAuth2 session management and revocation
🎯 Data Services	Generated typed service wrappers
🔧 Integration	Production application patterns
🧪 Testing	Unit and integration testing guide

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

See LICENSE for details.

manujoz / iracing-api-sdk-php

Maintainers

Details