Quick Start Guide

Get up and running with the Trading Card API PHP SDK in minutes. This guide covers the essential usage patterns and basic operations.

Basic Usage Patterns

The SDK provides three main ways to interact with the API:

1. Using the Facade (Recommended)

The facade provides a clean, static interface:

<?php

use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

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

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

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

2. Using the Helper Function

A convenient helper function for quick access:

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

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

// List all genres
$genres = tradingcardapi()->genre()->getList();

3. Direct Class Usage

For more control and dependency injection:

use CardTechie\TradingCardApiSdk\TradingCardApi;

class CardService
{
    public function __construct(
        private TradingCardApi $api
    ) {}

    public function getPopularCards(): array
    {
        return $this->api->card()->getList([
            'sort' => 'popularity',
            'limit' => 50
        ]);
    }
}

Essential Operations

Getting Single Resources

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

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

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

// Get with related data
$card = TradingCardApiSdk::card()->get('card-id', [
    'include' => 'set,player,prices'
]);

Listing Resources

// List cards with pagination
$cards = TradingCardApiSdk::card()->getList([
    'page' => 1,
    'limit' => 25
]);

// List with filters
$cards = TradingCardApiSdk::card()->getList([
    'name' => 'Charizard',
    'year' => 2023,
    'genre' => 'Pokemon'
]);

// List with sorting
$cards = TradingCardApiSdk::card()->getList([
    'sort' => 'name',
    'order' => 'asc'
]);

Creating Resources

// Create a new card
$card = TradingCardApiSdk::card()->create([
    'name' => 'Custom Card',
    'description' => 'A special custom card',
    'set_id' => 'set-123',
    'player_id' => 'player-456'
]);

// Create a team
$team = TradingCardApiSdk::team()->create([
    'name' => 'Custom Team',
    'location' => 'Custom City',
    'founded_year' => 2023
]);

Updating Resources

// Update a card
$card = TradingCardApiSdk::card()->update('card-id', [
    'name' => 'Updated Card Name',
    'description' => 'Updated description'
]);

// Update a set
$set = TradingCardApiSdk::set()->update('set-id', [
    'name' => 'Updated Set Name',
    'release_year' => 2024
]);

Deleting Resources

// Delete a card
$success = TradingCardApiSdk::card()->delete('card-id');

// Delete a set
$success = TradingCardApiSdk::set()->delete('set-id');

Working with Relationships

Including Related Data

// Get card with all relationships
$card = TradingCardApiSdk::card()->get('card-id', [
    'include' => 'set,player,team,genre,prices'
]);

// Access related data
echo $card['set']['name'];
echo $card['player']['name'];
echo $card['team']['location'];

Specific Relationship Queries

// Get set with its cards
$set = TradingCardApiSdk::set()->get('set-id', [
    'include' => 'cards'
]);

foreach ($set['cards'] as $card) {
    echo $card['name'] . "\n";
}

Error Handling Basics

Always wrap API calls in try-catch blocks:

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

try {
    $card = TradingCardApiSdk::card()->get('card-id');
    echo "Card found: " . $card['name'];
} catch (CardNotFoundException $e) {
    echo "Card not found: " . $e->getMessage();
} catch (ValidationException $e) {
    echo "Validation error: " . $e->getMessage();
    // Handle validation errors
    foreach ($e->getValidationErrors() as $field => $errors) {
        echo "Field $field: " . implode(', ', $errors);
    }
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after: " . $e->getRetryAfter() . " seconds";
} catch (AuthenticationException $e) {
    echo "Authentication failed: " . $e->getMessage();
}

Common Patterns

Search and Filter

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

// Filter by multiple criteria
$cards = TradingCardApiSdk::card()->getList([
    'genre' => 'Pokemon',
    'year' => 2023,
    'rarity' => 'rare'
]);

// Complex search with sorting and pagination
$cards = TradingCardApiSdk::card()->getList([
    'name' => 'Charizard',
    'sort' => 'release_date',
    'order' => 'desc',
    'page' => 1,
    'limit' => 50
]);

Pagination Handling

function getAllCards(): array
{
    $allCards = [];
    $page = 1;
    $limit = 100;

    do {
        $response = TradingCardApiSdk::card()->getList([
            'page' => $page,
            'limit' => $limit
        ]);
        
        $allCards = array_merge($allCards, $response['data']);
        $page++;
        
        // Check if there are more pages
        $hasMore = count($response['data']) === $limit;
    } while ($hasMore);

    return $allCards;
}

Bulk Operations

// Process multiple cards efficiently
function processCards(array $cardIds): array
{
    $results = [];
    
    foreach ($cardIds as $cardId) {
        try {
            $card = TradingCardApiSdk::card()->get($cardId);
            $results[$cardId] = $card;
        } catch (CardNotFoundException $e) {
            $results[$cardId] = null; // Card not found
        }
    }
    
    return $results;
}

Integration with Laravel Features

Using in Controllers

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

class CardController extends Controller
{
    public function index(Request $request)
    {
        $cards = TradingCardApiSdk::card()->getList([
            'page' => $request->get('page', 1),
            'limit' => 25,
            'name' => $request->get('search')
        ]);

        return view('cards.index', compact('cards'));
    }

    public function show($id)
    {
        try {
            $card = TradingCardApiSdk::card()->get($id, [
                'include' => 'set,player,prices'
            ]);

            return view('cards.show', compact('card'));
        } catch (CardNotFoundException $e) {
            abort(404, 'Card not found');
        }
    }
}

Using in Artisan Commands

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

class SyncCardsCommand extends Command
{
    protected $signature = 'cards:sync';
    protected $description = 'Sync cards from Trading Card API';

    public function handle()
    {
        $this->info('Starting card sync...');

        $cards = TradingCardApiSdk::card()->getList(['limit' => 1000]);
        
        foreach ($cards['data'] as $card) {
            // Process each card
            $this->line("Processing: {$card['name']}");
        }

        $this->info('Card sync completed!');
    }
}

Using in Jobs

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

class ProcessCardJob implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private string $cardId
    ) {}

    public function handle()
    {
        $card = TradingCardApiSdk::card()->get($this->cardId);
        
        // Process the card data
        // Store in database, send notifications, etc.
    }
}

Configuration in Different Environments

Testing Environment

// tests/Feature/CardApiTest.php
<?php

namespace Tests\Feature;

use Tests\TestCase;
use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

class CardApiTest extends TestCase
{
    public function test_can_fetch_cards()
    {
        // Mock the API response for testing
        $cards = TradingCardApiSdk::card()->getList(['limit' => 5]);
        
        $this->assertIsArray($cards);
        $this->assertArrayHasKey('data', $cards);
    }
}

Next Steps

Now that you're familiar with the basics:

1. API Resources - Explore all available resources and methods
2. Error Handling - Comprehensive error management
3. Installation & Setup - Detailed installation and configuration guide
4. Examples - Real-world implementation examples