README

Laravel wrapper for the UCubix PHP Client — provides a service provider, facade, and config file for seamless Laravel integration. No duplicated business logic.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12, or 13

Installation

composer require ucubix/laravel-client

The service provider and facade are auto-discovered. No manual registration needed.

Configuration

Publish the config file:

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

This creates config/ucubix.php. All settings are configurable via environment variables:

UCUBIX_API_KEY=your-api-key
UCUBIX_BASE_URL=https://ucubix.com/api/v1/
UCUBIX_MAX_RETRY=3

Quick Start

use Ucubix\LaravelClient\Facades\Ucubix;

// Get organisation info
$org = Ucubix::getOrganisation();
echo $org->name;

// Search products
$products = Ucubix::getProducts(['search' => 'Cyberpunk']);
foreach ($products->data as $product) {
    echo "{$product->name} ({$product->type})\n";
}

// Get single product with pricing
$product = Ucubix::getProduct('product-uuid');
foreach ($product->regional_pricing as $region) {
    echo "{$region->region_code}: {$region->reseller_wsp} WSP\n";
}

// Create order
$order = Ucubix::createOrder('product-uuid', 1, 'EU', 'DE');
echo "Order {$order->code} — {$order->status}\n";

// Get license keys
$items = Ucubix::getOrderItems($order->id);
foreach ($items->data as $item) {
    if ($item->hasLicenseKey()) {
        $key = Ucubix::getLicenseKey($item->license_key_uuid);
        echo "Key: {$key->license_key}\n";
    }
}

Dependency Injection

use Ucubix\PhpClient\Client\UcubixClient;

class ProductController extends Controller
{
    public function index(UcubixClient $client)
    {
        $products = $client->getProducts(page: 1, perPage: 50);
        
        return response()->json($products->toArray());
    }
}

The UcubixClient is registered as a singleton — the same instance is reused across the request lifecycle.

Facade Reference

The Ucubix facade proxies all methods directly to UcubixClient. All DTOs extend Spatie\LaravelData\Data and support toArray(), toJson(), etc.

Organisation

Products

Product filters: search, category, publisher, developer, franchise, platform

Orders

Order filters: code, external_reference

License Keys

Catalog Dictionaries

Rate Limiting

Pagination

All list endpoints return PaginatedResponse<T>:

$page = 1;
do {
    $products = Ucubix::getProducts(page: $page, perPage: 50);

    foreach ($products->data as $product) {
        // process
    }

    $page++;
} while ($products->hasMorePages());

Error Handling

All exceptions from ucubix/php-client propagate as-is:

use Ucubix\PhpClient\Exceptions\ApiException;
use Ucubix\PhpClient\Exceptions\AuthenticationException;
use Ucubix\PhpClient\Exceptions\RateLimitException;
use Ucubix\PhpClient\Exceptions\ValidationException;

try {
    $order = Ucubix::createOrder($uuid, 5, 'InvalidRegion');
} catch (AuthenticationException $e) {
    // 401/403 — invalid API key or IP not whitelisted
} catch (ValidationException $e) {
    // 422 — validation failed
    echo $e->field;
} catch (RateLimitException $e) {
    // 429 — all retries exhausted
    echo $e->retryAfter;
} catch (ApiException $e) {
    // All other API errors
    echo $e->errorDetail;
}

Rate Limiting

The underlying PHP client has a dual-layer rate limiting system:

1. Client-side sliding window — proactive throttling (default: 100 req/min)
2. Server-side 429 retry — reactive, respects Retry-After header (default: 3 retries)

The UCUBIX_MAX_RETRY config controls the retry count. The sliding window adapts automatically if the server reports a higher limit.

For full rate limiting documentation, see ucubix/php-client.

DTOs

All DTOs are from ucubix/php-client and extend Spatie\LaravelData\Data:

$product = Ucubix::getProduct('uuid');

$product->toArray();  // array
$product->toJson();   // JSON string

// Works seamlessly in responses
return response()->json($product);

For full DTO documentation, see ucubix/php-client DTOs.

Testing

composer install
vendor/bin/phpunit

License

MIT. See LICENSE.