0
# Channel System
1

2
Comprehensive channel system supporting public, private, encrypted private, and presence channels with event listening and broadcasting capabilities.
3

4
## Capabilities
5

6
### Base Channel Class
7

8
Abstract base class providing common channel functionality for all channel types.
9

10
```typescript { .api }
11
/**
12
 * Base class representing a broadcasting channel
13
 */
14
abstract class Channel {
15
  /** Listen for an event on the channel instance */
16
  abstract listen(event: string, callback: CallableFunction): this;
17
  /** Stop listening to an event on the channel instance */
18
  abstract stopListening(event: string, callback?: CallableFunction): this;
19
  /** Register a callback to be called anytime a subscription succeeds */
20
  abstract subscribed(callback: CallableFunction): this;
21
  /** Register a callback to be called anytime an error occurs */
22
  abstract error(callback: CallableFunction): this;
23
  /** Listen for a whisper event on the channel instance */
24
  listenForWhisper(event: string, callback: CallableFunction): this;
25
  /** Stop listening for a whisper event on the channel instance */
26
  stopListeningForWhisper(event: string, callback?: CallableFunction): this;
27
  /** Listen for Laravel notifications on the channel */
28
  notification(callback: CallableFunction): this;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
// Basic event listening
36
channel.listen("OrderShipped", (e) => {
37
  console.log("Order shipped:", e.order);
38
});
39

40
// Listen for whispers (client-to-client events)
41
channel.listenForWhisper("typing", (e) => {
42
  console.log(`${e.user.name} is typing...`);
43
});
44

45
// Listen for Laravel notifications
46
channel.notification((notification) => {
47
  console.log("Notification received:", notification);
48
});
49

50
// Handle subscription success
51
channel.subscribed(() => {
52
  console.log("Successfully subscribed to channel");
53
});
54

55
// Handle errors
56
channel.error((error) => {
57
  console.error("Channel error:", error);
58
});
59
```
60

61
### Presence Channel Interface
62

63
Interface extending Channel for presence channels with member tracking capabilities.
64

65
```typescript { .api }
66
/**
67
 * Interface representing a presence channel with member tracking
68
 */
69
interface PresenceChannel extends Channel {
70
  /** Register a callback to be called with current channel members */
71
  here(callback: CallableFunction): this;
72
  /** Listen for someone joining the channel */
73
  joining(callback: CallableFunction): this;
74
  /** Listen for someone leaving the channel */
75
  leaving(callback: CallableFunction): this;
76
  /** Send a whisper event to other clients in the channel */
77
  whisper(eventName: string, data: Record<any, any>): this;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
const presenceChannel = echo.join("chat.1");
85

86
// Get current members when joining
87
presenceChannel.here((users) => {
88
  console.log("Current users in chat:", users);
89
  users.forEach(user => {
90
    console.log(`- ${user.name} (${user.id})`);
91
  });
92
});
93

94
// Listen for new members joining
95
presenceChannel.joining((user) => {
96
  console.log(`${user.name} joined the chat`);
97
  displayMessage(`${user.name} joined the chat`);
98
});
99

100
// Listen for members leaving
101
presenceChannel.leaving((user) => {
102
  console.log(`${user.name} left the chat`);
103
  displayMessage(`${user.name} left the chat`);
104
});
105

106
// Send whisper to other clients
107
presenceChannel.whisper("typing", {
108
  user: { id: 1, name: "John" },
109
  timestamp: Date.now()
110
});
111
```
112

113
### Pusher Channel Implementations
114

115
Channel implementations for Pusher-based broadcasters (Pusher, Reverb, Ably).
116

117
```typescript { .api }
118
/**
119
 * Basic Pusher channel for public events
120
 */
121
class PusherChannel<T extends BroadcastDriver> extends Channel {
122
  pusher: Pusher;
123
  name: string;
124
  eventFormatter: EventFormatter;
125
  subscription: PusherChannelInstance;
126
  
127
  constructor(pusher: Pusher, name: string, options: EchoOptionsWithDefaults<T>);
128
  listen(event: string, callback: CallableFunction): this;
129
  stopListening(event: string, callback?: CallableFunction): this;
130
  subscribed(callback: CallableFunction): this;
131
  error(callback: CallableFunction): this;
132
}
133

134
/**
135
 * Private Pusher channel requiring authentication
136
 */
137
class PusherPrivateChannel<T extends BroadcastDriver> extends PusherChannel<T> {
138
  whisper(eventName: string, data: Record<any, any>): this;
139
}
140

141
/**
142
 * Encrypted private Pusher channel with end-to-end encryption
143
 */
144
class PusherEncryptedPrivateChannel<T extends BroadcastDriver> extends PusherPrivateChannel<T> {
145
  // Inherits all private channel functionality with encryption
146
}
147

148
/**
149
 * Presence Pusher channel with member tracking
150
 */
151
class PusherPresenceChannel<T extends BroadcastDriver> extends PusherPrivateChannel<T> implements PresenceChannel {
152
  here(callback: CallableFunction): this;
153
  joining(callback: CallableFunction): this;
154
  leaving(callback: CallableFunction): this;
155
}
156
```
157

158
### Socket.IO Channel Implementations
159

160
Channel implementations for Socket.IO broadcaster.
161

162
```typescript { .api }
163
import type { Socket } from "socket.io-client";
164
/**
165
 * Basic Socket.IO channel for public events
166
 */
167
class SocketIoChannel extends Channel {
168
  socket: Socket;
169
  name: string;
170
  eventFormatter: EventFormatter;
171
  
172
  constructor(socket: Socket, name: string, options: EchoOptionsWithDefaults<"socket.io">);
173
  listen(event: string, callback: CallableFunction): this;
174
  stopListening(event: string, callback?: CallableFunction): this;
175
  subscribed(callback: CallableFunction): this;
176
  error(callback: CallableFunction): this;
177
}
178

179
/**
180
 * Private Socket.IO channel requiring authentication
181
 */
182
class SocketIoPrivateChannel extends SocketIoChannel {
183
  whisper(eventName: string, data: Record<any, any>): this;
184
}
185

186
/**
187
 * Presence Socket.IO channel with member tracking
188
 */
189
class SocketIoPresenceChannel extends SocketIoPrivateChannel implements PresenceChannel {
190
  here(callback: CallableFunction): this;
191
  joining(callback: CallableFunction): this;
192
  leaving(callback: CallableFunction): this;
193
}
194
```
195

196
### Null Channel Implementations
197

198
Mock channel implementations for testing and development.
199

200
```typescript { .api }
201
/**
202
 * Null/mock channel for testing purposes
203
 */
204
class NullChannel extends Channel {
205
  name: string;
206
  
207
  constructor(name: string);
208
  listen(event: string, callback: CallableFunction): this;
209
  stopListening(event: string, callback?: CallableFunction): this;
210
  subscribed(callback: CallableFunction): this;
211
  error(callback: CallableFunction): this;
212
}
213

214
/**
215
 * Null/mock private channel for testing
216
 */
217
class NullPrivateChannel extends NullChannel {
218
  whisper(eventName: string, data: Record<any, any>): this;
219
}
220

221
/**
222
 * Null/mock encrypted private channel for testing
223
 */
224
class NullEncryptedPrivateChannel extends NullPrivateChannel {
225
  // Inherits private channel functionality
226
}
227

228
/**
229
 * Null/mock presence channel for testing
230
 */
231
class NullPresenceChannel extends NullPrivateChannel implements PresenceChannel {
232
  here(callback: CallableFunction): this;
233
  joining(callback: CallableFunction): this;
234
  leaving(callback: CallableFunction): this;
235
}
236
```
237

238
## Channel Usage Patterns
239

240
### Public Channels
241

242
Public channels are accessible to all users without authentication.
243

244
```typescript
245
// Listen to public events
246
echo.channel("orders")
247
  .listen("OrderShipped", (e) => {
248
    console.log("Order shipped:", e.order);
249
  })
250
  .subscribed(() => {
251
    console.log("Successfully subscribed to orders channel");
252
  });
253
```
254

255
### Private Channels  
256

257
Private channels require authentication and are typically user or resource-specific.
258

259
```typescript
260
// Listen to private events
261
echo.private("user.1")
262
  .listen("MessageReceived", (e) => {
263
    console.log("New message:", e.message);
264
  })
265
  .error((error) => {
266
    console.error("Private channel error:", error);
267
  });
268
```
269

270
### Encrypted Private Channels
271

272
Encrypted private channels provide end-to-end encryption (Pusher/Reverb only).
273

274
```typescript
275
// Only available with Pusher/Reverb
276
echo.encryptedPrivate("sensitive-data.1")
277
  .listen("ConfidentialUpdate", (e) => {
278
    console.log("Encrypted data:", e.data);
279
  });
280
```
281

282
### Presence Channels
283

284
Presence channels track who is currently subscribed to the channel.
285

286
```typescript
287
// Full presence channel example
288
const chatChannel = echo.join("chat.general");
289

290
chatChannel
291
  .here((users) => {
292
    console.log("Current users:", users);
293
    updateUserList(users);
294
  })
295
  .joining((user) => {
296
    console.log(`${user.name} joined`);
297
    addUserToList(user);
298
    showNotification(`${user.name} joined the chat`);
299
  })
300
  .leaving((user) => {
301
    console.log(`${user.name} left`);
302
    removeUserFromList(user);
303
    showNotification(`${user.name} left the chat`);
304
  })
305
  .listen("MessageSent", (e) => {
306
    displayMessage(e.message);
307
  })
308
  .listenForWhisper("typing", (e) => {
309
    showTypingIndicator(e.user);
310
  });
311

312
// Send typing indicator to other users
313
function handleTyping() {
314
  chatChannel.whisper("typing", {
315
    user: getCurrentUser(),
316
    timestamp: Date.now()
317
  });
318
}
319
```