Installation

Install#

flutter pub add magic_socket
dart run magic:dowel plugin:install magic_socket

The installer reads the package's install.yaml and makes two edits: it adds BroadcastServiceProvider to the providers list of lib/config/app.dart, and it adds () => broadcastingConfig to the configFactories of lib/main.dart. It publishes no config file, because broadcastingConfig reads every value from .env and is imported from the package.

The barrel, package:magic_socket/magic_socket.dart, is the only runtime import; everything under src/ is private. Test doubles live in a second barrel, package:magic_socket/testing.dart, see Testing.

Requirements#

Register by Hand#

plugin:install does this for you. To do it yourself, register the provider and the config factory in Magic.init:

import 'package:magic/magic.dart';
import 'package:magic_socket/magic_socket.dart';

Future<void> main() async {
  await Magic.init(
    configFactories: [
      () => broadcastingConfig,
    ],
    configs: [
      {
        'app': {
          'providers': [
            (app) => BroadcastServiceProvider(app),
          ],
        },
      },
    ],
  );
}

Use configFactories, not configs, for broadcastingConfig: it is a getter that calls env(), and a factory runs after .env is loaded. The provider is not auto-registered, so without it Echo finds no broadcasting binding.

Environment#

BROADCAST_CONNECTION=reverb
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=ws
REVERB_APP_KEY=

BROADCAST_CONNECTION defaults to null, which keeps the socket off. Every key and its default is listed in Configuration.

Private and presence channels authorise through POST /broadcasting/auth on your API through Http, and Laravel's toOthers() needs the X-Socket-ID header, so add NetworkServiceProvider to the providers list if the app does not have it yet.

Verify#

import 'package:magic_socket/magic_socket.dart';

Future<void> main() async {
  // Magic.init(...) has run with the provider and config above.
  print(Echo.connection.runtimeType); // NullBroadcastDriver until BROADCAST_CONNECTION=reverb
  print(Echo.socketId); // null until a real connection is up

  // The name must equal the frame's event name, see Channels > Event Names.
  Echo.channel('orders').listen('OrderShipped', (event) => print(event.data));
}

With BROADCAST_CONNECTION=reverb and a server running, the first line prints ReverbBroadcastDriver and Echo.socketId is a string once the handshake completes.

Related Documentation#

• Channels: public, private and presence channels and the BroadcastEvent envelope.
• Configuration: connections, environment keys and the socket id header.
• Listeners: sharing one subscription between controllers.
• Testing: Echo.fake and the assertion helpers.