README

A modular PHP client designed to facilitate seamless integration with the Ignis platform for managing groups, campaigns, and external communications in Ometra-based systems.

Features

Modular Group Management:
Contract-based (interface-first) group retrieval for flexibility and swapability.
Campaign Management:
Retrieve campaigns assigned to external groups via API endpoints and facade methods.
Auto-registered Routes:
Routes are automatically loaded via ServiceProvider (no manual registration needed).
Facade Access:
Laravel facade for convenient access to client operations from anywhere.
Custom Fields Definition:
Supports custom field schemas for group configurations and campaign-related metadata.
Extensible Service Provider:
Laravel-style ServiceProvider for auto-registration, config publishing, and dependency injection.
Environment-based Configuration:
All credentials and endpoints are environment-driven for secure deployment.
Pluggable Implementation:
Swap group logic using ignis_group_implementation config value (support for mock/test classes and production classes).

Installation

Require via Composer
```
composer require ometra/ignis-client
```
(Laravel) Register Service Provider
The package supports auto-discovery in Laravel.
If not, add to config/app.php:
```
Ometra\IgnisClient\Providers\IgnisServiceProvider::class,
```

Configuration

Publish the configuration file:
```
php artisan vendor:publish --tag=ignis:config
```
This creates a config/ignis.php file:
- base_url: Your Ignis API endpoint, eg: env('IGNIS_BASE_URL')
- ignis_group_implementation: Class name implementing the group contract. Defaults to DummyGroup for dev/testing.
Set your environment variables:
Define at least IGNIS_BASE_URL in your .env file.
Customize contract implementation (optional):

In config/ignis.php, set 'ignis_group_implementation' => YourCustomGroupClass::class

Available Commands

Config publishing:
php artisan vendor:publish --tag=ignis:config

Auto-registered Routes

Routes are automatically loaded by the ServiceProvider:

Method	Endpoint	Controller	Description
GET	`/api/ignis/groups`	`IgnisGroupController@index`	Returns all groups from the configured group implementation

Laravel Facade

Use the IgnisClient facade for quick access to client operations:

use Ometra\IgnisClient\Facades\IgnisClient;

// Get campaigns assigned to a group
$campaigns = IgnisClient::getCampaignsByExternalGroup('external-group-id-123');

// Returns an array of CampaignDTO objects
foreach ($campaigns as $campaign) {
    echo $campaign->name;
    echo $campaign->status;
}

// Post a content hit report
IgnisClient::hitReport([
    ['content_id' => '123', 'played_at' => '2024-01-01 10:00:00'],
]);

Data Structures

ExternalGroupDTO Schema

The standard group representation provided by this client library is the ExternalGroupDTO:

type ExternalGroupDTO = array{
    name: string,
    external_id: string,
    media_type: array<string>, // Example: ['video', 'audio', ...]
    provider_id: string, // Auto-assigned by the client
    play_modifiers?: array<string>, // Optional, list of modifier strings
}

name: Group name.
external_id: External unique identifier.
media_type: Array of strings, typically values like 'video', 'audio', 'image', etc.
provider_id: App name slug, generated internally.
play_modifiers (optional): Optional array of strings. If present and valid, the Ignis host server will interpret them; unrecognized values are ignored.

CampaignDTO Schema

The campaign data transfer object:

type CampaignDTO = array{
    id: string,
    name: string,
    client_id: string,
    dow: string,
    dt_start: string,
    dt_end: string,
    proteus_directory_id?: string,
    created_at?: string,
    updated_at?: string,
    external_group_id?: string,
    status?: string,
    metadata?: array,
    contents?: array,
}

id: Unique campaign identifier.
name: Campaign name.
client_id: Associated client ID.
dow: Day of week (e.g., 'MON', 'TUE').
dt_start: Start date/time.
dt_end: End date/time.
proteus_directory_id (optional): Related Proteus directory.
created_at / updated_at: Timestamps.
external_group_id (optional): Linked external group.
status (optional): Campaign status.
metadata / contents (optional): Additional data.

Example Usage

use Ometra\Ignis\Contracts\IgnisGroupContract;

// Resolve via app container or Laravel's dependency injection
$groups = app(IgnisGroupContract::class)->getGroups();

// Each element is an instance of ExternalGroupDTO (see Data Structures section)
// Manual creation example:
$group = new \Ometra\IgnisClient\DTO\ExternalGroupDTO(
    name: 'Test Group',
    external_id: 'ext-123',
    media_type: ['video'],
    play_modifiers: ['max_rep_count', 'frequency'], // optional
);

ometra / ignis-client

Maintainers

Package info

Statistics

Security