README

gboquizosanchez/screenscraper

ScreenScraper.fr API client for Laravel

Fetch game metadata, media, and platform data from ScreenScraper.fr directly in your Laravel app.

Overview

A Laravel package that wraps the full ScreenScraper API, giving you access to game info, artwork, ratings, and more — with optional DTO mapping via spatie/laravel-data.

Note: You need a ScreenScraper account and developer credentials to use this package. Register here and request developer access here.

📦 Installation

composer require gboquizosanchez/screenscraper

Add your credentials to .env:

SCREENSCRAPER_BASE_URL=https://api.screenscraper.fr/api2/
SCREENSCRAPER_OUTPUT=json
SCREENSCRAPER_USERNAME=your_username
SCREENSCRAPER_PASSWORD=your_password
SCREENSCRAPER_DEV_ID=your_dev_id
SCREENSCRAPER_DEV_PASSWORD=your_dev_password
SCREENSCRAPER_SOFTNAME="ScreenScraper API Client for Laravel"
SCREENSCRAPER_DTO_MAPPING=true
SCREENSCRAPER_RAW_MAPPING=false

Optionally, publish the configuration file:

php artisan vendor:publish --provider="ScreenScraper\ScreenScraperServiceProvider"

🚀 Usage

Via facade

The facade reads credentials directly from your .env:

use ScreenScraper\ScreenScraperClient;

ScreenScraperClient::getGame(gameId: 1);

Via the client directly

Useful when working with multiple accounts or custom credentials:

use ScreenScraper\Data\AuthData;
use ScreenScraper\Models\ScreenScraper;

$auth = new AuthData(
    devId: 'your_dev_id',
    devPassword: 'your_dev_password',
    softname: 'Your App Name',
    output: 'json',
    ssid: 'your_username',
    sspassword: 'your_password',
);

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

You can also use the default credentials from config:

$auth = new AuthData(...config('screenscraper.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
SCREENSCRAPER_DTO_MAPPING=true
SCREENSCRAPER_RAW_MAPPING=false

# Raw responses — disable DTO mapping first
SCREENSCRAPER_DTO_MAPPING=false
SCREENSCRAPER_RAW_MAPPING=true

RAW mapping only works when SCREENSCRAPER_DTO_MAPPING is set to false.

📚 Available methods

This package covers all endpoints from the ScreenScraper API. See ScreenScraperClient 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.