README

Official Laravel SDK for IssueBadge API.

Requirements

• PHP 8.0 or higher
• Laravel 9.0 or higher

Installation

Install the package via Composer:

composer require issuebadge/laravel-sdk

Configuration

Publish the configuration file:

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

Add your IssueBadge API key to your .env file:

ISSUEBADGE_API_KEY=your-api-key-here

Optional configuration:

ISSUEBADGE_BASE_URL=https://app.issuebadge.com/api/v1
ISSUEBADGE_TIMEOUT=30

Usage

Using the Facade

use IssueBadge\Laravel\Facades\IssueBadge;

// Validate API key
$validation = IssueBadge::validateKey();
echo "User: " . $validation->user->name;

// Get all badges
$badges = IssueBadge::getAllBadges();
foreach ($badges->badges() as $badge) {
    echo $badge->name . " (ID: " . $badge->id . ")\n";
}

// Issue a badge
$response = IssueBadge::issueBadge([
    'name' => 'John Doe',
    'badge_id' => 'W238GD8PK',
    'idempotency_key' => 'unique-key-123',
    'email' => 'john@example.com',
]);

// Issue a badge with auto-generated idempotency key
$response = IssueBadge::issueBadgeWithAutoKey(
    'Jane Smith',
    'W238GD8PK',
    'jane@example.com'
);

Using Dependency Injection

<?php

namespace App\Http\Controllers;

use IssueBadge\Laravel\Http\Client;
use IssueBadge\Laravel\Exceptions\IssueBadgeException;

class BadgeController extends Controller
{
    protected Client $issuebadge;

    public function __construct(Client $issuebadge)
    {
        $this->issuebadge = $issuebadge;
    }

    public function issue()
    {
        try {
            $response = $this->issuebadge->issueBadgeWithAutoKey(
                'John Doe',
                'W238GD8PK',
                'john@example.com'
            );
            
            return response()->json([
                'success' => true,
                'message' => $response->message
            ]);
        } catch (IssueBadgeException $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage()
            ], $e->getStatusCode() ?: 400);
        }
    }
}

Console Commands

The package provides several Artisan commands:

Validate API Key

php artisan issuebadge:validate-key

List All Badges

php artisan issuebadge:list-badges

Issue a Badge

php artisan issuebadge:issue "John Doe" W238GD8PK john@example.com

With custom idempotency key:

php artisan issuebadge:issue "John Doe" W238GD8PK john@example.com --idempotency-key="custom-key-123"

Data Transfer Objects (DTOs)

ValidateKeyResponse

$response = IssueBadge::validateKey();

// Properties
$response->success;      // bool
$response->message;      // string
$response->user;         // ?User
$response->tokenInfo;    // ?TokenInfo

// User properties
$response->user->id;     // int
$response->user->name;   // string
$response->user->email;  // string

// TokenInfo properties
$response->tokenInfo->name;      // string
$response->tokenInfo->createdAt; // string

BadgesResponse

$response = IssueBadge::getAllBadges();

// Properties
$response->success;  // bool
$response->message;  // string
$response->badges(); // Collection<Badge>

// Badge properties
foreach ($response->badges() as $badge) {
    $badge->id;   // string
    $badge->name; // string
}

IssueResponse

$response = IssueBadge::issueBadge([...]);

// Properties
$response->success; // bool
$response->message; // string
$response->data;    // mixed (optional)

Error Handling

The SDK throws IssueBadgeException for all API-related errors:

use IssueBadge\Laravel\Exceptions\IssueBadgeException;

try {
    $response = IssueBadge::validateKey();
} catch (IssueBadgeException $e) {
    $message = $e->getMessage();
    $statusCode = $e->getStatusCode();
    
    // Handle the error
    Log::error('IssueBadge API error', [
        'message' => $message,
        'status' => $statusCode
    ]);
}

Testing

Run the test suite:

composer test

License

This SDK is released under the MIT License.