Skip to main content

Installation & Setup

This guide covers the complete installation and setup process for the Trading Card API PHP SDK in Laravel applications.

Requirements​

Before installing the SDK, ensure your environment meets these requirements:

  • PHP: 8.1 or higher
  • Laravel: 10.0 or higher
  • GuzzleHTTP: 7.5 or higher
  • Composer: Latest version recommended

Installation​

Step 1: Install via Composer​

Add the SDK to your Laravel project using Composer:

composer require cardtechie/tradingcardapi-sdk-php

Step 2: Publish Configuration​

Publish the configuration file to customize SDK settings:

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

This creates config/tradingcardapi.php with the following structure:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Trading Card API URL
    |--------------------------------------------------------------------------
    |
    | The base URL for the Trading Card API. This should typically be the
    | production API URL unless you're working with a development environment.
    |
    */
    'url' => env('TRADINGCARDAPI_URL', 'https://api.tradingcardapi.com'),

    /*
    |--------------------------------------------------------------------------
    | SSL Verification
    |--------------------------------------------------------------------------
    |
    | Whether to verify SSL certificates when making API requests. This should
    | always be true in production for security reasons.
    |
    */
    'ssl_verify' => (bool) env('TRADINGCARDAPI_SSL_VERIFY', true),

    /*
    |--------------------------------------------------------------------------
    | API Credentials
    |--------------------------------------------------------------------------
    |
    | Your Trading Card API client credentials. These are used for OAuth2
    | authentication and should be kept secure.
    |
    */
    'client_id' => env('TRADINGCARDAPI_CLIENT_ID', ''),
    'client_secret' => env('TRADINGCARDAPI_CLIENT_SECRET', ''),

    /*
    |--------------------------------------------------------------------------
    | Request Configuration
    |--------------------------------------------------------------------------
    |
    | Configuration for HTTP requests including timeouts and retry settings.
    |
    */
    'timeout' => (int) env('TRADINGCARDAPI_TIMEOUT', 30),
    'retry_attempts' => (int) env('TRADINGCARDAPI_RETRY_ATTEMPTS', 3),
    'retry_delay' => (int) env('TRADINGCARDAPI_RETRY_DELAY', 1),
];

Step 3: Environment Configuration​

Add your API credentials to your .env file:

# Trading Card API Configuration
TRADINGCARDAPI_URL=https://api.tradingcardapi.com
TRADINGCARDAPI_CLIENT_ID=your_client_id_here
TRADINGCARDAPI_CLIENT_SECRET=your_client_secret_here
TRADINGCARDAPI_SSL_VERIFY=true

# Optional: Request Configuration
TRADINGCARDAPI_TIMEOUT=30
TRADINGCARDAPI_RETRY_ATTEMPTS=3
TRADINGCARDAPI_RETRY_DELAY=1

Getting API Credentials​

Step 1: Request Access​

  1. Join the founding list with your details and intended use case
  2. Watch for the confirmation email acknowledging your request
  3. Once a founding slot is granted, you'll receive your account credentials

Step 2: Create Application​

  1. Log into your developer dashboard
  2. Click "Create New Application"
  3. Fill in your application details:
    • Application Name: Your app's name
    • Description: Brief description of your use case
    • Website: Your application's website (optional)
    • Redirect URI: For OAuth flows (if needed)

Step 3: Get Credentials​

After creating your application, you'll receive:

  • Client ID: Public identifier for your application
  • Client Secret: Private key for authentication ⚠️ Keep this secure!

Verification​

Test your installation and configuration:

<?php

use CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk;

try {
    // Test basic connectivity
    $genres = TradingCardApiSdk::genre()->getList();
    echo "✅ SDK installed and configured successfully!\n";
    echo "Found " . count($genres) . " genres\n";
} catch (\Exception $e) {
    echo "❌ Configuration error: " . $e->getMessage() . "\n";
}

Development vs Production Setup​

Development Environment​

For development, you might want to:

# Use development API if available
TRADINGCARDAPI_URL=https://dev-api.tradingcardapi.com

# Enable debug mode
APP_DEBUG=true

# Reduce SSL verification for local development (NOT recommended for production)
TRADINGCARDAPI_SSL_VERIFY=false

Production Environment​

For production, ensure:

# Use production API
TRADINGCARDAPI_URL=https://api.tradingcardapi.com

# Always verify SSL in production
TRADINGCARDAPI_SSL_VERIFY=true

# Disable debug mode
APP_DEBUG=false

# Consider increasing timeout for production loads
TRADINGCARDAPI_TIMEOUT=60

Service Provider Registration​

The SDK automatically registers its service provider. If you need to manually register it:

// config/app.php
'providers' => [
    // Other providers...
    CardTechie\TradingCardApiSdk\TradingCardApiSdkServiceProvider::class,
],

Facade Registration​

The facade is also automatically registered. Manual registration:

// config/app.php
'aliases' => [
    // Other aliases...
    'TradingCardApiSdk' => CardTechie\TradingCardApiSdk\Facades\TradingCardApiSdk::class,
],

Troubleshooting Installation​

Common Issues​

1. Composer Installation Fails​

Problem: Composer can't find the package

Could not find package cardtechie/tradingcardapi-sdk-php

Solution: Update Composer and try again

composer self-update
composer clear-cache
composer require cardtechie/tradingcardapi-sdk-php

2. Configuration File Not Published​

Problem: Config file doesn't exist after publishing

Solution: Clear config cache and try again

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

3. Authentication Errors​

Problem: SDK returns authentication errors

Solution: Verify your credentials

# Check your .env file
grep TRADINGCARDAPI .env

# Clear config cache
php artisan config:clear

# Test credentials manually
php artisan tinker
>>> config('tradingcardapi.client_id')
>>> config('tradingcardapi.client_secret')

4. SSL Certificate Errors​

Problem: SSL verification failures in development

Solution: Update certificates or disable SSL verification (development only)

# Temporary fix for development (NOT for production)
TRADINGCARDAPI_SSL_VERIFY=false

For permanent fix, update your system's CA certificates.

Getting Help​

If you encounter issues:

  1. Check the logs: storage/logs/laravel.log
  2. Enable debug mode: Set APP_DEBUG=true in .env
  3. Test connectivity: Use the verification script above
  4. Check GitHub Issues: SDK Issues
  5. Contact support: [email protected]

Next Steps​

After successful installation:

  1. Quick Start Guide - Basic usage patterns
  2. API Resources - Available endpoints and methods
  3. Error Handling - Comprehensive error management
  4. Examples - Real-world use cases