README

Symfony bundle to integrate the Notifuse API in your application. It focuses on:

A small, explicit HTTP client wrapper for the Notifuse API (Service\ApiClient).
A thin configuration layer (DI extension + YAML) to keep endpoints and options fully configurable. The Notification Center UI embed is handled directly by Notifuse’s front-end script and is not part of this bundle.

The bundle does not hide Symfony’s HttpClient. Instead, it applies the base URL, headers and common options for you, and gives you escape hatches to pass per‑request options when needed.

How It Works

Configuration is declared under the notifuse key and loaded by DependencyInjection\NotifuseExtension.
Services are registered in Resources/config/services.yaml and autowired into your code.
Service\ApiClient prefixes requests with api_base_url, injects authentication headers (Authorization: Bearer …, X-Workspace-ID) and merges configured HTTP client options. The UI widget is not generated by this bundle; integrate the Notification Center via Notifuse's front-end script.

Installation

Install from your application root:

composer require obsidiane/notifuse-symfony-bundle

If you are not using Symfony Flex auto‑registration, enable the bundle in the kernel:

return [
    // ...
    Obsidiane\Notifuse\NotifuseBundle::class => ['all' => true],
];

Configuration

Minimal configuration via environment variables:

notifuse:
  api_base_url: '%env(NOTIFUSE_API_BASE_URL)%'
  workspace_id: '%env(NOTIFUSE_WORKSPACE_ID)%'
  workspace_api_key: '%env(NOTIFUSE_API_KEY)%'
  http_client_options:
    timeout: 10.0
    max_redirects: 5
    verify_peer: true
    headers: { }
# The Notification Center embed is configured and loaded via Notifuse’s own front-end script.

Option reference:

api_base_url: Base URL for the Notifuse API (e.g. https://api.notifuse.com).
workspace_id: Your workspace identifier; sent as header and embed parameter.
workspace_api_key: Bearer token used for API calls; keep it in env/secrets.
http_client_options: Subset of Symfony HttpClient options applied to every call (timeout, max_redirects, verify_peer, headers). You can still override them per request. The Notification Center script and container are not managed by this bundle.

API Usage

Inject Service\ApiClient and call request($method, $endpoint, $options = []). The $endpoint is appended to api_base_url.

use Obsidiane\Notifuse\ApiClient;

final class MyService
{
    public function __construct(private ApiClient $apiClient) {}

    public function ping(): array
    {
        // Performs GET https://…/api/workspace.status with auth headers
        return $this->apiClient->request('GET', '/api/workspace.status');
    }

    public function createSomething(array $payload): array
    {
        return $this->apiClient->request('POST', '/api/something', [
            'json' => $payload,
            // Optional per‑request overrides
            'headers' => [ 'X-Client-Name' => 'my-app' ],
            'timeout' => 8.0,
        ]);
    }
}

Error handling: network/HTTP client errors are wrapped in Service\Exception\NotifuseClientException with the original exception as previous. Catch it at your boundary if you want to map to domain errors.

try {
    $data = $this->apiClient->request('GET', '/api/workspace.status');
} catch (\Obsidiane\Notifuse\Exception\NotifuseClientException $e) {
    // Log and render a user‑friendly message
}

Endpoint Helpers

The ApiClient exposes convenience methods for all Notifuse endpoints:

sendTransactional(array $notification, ?string $workspaceId = null, array $options = []): POST /api/transactional.send
upsertContact(array $contact, ?string $workspaceId = null, array $options = []): POST /api/contacts.upsert
getContactByEmail(string $email, ?string $workspaceId = null, array $options = []): GET /api/contacts.getByEmail
getContactByExternalId(string $externalId, ?string $workspaceId = null, array $options = []): GET /api/contacts.getByExternalID
importContacts(array $contacts, array $subscribeToLists = [], ?string $workspaceId = null, array $options = []): POST /api/contacts.import
deleteContact(string $email, ?string $workspaceId = null, array $options = []): POST /api/contacts.delete
updateContactListStatus(string $email, string $listId, string $status, ?string $workspaceId = null, array $options = []): POST /api/contactLists.updateStatus
publicSubscribeToLists(array $contact, array $listIds, ?string $workspaceId = null, array $options = []): POST /subscribe (no auth header sent)

Examples:

// 1) Send transactional notification
$client->sendTransactional([
    'id' => 'welcome_email',
    'contact' => ['email' => 'user@example.com'],
    'channels' => ['email'],
    'data' => ['user_name' => 'John'],
]);

// 2) Upsert a contact
$client->upsertContact([
    'email' => 'user@example.com',
    'first_name' => 'John',
]);

// 3) Get a contact
$client->getContactByEmail('user@example.com');
$client->getContactByExternalId('user_123');

// 4) Import contacts in batch
$client->importContacts([
    ['email' => 'user1@example.com'],
    ['email' => 'user2@example.com'],
], ['newsletter']);

// 5) Delete a contact
$client->deleteContact('user@example.com');

// 6) Update list subscription status
$client->updateContactListStatus('user@example.com', 'newsletter', 'active');

// 7) Public subscription (no Authorization header)
$client->publicSubscribeToLists([
    'email' => 'user@example.com',
], ['newsletter']);

Embedding the Notification Center

The UI embed is not handled by this bundle. Include Notifuse’s front-end script directly where you need the Notification Center.

HTTP Client Options

Global defaults are provided via notifuse.http_client_options. You can still override on each call via $options in ApiClient::request().

Common examples:

notifuse:
  http_client_options:
    timeout: 8.0
    verify_peer: true
    headers:
      X-Client-Name: 'my-app'

$this->apiClient->request('GET', '/api/endpoint', [
    'headers' => ['Accept-Language' => 'fr'],
    'timeout' => 5.0,
]);

Compatibility

PHP: ^8.1
Symfony: ^6.4 or ^7.0

Services Summary

Service ID	Class	Description
`Obsidiane\Notifuse\ApiClient`	`Service\ApiClient`	Authenticated requests to the Notifuse API.

CI, Releases and Composer Registry

The pipeline validates the package on all branches and, on the default branch, computes a semantic version and creates a GitLab Release and tag. A separate job then notifies the GitLab Composer registry with the same version so consumers can install it via Composer.

See .gitlab-ci.yml for job names and the exact flow (define-version-app, release-production, publish-composer).

Testing

This bundle does not ship with its own test-suite. When writing tests in your application, you can mock HttpClientInterface and assert:

URL resolution/headers in ApiClient::request().

obsidiane / notifuse-symfony-bundle

Maintainers

Details