README

A modern PHP SDK for integrating with the Trading Card API. This Laravel package provides a clean, type-safe interface for accessing trading card data including cards, sets, players, teams, and more.

✨ Features

🔧 Laravel Integration - Built specifically for Laravel applications
🛡️ Type Safety - Full PHPStan Level 4 compliance with strict typing
🧪 Well Tested - Comprehensive test suite with 80%+ coverage
📦 Easy Installation - Simple Composer installation and configuration
🔄 OAuth2 Authentication - Automatic token management and renewal
🚨 Enhanced Error Handling - Specific exception classes for different error types
📖 Rich Documentation - Clear examples and comprehensive API coverage
⚡ High Performance - Efficient HTTP client with connection pooling

📋 Requirements

PHP 8.1 or higher
Laravel 10.0 or higher
GuzzleHTTP 7.5 or higher

🚀 Installation

Install the package via Composer:

composer require cardtechie/tradingcardapi-sdk-php

Publish the configuration file:

php artisan vendor:publish --tag="tradingcardapi-config"

Add your API credentials to your .env file:

TRADINGCARDAPI_URL=https://api.tradingcardapi.com
TRADINGCARDAPI_CLIENT_ID=your_client_id
TRADINGCARDAPI_CLIENT_SECRET=your_client_secret
TRADINGCARDAPI_SSL_VERIFY=true

🎯 Quick Start

Using the Facade

use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

// Get a specific card
$card = TradingCardApiSdk::card()->get('card-id');

// Search for cards
$cards = TradingCardApiSdk::card()->getList(['name' => 'Pikachu']);

// Get player information
$player = TradingCardApiSdk::player()->get('player-id');

// Get paginated list of players
$players = TradingCardApiSdk::player()->list(['limit' => 25, 'page' => 1]);

// Search for players
$players = TradingCardApiSdk::player()->getList(['full_name' => 'Michael Jordan']);

Using the Helper Function

// Get a set with related data
$set = tradingcardapi()->set()->get('set-id', ['include' => 'cards,genre']);

// Create a new team
$team = tradingcardapi()->team()->create([
    'name' => 'New Team',
    'location' => 'City Name'
]);

Error Handling

The SDK provides comprehensive error handling with specific exception classes:

use CardTechie\TradingCardApiSdk\Exceptions\{
    CardNotFoundException,
    ValidationException,
    RateLimitException,
    AuthenticationException
};

try {
    $card = TradingCardApiSdk::card()->get('invalid-id');
} catch (CardNotFoundException $e) {
    // Handle missing card
    echo "Card not found: " . $e->getMessage();
} catch (ValidationException $e) {
    // Handle validation errors
    foreach ($e->getValidationErrors() as $field => $errors) {
        echo "Field $field: " . implode(', ', $errors);
    }
} catch (RateLimitException $e) {
    // Handle rate limiting
    echo "Rate limited. Retry after: " . $e->getRetryAfter() . " seconds";
}

Direct Class Usage

use CardTechie\TradingCardApiSdk\TradingCardApi;

$api = new TradingCardApi();
$genres = $api->genre()->getList();

👥 Working with Players

The Player resource provides comprehensive CRUD operations and relationship management:

Basic Operations

use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

// Get a specific player
$player = TradingCardApiSdk::player()->get('player-id');

// Create a new player
$player = TradingCardApiSdk::player()->create([
    'first_name' => 'Michael',
    'last_name' => 'Jordan'
]);

// Update player information
$player = TradingCardApiSdk::player()->update('player-id', [
    'first_name' => 'Michael Jeffrey',
    'last_name' => 'Jordan'
]);

// Delete a player
TradingCardApiSdk::player()->delete('player-id');

Listing and Searching

// Get paginated list of players
$players = TradingCardApiSdk::player()->list([
    'limit' => 50,
    'page' => 1,
    'sort' => 'last_name'
]);

// Search for players (returns Collection)
$players = TradingCardApiSdk::player()->getList([
    'full_name' => 'Michael Jordan',
    'parent_id' => null  // Only parent players, not aliases
]);

// Find players by partial name
$players = TradingCardApiSdk::player()->getList([
    'first_name' => 'Michael'
]);

Player Relationships

// Working with player relationships
$player = TradingCardApiSdk::player()->get('player-id');

// Get parent player (if this is an alias)
$parent = $player->getParent();

// Get all aliases of this player
$aliases = $player->getAliases();

// Get teams this player has been associated with
$teams = $player->getTeams();

// Get all player-team relationships
$playerteams = $player->getPlayerteams();

// Check if player is an alias
if ($player->isAlias()) {
    echo "This is an alias of: " . $player->getParent()->full_name;
}

// Check if player has aliases
if ($player->hasAliases()) {
    echo "This player has " . $player->getAliases()->count() . " aliases";
}

Creating Player Hierarchies

// Create a parent player
$parent = TradingCardApiSdk::player()->create([
    'first_name' => 'Michael',
    'last_name' => 'Jordan'
]);

// Create an alias player with parent relationship
$alias = TradingCardApiSdk::player()->create(
    ['first_name' => 'Mike', 'last_name' => 'Jordan'],
    ['parent' => ['data' => ['type' => 'players', 'id' => $parent->id]]]
);

Working with Deleted Players

// List deleted players
$deletedPlayers = TradingCardApiSdk::player()->listDeleted();

// Get a specific deleted player
$deletedPlayer = TradingCardApiSdk::player()->deleted('player-id');

Player Model Attributes

$player = TradingCardApiSdk::player()->get('player-id');

// Access player data
echo $player->first_name;        // "Michael"
echo $player->last_name;         // "Jordan"
echo $player->full_name;         // "Michael Jordan" (computed attribute)
echo $player->last_name_first;   // "Jordan, Michael" (computed attribute)

// Check relationships
echo $player->parent_id;         // UUID of parent player (if alias)

📚 Available Resources

The SDK provides access to the following Trading Card API resources:

Resource	Description	Methods
Cards	Individual trading cards	`get()`, `create()`, `update()`, `delete()`
Sets	Card sets and collections	`get()`, `list()`, `create()`, `update()`, `delete()`, `checklist($id)`, `addMissingCards($id)`, `addChecklist($request, $id)`
Players	Player information	`get()`, `list()`, `getList()`, `create()`, `update()`, `delete()`, `listDeleted()`, `deleted($id)`
Teams	Team data	`get()`, `getList()`, `create()`
Genres	Card categories/types	`get()`, `list()`, `create()`, `update()`, `delete()`, `listDeleted()`, `deleted($id)`
Brands	Trading card brands	`get()`, `list()`, `create()`, `update()`, `delete()`
Manufacturers	Trading card manufacturers	`get()`, `list()`, `create()`, `update()`, `delete()`
Years	Trading card years	`get()`, `list()`, `create()`, `update()`, `delete()`
ObjectAttributes	Object attributes	`get()`, `list()`, `create()`, `update()`, `delete()`
Stats	Model statistics	`get($type)`
Attributes	Card attributes	`get()`, `getList()`

🔧 Configuration

The configuration file (config/tradingcardapi.php) supports:

return [
    'url' => env('TRADINGCARDAPI_URL', ''),
    'ssl_verify' => (bool) env('TRADINGCARDAPI_SSL_VERIFY', true),
    'client_id' => env('TRADINGCARDAPI_CLIENT_ID', ''),
    'client_secret' => env('TRADINGCARDAPI_CLIENT_SECRET', ''),
];

🧪 Development & Testing

This project uses modern PHP development tools and practices:

Prerequisites

Docker and Docker Compose
Make (optional, for convenience commands)

Getting Started

# Clone the repository
git clone https://github.com/cardtechie/tradingcardapi-sdk-php.git
cd tradingcardapi-sdk-php

# Start development environment
make up

# Install dependencies
make install

# Run tests
make test

# Run code quality checks
make check

Available Commands

make test              # Run test suite
make analyse           # Run PHPStan static analysis
make format            # Format code with Laravel Pint
make check             # Run all quality checks
make quality           # Run comprehensive quality checks with coverage
make ci                # Run CI pipeline locally

# Release management commands
make version           # Show current version
make changelog-update  # Update changelog for current version
make release-notes-preview  # Generate release notes preview

Code Quality Standards

This project maintains high code quality standards:

✅ PHPStan Level 4 - Strict static analysis
✅ PSR-12 - Code style compliance via Laravel Pint
✅ 80%+ Test Coverage - Comprehensive test suite using Pest
✅ Automated CI/CD - Quality checks on all PRs

📖 Documentation

Error Handling Guide - Comprehensive guide to exception handling
Response Validation - Response validation and schema handling
Version Management - Release process and versioning
Trading Card API Documentation - Complete API reference

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Run quality checks: make check
Submit a pull request

🐛 Bug Reports & Feature Requests

Please use the GitHub Issues to report bugs or request features.

🔒 Security

Please review our Security Policy for reporting security vulnerabilities.

🚀 Release Process

This project uses a sophisticated, automated release management system adapted from the main Trading Card API repository.

Version Management

The SDK uses intelligent, branch-aware semantic versioning:

Production releases (1.2.3) - Created from main branch
Beta releases (1.3.0.beta-5) - Created from develop branch
Release candidates (1.3.0.rc-2) - Created from release/* branches
Development versions (1.2.3-alpha.4) - Feature branches

Development Commands

# Check current version
make version

# Preview version for different branches
make version-preview --branch=main
make version-preview --branch=develop

# Update changelog for current version
make changelog-update

# Generate release notes preview
make release-notes-preview

Automated Release Process

Development: Features are developed on feature branches
Integration: Changes are merged to develop for testing
Release Preparation: Release branches are created for final testing
Production Release: Stable releases are merged to main
Automation: GitHub Actions handles versioning, changelog updates, and Packagist publishing

See docs/VERSION-MANAGEMENT.md for complete release process documentation.

📄 Changelog

See CHANGELOG.md for recent changes.

👥 Credits

Josh Harrison - Lead Developer
All Contributors

📜 License

This project is licensed under the MIT License. See LICENSE.md for details.

Made with ❤️ by CardTechie

cardtechie / tradingcardapi-sdk-php

Maintainers

Details