README

gboquizosanchez/retroachievements

RetroAchievements.org API client for Laravel

Fetch achievements, user stats, and game data from RetroAchievements.org directly in your Laravel app.

Overview

A Laravel package that wraps the full RetroAchievements API, giving you access to game data, user profiles, achievement lists, and more — with optional DTO mapping via spatie/laravel-data.

Note: You need a RetroAchievements account and a Web API key from your control panel to use this package.

📦 Installation

composer require gboquizosanchez/retroachievements

Add your credentials to .env:

RA_USERNAME=your_username
RA_WEB_API_KEY=your_api_key

Optionally, publish the configuration file:

php artisan vendor:publish --provider="RetroAchievements\RetroAchievementsServiceProvider"

🚀 Usage

Via facade

The facade reads credentials directly from your .env:

use Retroachievements\RetroClient;

RetroClient::getGame(gameId: 1);

Via the client directly

Useful when working with multiple accounts or custom credentials:

use Retroachievements\Data\AuthData;
use RetroAchievements\Models\RetroAchievements;

$auth = new AuthData(
    username: 'your_username',
    webApiKey: 'your_api_key',
);

$client = new RetroAchievements($auth);
$client->getGame(gameId: 1);

You can also use the default credentials from config:

$auth = new AuthData(...config('retro-achievements.credentials'));

🗺️ Response mapping

By default, the package maps responses to typed DTOs. You can switch to raw responses via .env:

# Default — typed DTOs via spatie/laravel-data
RA_DTO_MAPPING=true
RA_RAW_MAPPING=false

# Raw responses — disable DTO mapping first
RA_DTO_MAPPING=false
RA_RAW_MAPPING=true

RAW mapping only works when RA_DTO_MAPPING is set to false.

📚 Available methods

This package covers all endpoints from the RetroAchievements API. See RetroClient for the full method list.

🧪 Testing

composer test

Contributing

Contributions are welcome!

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features or improvements
• 🔧 Submit pull requests with fixes or enhancements

Credits

• Author: Germán Boquizo Sánchez
• Contributors: View all contributors

📄 License

This package is open-source software licensed under the MIT License.