lucie/ballchasing-sdk

Laravel package for Ballchasing.com API integration

dev-main 2025-09-27 15:25 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.0
• mockery/mockery: ^1.6
• orchestra/testbench: ^8.0|^9.0|^10.0
• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^10.0|^11.0
• vlucas/phpdotenv: ^5.0

MIT

• Lucie

• api
• sdk
• laravel
• ballchasing
• rocket-league

README

A Laravel package for integrating with the Ballchasing.com API, providing easy access to Rocket League replay data and analysis.

Features

• ✅ Replay Management: List, retrieve, upload, update, and delete replays
• ✅ Group Management: Create and manage replay groups
• ✅ Maps Information: Get available Rocket League maps
• ✅ Laravel Integration: Service provider with dependency injection
• ✅ Type Safety: Full PHP 8.2+ type declarations and DTOs
• ✅ Testing: Comprehensive test suite with mocked HTTP responses
• ✅ Error Handling: Custom exceptions with detailed error messages
• ✅ Retry Logic: Automatic retry for server errors

Installation

Install the package via Composer:

composer require lucie/ballchasing-laravel

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=ballchasing-config

Add your Ballchasing API key to your .env file:

BALLCHASING_API_KEY=your_api_key_here

Testing

Unit Tests (Mocked)

Run unit tests with mocked HTTP responses (no API key required):

composer test
# or specifically
composer test-unit

Integration Tests (Real API)

For integration testing with the real Ballchasing API:

1. Copy the example environment file:

   cp .env.testing .env
   

2. Add your real API key to .env:

   BALLCHASING_API_KEY=your_real_api_key_here
   

3. Run integration tests:

   composer test-integration
   

Coverage Reports

Generate test coverage reports:

composer test-coverage

Development

Code Style

Format code using Pint:

composer format

Static Analysis

Run PHPStan analysis:

composer analyse

Versioning

This package follows Semantic Versioning. To create a new release:

1. Update the version in composer.json
2. Run all checks: composer release
3. Commit the changes
4. Create a new git tag: git tag v1.0.0
5. Push with tags: git push --tags

Note: Since this is a beta package (0.x.x), the API may change between minor versions until we reach 1.0.0.

Documentation

📖 Full documentation is available in multiple languages:

• English: docs/en/usage.md
• Français: docs/fr/usage.md

Requirements

• PHP 8.2+
• Laravel 10.0+
• Guzzle HTTP 7.0+

License

The MIT License (MIT). Please see License File for more information.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you discover any security vulnerabilities, please send an e-mail to [e-mail].

Credits

• Lucie
• Ballchasing.com for providing the API

Built for the Rocket League community 🚗⚽