README

This package provides an easy way to interact with the Dimona API in Laravel applications.

Installation

You can install the package via composer:

composer require hyperlab/laravel-dimona

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-dimona-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-dimona-config"

This is the contents of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | API Endpoints
    |--------------------------------------------------------------------------
    |
    | The endpoints for the Dimona API.
    |
    */

    'endpoint' => env('DIMONA_ENDPOINT', 'https://services.socialsecurity.be/REST/dimona/v2'),

    'oauth_endpoint' => env('DIMONA_OAUTH_ENDPOINT', 'https://services.socialsecurity.be/REST/oauth/v5/token'),

    /*
    |--------------------------------------------------------------------------
    | Default Client
    |--------------------------------------------------------------------------
    |
    | The default client to use when no client is specified.
    |
    */

    'default_client' => env('DIMONA_DEFAULT_CLIENT', 'default'),

    /*
    |--------------------------------------------------------------------------
    | API Clients
    |--------------------------------------------------------------------------
    |
    | Configure multiple API clients with different credentials.
    | Each client has its own client_id, private_key_path, and enterprise_number.
    |
    */

    'clients' => [

        'default' => [
            'client_id' => env('DIMONA_CLIENT_ID'),
            'private_key_path' => env('DIMONA_PRIVATE_KEY_PATH'),
        ],

        // Add more clients as needed:
        // 'client2' => [
        //     'client_id' => env('DIMONA_CLIENT2_ID'),
        //     'private_key_path' => env('DIMONA_CLIENT2_PRIVATE_KEY_PATH'),
        // ],

    ],

];

Usage

Configuration

First, configure your Dimona API credentials in the .env file:

DIMONA_CLIENT_ID=your-client-id
DIMONA_PRIVATE_KEY_PATH=/path/to/your/private-key.pem

For multiple clients, you can configure them in the config/dimona.php file:

'clients' => [
    'default' => [
        'client_id' => env('DIMONA_CLIENT_ID'),
        'private_key_path' => env('DIMONA_PRIVATE_KEY_PATH'),
    ],
    'client2' => [
        'client_id' => env('DIMONA_CLIENT2_ID'),
        'private_key_path' => env('DIMONA_CLIENT2_PRIVATE_KEY_PATH'),
    ],
],

Basic Usage

Call the declare method on the Dimona facade with a period and collection of EmploymentData objects.

use Carbon\CarbonImmutable;
use Carbon\CarbonPeriodImmutable;
use Hyperlab\Dimona\Data\EmploymentData;
use Illuminate\Support\Collection;

$period = CarbonPeriodImmutable::dates(
    CarbonImmutable::startOfWeek(),
    CarbonImmutable::endOfWeek(),
);

$employments = new Collection([
    new EmploymentData(...),
    new EmploymentData(...),
    new EmploymentData(...),
]);

// Declare a Dimona
Dimona::declare($period, $employments);

// Use a specific client
Dimona::client('default')->declare($period, $employments);

Use the HasDimonaPeriods trait in your employment model:

use Hyperlab\Dimona\HasDimonaPeriods;

class Employment extends Model
{
    use HasDimonaPeriods;
}

Events

This package dispatches the following events:

DimonaPeriodCreated

This event is dispatched when a new DimonaPeriod is created.

use Hyperlab\Dimona\Events\DimonaPeriodCreated;

// Listen for the event
Event::listen(function (DimonaPeriodCreated $event) {
    $dimonaPeriod = $event->dimonaPeriod;
    // Your code here
});

DimonaPeriodStateUpdated

This event is dispatched when a DimonaPeriod's state is updated.

use Hyperlab\Dimona\Events\DimonaPeriodStateUpdated;

// Listen for the event
Event::listen(function (DimonaPeriodStateUpdated $event) {
    $dimonaPeriod = $event->dimonaPeriod;
    // Your code here
});

Testing

composer test

Mocking the Dimona API

For testing code that interacts with the Dimona API, you can use the MockDimonaApiClient class:

use Hyperlab\Dimona\Tests\Mocks\MockDimonaApiClient;

// Create a mock client
$mock = new MockDimonaApiClient();

// Mock responses
$mock
    ->mockCreateDeclaration('test-reference')
    ->mockGetDeclaration('test-reference', 'A')
    ->register();

// Now any code that uses DimonaApiClient will use your mock

See the mock documentation for more details.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

hyperlab / laravel-dimona

Maintainers

Details