Channels

Basic Usage#

import 'package:magic_socket/magic_socket.dart';

void main() {
  Echo.channel('orders').listen('OrderShipped', (event) {
    print('Order ${event.data['id']} has shipped');
  });

  Echo.leave('orders');
}

Echo is a static facade over the BroadcastManager bound at broadcasting. It follows the shape of the Laravel Echo client (channel, private, join, listen and leave) with differences, the first being event names. With the null driver the calls succeed and no event ever arrives, so the same code runs in development without a server.

Quick Reference#

Event Names#

listen compares the name you pass with the event name in the frame, exactly. Echo JS prepends the event's namespace for you; this driver does not. Laravel names a frame by broadcastAs() when the event has one and by its full class name when it has none, so a handler registered for 'OrderShipped' never runs for a default App\Events\OrderShipped.

Name the event on the server and pass the same string to listen:

use Illuminate\Broadcasting\Channel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;

class OrderShipped implements ShouldBroadcast
{
    public function broadcastOn(): Channel
    {
        return new Channel('orders');
    }

    public function broadcastAs(): string
    {
        return 'OrderShipped';
    }
}

import 'package:magic_socket/magic_socket.dart';

void main() {
  Echo.channel('orders').listen('OrderShipped', (event) => print(event.data));

  // Without broadcastAs() on the server, pass the full class name instead.
  Echo.channel('orders').listen(r'App\Events\OrderShipped', (event) => print(event.data));
}

Echo's leading-dot form (.OrderShipped) is not needed and not recognised: pass the name as the frame carries it. Every other sample on this page assumes the event has a broadcastAs() equal to the name shown.

Public Channels#

Any connected client may subscribe to a public channel.

import 'package:magic_socket/magic_socket.dart';

void main() {
  void onShipped(BroadcastEvent event) => print(event.data);
  void onCancelled(BroadcastEvent event) => print(event.data);

  Echo.channel('orders')
      .listen('OrderShipped', onShipped)
      .listen('OrderCancelled', onCancelled);

  Echo.channel('orders').stopListening('OrderShipped');
}

A second listen for the same event on the same channel replaces the first handler. To fan one event out to several handlers, use BroadcastListeners.

Private Channels#

A private channel performs an HTTP handshake before it subscribes: the driver posts socket_id and channel_name to the auth_endpoint (/broadcasting/auth by default) through Http, and expects {"auth": "..."} back.

import 'package:magic_socket/magic_socket.dart';

void main() {
  Echo.private('user.1').listen('ProfileUpdated', (event) {
    print('Profile updated: ${event.data}');
  });
}

The server decides who may join, in Laravel's routes/channels.php:

Broadcast::channel('user.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});

The request goes through your Http stack, so the user's bearer token reaches the auth route like any other call. A refusal (401, 403) is logged and not retried; a missing response or a 5xx is retried with the reconnect backoff, see Connection.

Presence Channels#

A presence channel is a private channel that also tracks who is in it.

import 'package:magic_socket/magic_socket.dart';

void main() {
  final room = Echo.join('room.1');

  print('Online: ${room.members.length}');

  room.onJoin.listen((member) => print('${member['name']} joined'));
  room.onLeave.listen((member) => print('${member['name']} left'));
  room.listen('MessagePosted', (event) => print(event.data['body']));
}

The BroadcastEvent Envelope#

Every handler receives a BroadcastEvent.

Every frame the server sends reaches your handler, including one whose payload repeats an earlier frame. The server can also deliver an event twice when a queued broadcast job is retried. Write handlers so a second delivery is harmless: refetch, or upsert by an id in the payload, rather than counting or showing a toast per frame.

Subscription State#

A connected driver does not mean a subscribed channel: a private channel still waits on its auth call, and a refusal leaves it unsubscribed. Each channel reports the server's confirmation itself.

import 'package:magic_socket/magic_socket.dart';

void main() {
  final channel = Echo.private('team.1');

  print(channel.isSubscribed); // true once the server sent subscription_succeeded

  channel.onSubscriptionChanged.listen((subscribed) {
    print(subscribed ? 'stop polling' : 'start polling');
  });
}

onSubscriptionChanged emits only on a change and never replays, so read isSubscribed when you attach. Channels of the null driver are never subscribed.

Gotchas#

Related Documentation#

• Configuration: connections, environment keys and the socket id header.
• Listeners: sharing a channel between controllers.
• Connection: lifecycle, reconnects and auth failures.
• Testing: faking channels and delivering events in a test.