Documentation EN | RU

Laravel + Centrifugo

Centrifugo broadcast driver for Laravel 8.75.0 - 9

Introduction

Centrifugo broadcaster for laravel , based on:

Features

Compatible with latest Centrifugo 3.2.0 🚀
Wrapper over Centrifugo HTTP API 🔌
Authentication with JWT token (HMAC algorithm) for anonymous, authenticated user and private channel 🗝️

Requirements

PHP >= 7.4 , 8.0, 8.1
Laravel 8.75.0 - 10.0
guzzlehttp/guzzle 6 - 7
Centrifugo Server 3.2.0 or newer (see here)

Installation

Require this package with composer:

composer req denis660/laravel-centrifugo

Open your config/app.php and add the following to the providers array:

'providers' => [
    // And uncomment BroadcastServiceProvider
    App\Providers\BroadcastServiceProvider::class,
],

Open your config/broadcasting.php and add new connection like this:

        'centrifugo' => [
            'driver' => 'centrifugo',
            'token_hmac_secret_key'  => env('CENTRIFUGO_TOKEN_HMAC_SECRET_KEY',''),
            'api_key'  => env('CENTRIFUGO_API_KEY',''),
            'url'     => env('CENTRIFUGO_URL', 'http://localhost:8000'), // centrifugo api url
            'verify'  => env('CENTRIFUGO_VERIFY', false), // Verify host ssl if centrifugo uses this
            'ssl_key' => env('CENTRIFUGO_SSL_KEY', null), // Self-Signed SSl Key for Host (require verify=true)
        ],

Also you should add these two lines to your .env file:

CENTRIFUGO_TOKEN_HMAC_SECRET_KEY=token_hmac_secret_key-from-centrifugo-config
CENTRIFUGO_API_KEY=api_key-from-centrifugo-config
CENTRIFUGO_URL=http://localhost:8000

These lines are optional:

CENTRIFUGO_SSL_KEY=/etc/ssl/some.pem
CENTRIFUGO_VERIFY=false

Don't forget to change BROADCAST_DRIVER setting in .env file!

BROADCAST_DRIVER=centrifugo

Basic Usage

To configure Centrifugo server, read official documentation

For broadcasting events, see official documentation of laravel

A simple client usage example:

<?php
declare(strict_types = 1);

namespace App\Http\Controllers;


use denis660\Centrifugo\Centrifugo;
use Illuminate\Support\Facades\Auth;

class ExampleController
{

    public function example(Centrifugo $centrifugo)
    {
        // Send message into channel
        $centrifugo->publish('news', ['message' => 'Hello world']);

        // Generate connection token
        $token = $centrifugo->generateConnectionToken((string)Auth::id(), 0, [
            'name' => Auth::user()->name,
        ]);

        // Generate private channel token
        $apiSign = $centrifugo->generatePrivateChannelToken((string)Auth::id(), 'channel', time() + 5 * 60, [
            'name' => Auth::user()->name,
        ]);

        //Get a list of currently active channels.
        $centrifugo->channels();

        //Get channel presence information (all clients currently subscribed on this channel).
        $centrifugo->presence('news');

    }
}

Available methods

Name	Description
publish(string $channel, array $data, $skipHistory = false)	Send message into channel.
broadcast(array $channels, array $data, $skipHistory = false)	Send message into multiple channel.
presence(string $channel)	Get channel presence information (all clients currently subscribed on this channel).
presenceStats(string $channel)	Get channel presence information in short form (number of clients).
history(string $channel, $limit = 0, $since = [], $reverse = false)	Get channel history information (list of last messages sent into channel).
historyRemove(string $channel)	Remove channel history information.
subscribe(string $channel, string $user, $client = '')	subscribe user from channel.
unsubscribe(string $channel, string $user, string $client = '')	Unsubscribe user from channel.
disconnect(string $user_id)	Disconnect user by it's ID.
channels(string $pattern = '')	Get channels information (list of currently active channels).
info()	Get stats information about running server nodes.
generateConnectionToken(string $userId = '', int $exp = 0, array $info = [], array $channels = [])	Generate connection token.
generatePrivateChannelToken(string $client, string $channel, int $exp = 0, array $info = [])	Generate private channel token.

License

The MIT License (MIT). Please see [License File](https://github.com/denis660/laravel-centrifugo/blob/master/LICENSE for more information.

Centrifugo v3 compatibility

Hello! Currently readme states that this package:

Compatible with latest Centrifugo 2.8.5

Recently we released Centrifugo v3 with many improvements and new features. Unfortunately there are also several backwards incompatible changes. Everything described in Migrating to v3 guide.

Regarding this package I noticed the following things to be updated:

Response format of channels API method changed, and it now accepts pattern argument
Behavior of history API changed - it does not return publications by default, only current stream position, to return publications limit argument must be set to a value greater than 0.
Some additional fields added to publish, broadcast, history methods (though new params fields do not break requests, just extend functionality)
Also, some deprecated option names like secret now removed from Centrifugo, it's now token_hmac_secret_key - so maybe this package should match updated option names.

Would be awesome to have laravel-centrifugo inherit all of this. I am ready to help answering any questions during migration.

And thanks for an awesome package @denis660!

denis660 / laravel-centrifugo Goto Github PK