README

Official PHP client for AmarWave real-time messaging.

Works in any PHP environment — raw PHP, Symfony, or any other framework.

For Laravel projects, install the dedicated amarwave/amarwave-laravel package which adds a service provider, facade, and broadcasting driver.

Requirements

• PHP 8.1+
• ext-curl
• ext-json

Installation

composer require amarwave/amarwave-php

Usage — Raw PHP

<?php

require 'vendor/autoload.php';

use AmarWave\AmarWave;
use AmarWave\AmarWaveException;

$aw = new AmarWave(
    appKey:    'your-app-key',
    appSecret: 'your-app-secret',
    cluster:   'default',
);

// Trigger a single event
$aw->trigger('orders', 'placed', ['order_id' => 42]);

// Trigger multiple events in one request
$aw->triggerBatch([
    ['channel' => 'chat-1', 'event' => 'message', 'data' => ['text' => 'Hello']],
    ['channel' => 'chat-2', 'event' => 'message', 'data' => ['text' => 'World']],
]);

// Error handling
try {
    $aw->trigger('channel', 'event', $data);
} catch (AmarWaveException $e) {
    echo "HTTP {$e->getStatusCode()}: {$e->getMessage()}";
    echo $e->getResponseBody();
}

Usage — Symfony

Register as a service

# config/services.yaml
services:
    AmarWave\AmarWave:
        arguments:
            $appKey:    '%env(AMARWAVE_APP_KEY)%'
            $appSecret: '%env(AMARWAVE_APP_SECRET)%'
            $cluster:   '%env(default:default:AMARWAVE_CLUSTER)%'
            $timeout:   '%env(int:default:10:AMARWAVE_TIMEOUT)%'

# .env
AMARWAVE_APP_KEY=your-app-key
AMARWAVE_APP_SECRET=your-app-secret
AMARWAVE_CLUSTER=default
AMARWAVE_TIMEOUT=10

Inject into a controller

<?php

namespace App\Controller;

use AmarWave\AmarWave;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

class OrderController extends AbstractController
{
    public function __construct(private readonly AmarWave $aw) {}

    #[Route('/orders', methods: ['POST'])]
    public function store(Request $request): JsonResponse
    {
        // ... create order ...

        $this->aw->trigger('orders', 'placed', ['order_id' => $order->getId()]);

        return $this->json($order, 201);
    }
}

Inject into a service

<?php

namespace App\Service;

use AmarWave\AmarWave;

class NotificationService
{
    public function __construct(private readonly AmarWave $aw) {}

    public function notifyUser(int $userId, string $message): void
    {
        $this->aw->trigger("private-user.{$userId}", 'notification', [
            'message' => $message,
        ]);
    }
}

Usage — Slim 4

<?php

use AmarWave\AmarWave;
use Slim\Factory\AppFactory;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;

require 'vendor/autoload.php';

$app = AppFactory::create();

// Register AmarWave in the container
$container = new \DI\Container();
$container->set(AmarWave::class, fn() => new AmarWave(
    appKey:    $_ENV['AMARWAVE_APP_KEY'],
    appSecret: $_ENV['AMARWAVE_APP_SECRET'],
));
AppFactory::setContainer($container);

// Use in a route
$app->post('/orders', function (Request $request, Response $response) {
    $aw = $this->get(AmarWave::class);
    $body = (array) $request->getParsedBody();

    // ... create order ...

    $aw->trigger('orders', 'placed', ['order_id' => $body['id']]);

    $response->getBody()->write(json_encode(['status' => 'ok']));
    return $response->withHeader('Content-Type', 'application/json');
});

$app->run();

Usage — CodeIgniter 4

Create a helper or library

<?php
// app/Libraries/AmarWaveClient.php

namespace App\Libraries;

use AmarWave\AmarWave;

class AmarWaveClient extends AmarWave
{
    public function __construct()
    {
        parent::__construct(
            appKey:    env('amarwave.app_key'),
            appSecret: env('amarwave.app_secret'),
            cluster:   env('amarwave.cluster', 'default'),
        );
    }
}

// app/Config/AmarWave.php
<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class AmarWave extends BaseConfig
{
    public string $appKey    = '';
    public string $appSecret = '';
    public string $cluster   = 'default';
    public int    $timeout   = 10;
}

Use in a controller

<?php

namespace App\Controllers;

use App\Libraries\AmarWaveClient;
use CodeIgniter\Controller;

class OrderController extends Controller
{
    public function create(): string
    {
        $aw = new AmarWaveClient();

        // ... create order ...

        $aw->trigger('orders', 'placed', ['order_id' => 42]);

        return $this->response->setJSON(['status' => 'ok']);
    }
}

Usage — Laminas / Mezzio

Register in a factory

<?php
// src/App/AmarWaveFactory.php

namespace App;

use AmarWave\AmarWave;
use Psr\Container\ContainerInterface;

class AmarWaveFactory
{
    public function __invoke(ContainerInterface $container): AmarWave
    {
        $config = $container->get('config')['amarwave'] ?? [];

        return new AmarWave(
            appKey:    $config['app_key']   ?? '',
            appSecret: $config['app_secret'] ?? '',
            cluster:   $config['cluster']   ?? 'default',
            timeout:   $config['timeout']   ?? 10,
        );
    }
}

// config/autoload/amarwave.global.php
<?php

return [
    'amarwave' => [
        'app_key'    => getenv('AMARWAVE_APP_KEY'),
        'app_secret' => getenv('AMARWAVE_APP_SECRET'),
        'cluster'    => getenv('AMARWAVE_CLUSTER') ?: 'default',
        'timeout'    => 10,
    ],
    'dependencies' => [
        'factories' => [
            \AmarWave\AmarWave::class => \App\AmarWaveFactory::class,
        ],
    ],
];

Use in a handler

<?php

namespace App\Handler;

use AmarWave\AmarWave;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Laminas\Diactoros\Response\JsonResponse;

class OrderHandler implements RequestHandlerInterface
{
    public function __construct(private readonly AmarWave $aw) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        // ... create order ...

        $this->aw->trigger('orders', 'placed', ['order_id' => 42]);

        return new JsonResponse(['status' => 'ok'], 201);
    }
}

Channel Authentication

For private and presence channels, generate an auth token server-side:

// Private channel
$auth = $aw->authenticate($socketId, 'private-orders');
// returns: "appKey:hmac-signature"

// Presence channel
$auth = $aw->authenticatePresence($socketId, 'presence-room.42', [
    'user_id'   => '99',
    'user_info' => ['name' => 'Alice'],
]);
// returns: ['auth' => '...', 'channel_data' => '...']

Constructor Options

Laravel

Use the dedicated Laravel package for full framework integration (service provider, facade, broadcasting driver):

composer require amarwave/amarwave-laravel

See amarwave-laravel for setup.

License

MIT