PHPackages                             redeemly/catalogue - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. redeemly/catalogue

ActiveLibrary[API Development](/categories/api)

redeemly/catalogue
==================

Laravel package for Redeemly Catalogue services integration

00PHP

Since Feb 19Pushed 4mo agoCompare

[ Source](https://github.com/Redeemly-LikeCard/RD-catalogue)[ Packagist](https://packagist.org/packages/redeemly/catalogue)[ RSS](/packages/redeemly-catalogue/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

Redeemly Catalogue Integration for Laravel
==========================================

[](#redeemly-catalogue-integration-for-laravel)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/5fe05c705bf034839bda7651781e4d0a9d42f4a840478ca5e343873a0361bb89/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322b2d626c75652e737667)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/b7bd8c10f88035d2b0039e09cc47b4c71a6f3d85267e3efe9a9118631e0e8dae/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825323025374325323031312e782d7265642e737667)](https://laravel.com)[![GitHub Repo](https://camo.githubusercontent.com/f6d0295ba7c3222a3acfe2d00bdf1e338c4ef2dfebec660ac0d0a0a5467e88b1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4769744875622d52656465656d6c792d2d6875622f436174616c6f75676550616b6167652d677265656e2e737667)](https://github.com/Redeemly-hub/CatalougePakage)

A comprehensive Laravel package for seamless integration with Redeemly Catalogue services. Designed for enterprise customer projects with production-ready features including automatic token management, comprehensive error handling, and full API coverage.

🚀 Features
----------

[](#-features)

- � **Easy Integration** - Seamless integration with Redeemly Catalogue API
- 🔐 **Automatic Token Management** - Smart token caching and refresh
- 📱 **Laravel Ready** - Built for Laravel 10.x and 11.x with auto-discovery
- 🎯 **Production Ready** - Enterprise-grade error handling and logging
- 📝 **Full API Coverage** - Complete catalogue, SKU pull, and customer logs
- 🔄 **Retry Logic** - Automatic retry with configurable attempts
- 📊 **Comprehensive Logging** - Detailed request/response logging
- 🧪 **Test Dashboard** - Built-in testing interface for development
- ⚡ **Performance Optimized** - Intelligent caching and connection pooling

📋 Requirements
--------------

[](#-requirements)

- PHP 8.2 or higher
- Laravel 10.x or 11.x
- Composer

📦 Installation
--------------

[](#-installation)

### Option 1: Install via Composer (Recommended)

[](#option-1-install-via-composer-recommended)

```
composer require redeemly/catalogue-integration
```

*Note: This will be available after publishing to Packagist*

### Option 2: Install from GitHub

[](#option-2-install-from-github)

```
composer require redeemly-hub/catalougepakage:dev-master
```

### Step 2: Publish Configuration (Optional)

[](#step-2-publish-configuration-optional)

```
php artisan vendor:publish --provider="Redeemly\CatalogueIntegration\Providers\CatalogueIntegrationServiceProvider" --tag="catalogue-config"
```

### Step 3: Configure Environment Variables

[](#step-3-configure-environment-variables)

Add the following to your `.env` file:

```
# Catalogue Integration Configuration
CATALOGUE_API_BASE_URL=https://api-stg-luckycode.redeemly.com
CATALOGUE_API_KEY=your_api_key_here
CATALOGUE_CLIENT_ID=your_client_id_here
CATALOGUE_HTTP_TIMEOUT=30
CATALOGUE_CACHE_ENABLED=true
CATALOGUE_CACHE_TTL=3600
CATALOGUE_ROUTES_AUTO_LOAD=true
```

CATALOGUE\_CLIENT\_ID=your\_client\_id\_here CATALOGUE\_HTTP\_TIMEOUT=30 CATALOGUE\_CACHE\_ENABLED=true CATALOGUE\_CACHE\_TTL=3600 CATALOGUE\_ROUTES\_AUTO\_LOAD=true

```

### Automatic Route Loading

By default, the package automatically loads API routes with the prefix `api/catalogue`. The routes include:

- `POST /api/catalogue/external-sign-in` - Authenticate and get token
- `GET /api/catalogue/catalogue` - Retrieve catalogue vouchers
- `POST /api/catalogue/pull-sku` - Pull SKU codes
- `GET /api/catalogue/customer-log` - Get customer transaction logs
- `GET /api/catalogue/token` - Get current access token

**To disable automatic route loading:**

```env
CATALOGUE_ROUTES_AUTO_LOAD=false

```

Then manually add routes as shown below.

### Step 4: Service Provider Registration (Laravel < 11 only)

[](#step-4-service-provider-registration-laravel--11-only)

For Laravel versions below 11, add the service provider to `config/app.php`:

```
'providers' => [
    // ... other providers
    Redeemly\CatalogueIntegration\Providers\CatalogueIntegrationServiceProvider::class,
],
```

⚙️ Configuration
----------------

[](#️-configuration)

The package provides comprehensive configuration options in `config/catalogue.php`:

### API Configuration

[](#api-configuration)

```
'base_url' => env('CATALOGUE_API_BASE_URL', 'https://api-stg-luckycode.redeemly.com'),
'credentials' => [
    'api_key' => env('CATALOGUE_API_KEY'),
    'client_id' => env('CATALOGUE_CLIENT_ID'),
],
```

### HTTP Client Settings

[](#http-client-settings)

```
'http' => [
    'timeout' => env('CATALOGUE_HTTP_TIMEOUT', 30),
    'retry_times' => env('CATALOGUE_HTTP_RETRY_TIMES', 3),
    'retry_delay' => env('CATALOGUE_HTTP_RETRY_DELAY', 1000),
],
```

### Caching Configuration

[](#caching-configuration)

```
'cache' => [
    'enabled' => env('CATALOGUE_CACHE_ENABLED', true),
    'ttl' => env('CATALOGUE_CACHE_TTL', 3600),
    'key' => env('CATALOGUE_CACHE_KEY', 'catalogue_access_token'),
],
```

🚀 Usage
-------

[](#-usage)

### Using the Facade (Recommended)

[](#using-the-facade-recommended)

```
use Redeemly\CatalogueIntegration\Facades\Catalogue;

class VoucherController extends Controller
{
    public function index()
    {
        // Get catalogue vouchers
        $response = Catalogue::getCatalogue();

        if ($response->success) {
            $vouchers = $response->data;
            return view('vouchers.index', compact('vouchers'));
        }

        return back()->withErrors(['error' => $response->error->message]);
    }

    public function pullSku(Request $request)
    {
        $skuRequest = new RequestSKUDto(
            voucherId: $request->voucher_id,
            quantity: $request->quantity,
            orderRef: $request->order_reference,
            customerRef: $request->customer_reference
        );

        $response = Catalogue::pullSku($skuRequest);

        if ($response->success) {
            return response()->json([
                'success' => true,
                'data' => $response->data
            ]);
        }

        return response()->json([
            'success' => false,
            'error' => $response->error->message
        ], 400);
    }
}
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use Redeemly\CatalogueIntegration\Services\CatalogueService;

class CatalogueManager
{
    public function __construct(
        private CatalogueService $catalogueService
    ) {}

    public function getCustomerLogs(string $customerRef, int $page = 1, int $limit = 10)
    {
        $query = new CustomerLogQueryDto(
            page: $page,
            pageSize: $limit,
            customerRef: $customerRef
        );

        return $this->catalogueService->getCustomerLog($query);
    }
}
```

### Optional: Publish Routes

[](#optional-publish-routes)

To publish the API routes to your project:

```
php artisan vendor:publish --provider="Redeemly\CatalogueIntegration\Providers\CatalogueIntegrationServiceProvider" --tag="catalogue-routes"
```

This will create `routes/catalogue.php` in your project. You can then include it in your main routes file:

```
// In routes/api.php or routes/web.php
require __DIR__.'/catalogue.php';
```

### Using the Built-in API Routes

[](#using-the-built-in-api-routes)

Add these routes to your `routes/api.php` for quick API access:

```
use Redeemly\CatalogueIntegration\Http\Controllers\CatalogueController;

Route::prefix('api/catalogue')->middleware(['auth:sanctum'])->group(function () {
    Route::post('external-sign-in', [CatalogueController::class, 'externalSignIn']);
    Route::get('catalogue', [CatalogueController::class, 'getCatalogue']);
    Route::post('pull-sku', [CatalogueController::class, 'pullSku']);
    Route::get('customer-log', [CatalogueController::class, 'getCustomerLog']);
    Route::get('token', [CatalogueController::class, 'getToken']);
});
```

**Note:** Routes are not loaded automatically by the package. You must manually add them or publish them to maintain full control over your application's routing.

📚 API Reference
---------------

[](#-api-reference)

### CatalogueService Methods

[](#catalogueservice-methods)

#### `externalSignIn(ExternalSignInDto $dto): ApiResponse`

[](#externalsigninexternalsignindto-dto-apiresponse)

Authenticate and get access token.

#### `getCatalogue(): ApiResponse`

[](#getcatalogue-apiresponse)

Retrieve all available catalogue vouchers.

#### `pullSku(RequestSKUDto $dto): ApiResponse`

[](#pullskurequestskudto-dto-apiresponse)

Pull SKU codes for a specific voucher.

#### `getCustomerLog(CustomerLogQueryDto $dto): ApiResponse`

[](#getcustomerlogcustomerlogquerydto-dto-apiresponse)

Get customer transaction logs with pagination.

#### `ensureValidToken(): string`

[](#ensurevalidtoken-string)

Get a valid cached token or fetch new one.

#### `clearTokenCache(): void`

[](#cleartokencache-void)

Clear the cached access token.

### Data Transfer Objects (DTOs)

[](#data-transfer-objects-dtos)

#### ExternalSignInDto

[](#externalsignindto)

```
$signIn = new ExternalSignInDto(
    apiKey: 'your-api-key',
    clientId: 'your-client-id'
);
```

#### RequestSKUDto

[](#requestskudto)

```
$skuRequest = new RequestSKUDto(
    voucherId: 'voucher-123',      // Required
    quantity: 5,                   // Required
    orderRef: 'order-456',         // Optional
    customerRef: 'customer-789',   // Optional
    transactionId: 'txn-123'       // Optional
);
```

#### CustomerLogQueryDto

[](#customerlogquerydto)

```
$query = new CustomerLogQueryDto(
    page: 1,                       // Optional, default: 1
    pageSize: 10,                  // Optional, default: 10
    customerRef: 'customer-789',   // Optional
    type: 2                        // Optional: 1=New, 2=Revealed, 3=Redeemed, 4=Expired
);
```

### ApiResponse Structure

[](#apiresponse-structure)

All methods return an `ApiResponse` object:

```
class ApiResponse
{
    public bool $success;
    public ?ErrorDto $error;
    public mixed $data;
    public ?string $sourceProvider;

    public function toArray(): array;
}
```

🧪 Testing
---------

[](#-testing)

### Test Dashboard

[](#test-dashboard)

Access the built-in test dashboard during development:

```
http://your-app.test/test-dashboard

```

### Running Tests

[](#running-tests)

```
# Run package tests
composer test

# Run Laravel tests including package
php artisan test
```

### Manual Testing

[](#manual-testing)

```
// Using Tinker
php artisan tinker

>>> use Redeemly\CatalogueIntegration\Facades\Catalogue;
>>> $response = Catalogue::getCatalogue();
>>> $response->success ? $response->data : $response->error->message;
```

📊 Error Handling
----------------

[](#-error-handling)

The package provides comprehensive error handling:

```
$response = Catalogue::getCatalogue();

if (!$response->success) {
    // Handle error
    Log::error('Catalogue API Error', [
        'message' => $response->error->message,
        'code' => $response->error->code,
        'source' => $response->sourceProvider
    ]);

    // Show user-friendly message
    return back()->withErrors(['catalogue' => 'Unable to load catalogue. Please try again.']);
}
```

🔍 Logging
---------

[](#-logging)

All API requests and errors are automatically logged:

- **Request Logs**: Include endpoint, parameters, and timing
- **Error Logs**: Include full error details and stack traces
- **Token Logs**: Secure token logging (first 20 characters only)

Configure logging in `config/logging.php` as needed.

🔧 Advanced Configuration
------------------------

[](#-advanced-configuration)

### Custom HTTP Client

[](#custom-http-client)

```
// In service provider
public function register()
{
    $this->app->bind(CatalogueService::class, function ($app) {
        $config = config('catalogue');

        // Custom Guzzle client
        $httpClient = new \GuzzleHttp\Client([
            'base_uri' => $config['base_url'],
            'timeout' => $config['http']['timeout'],
            'proxy' => $config['http']['proxy'] ?? null, // Add proxy support
        ]);

        return new CatalogueService(
            $config['base_url'],
            $config['credentials'],
            $config['http'],
            $app->make(\Illuminate\Contracts\Cache\Repository::class)
        );
    });
}
```

### Custom Cache Store

[](#custom-cache-store)

```
// Use Redis for token caching
CATALOGUE_CACHE_STORE=redis
CATALOGUE_CACHE_KEY=catalogue:token
```

🤝 Contributing
--------------

[](#-contributing)

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

[](#development-setup)

```
# Clone repository
git clone https://github.com/redeemly-hub/CatalougePakage.git

# Install dependencies
composer install

# Run tests
composer test

# Run linting
composer lint
```

📝 Changelog
-----------

[](#-changelog)

### v1.0.0 (Current)

[](#v100-current)

- Initial release with full API integration
- Automatic token management
- Comprehensive error handling
- Laravel 10.x and 11.x support
- Built-in test dashboard

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

🏢 About Redeemly
----------------

[](#-about-redeemly)

Redeemly provides enterprise voucher and catalogue management solutions. This package is part of our Laravel integration suite designed for seamless API connectivity.

📞 Support
---------

[](#-support)

- 📧 **Email**:
- 📚 **Documentation**: [Redeemly Developer Portal](https://developers.redeemly.com)
- 🐛 **Issues**: [GitHub Issues](https://github.com/redeemly-hub/CatalougePakage/issues)

---

**Made with ❤️ by Redeemly Team**

###  Health Score

17

—

LowBetter than 6% of packages

Maintenance51

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/0216c07a65da9ecdd4f0b341afd69d511e9d813bc1325397d01cb70316d873f2?d=identicon)[redeemly-likecard](/maintainers/redeemly-likecard)

---

Top Contributors

[![Redeemly-LikeCard](https://avatars.githubusercontent.com/u/239739905?v=4)](https://github.com/Redeemly-LikeCard "Redeemly-LikeCard (3 commits)")

### Embed Badge

![Health badge](/badges/redeemly-catalogue/health.svg)

```
[![Health](https://phpackages.com/badges/redeemly-catalogue/health.svg)](https://phpackages.com/packages/redeemly-catalogue)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k13](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)