0
# Laravel Echo
1

2
Laravel Echo is a TypeScript/JavaScript library that provides seamless WebSocket integration for Laravel applications, enabling real-time communication through multiple broadcasting drivers including Pusher, Socket.IO, Ably, and Reverb.
3

4
## Package Information
5

6
- **Package Name**: laravel-echo
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install laravel-echo`
10

11
## Core Imports
12

13
```typescript
14
import Echo, { Channel, Connector, EventFormatter, type PresenceChannel } from "laravel-echo";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { default: Echo, Channel, Connector, EventFormatter } = require("laravel-echo");
21
```
22

23
Most common usage:
24

25
```typescript
26
import Echo from "laravel-echo";
27
```
28

29
## Companion Packages
30

31
Laravel Echo includes companion packages for popular frontend frameworks:
32

33
- **@laravel/echo-react**: React hooks for seamless Echo integration including `useEcho`, `useEchoPresence`, `useEchoNotification`, and model-specific hooks
34
- **@laravel/echo-vue**: Vue composables providing similar functionality for Vue.js applications
35

36
Install companion packages separately:
37

38
```bash
39
npm install @laravel/echo-react  # For React
40
npm install @laravel/echo-vue    # For Vue
41
```
42

43
## Basic Usage
44

45
```typescript
46
import Echo from "laravel-echo";
47
import Pusher from "pusher-js";
48

49
// Initialize Echo with Pusher
50
const echo = new Echo({
51
  broadcaster: "pusher",
52
  key: "your-pusher-key",
53
  cluster: "us2",
54
});
55

56
// Listen to public channels
57
echo.channel("orders")
58
  .listen("OrderShipped", (e) => {
59
    console.log("Order shipped:", e.order);
60
  });
61

62
// Join presence channels
63
echo.join("chat.1")
64
  .here((users) => {
65
    console.log("Current users:", users);
66
  })
67
  .joining((user) => {
68
    console.log("User joining:", user);
69
  })
70
  .leaving((user) => {
71
    console.log("User leaving:", user);
72
  });
73

74
// Listen to private channels
75
echo.private("user.1")
76
  .listen("OrderPaid", (e) => {
77
    console.log("Payment received:", e.payment);
78
  });
79
```
80

81
## Architecture
82

83
Laravel Echo is built around several key components:
84

85
- **Echo Class**: Main API for managing WebSocket connections and channel subscriptions
86
- **Broadcasting Drivers**: Support for multiple WebSocket services (Pusher, Socket.IO, Ably, Reverb)
87
- **Channel System**: Different channel types for various use cases (public, private, encrypted, presence)
88
- **Connector Layer**: Abstraction over WebSocket client libraries with consistent API
89
- **HTTP Integration**: Automatic request interceptors for Vue, Axios, jQuery, and Turbo
90
- **Type Safety**: Full TypeScript support with generic types for broadcaster-specific functionality
91

92
## Capabilities
93

94
### Core Echo Interface
95

96
Main Echo class providing connection management and channel access methods. Handles initialization, connection lifecycle, and channel factory methods.
97

98
```typescript { .api }
99
export default class Echo<T extends keyof Broadcaster> {
100
  constructor(options: EchoOptions<T>);
101
  channel(channel: string): Broadcaster[T]["public"];
102
  private(channel: string): Broadcaster[T]["private"];
103
  encryptedPrivate(channel: string): Broadcaster[T]["encrypted"];
104
  join(channel: string): Broadcaster[T]["presence"];
105
  listen(channel: string, event: string, callback: CallableFunction): Broadcaster[T]["public"];
106
  leave(channel: string): void;
107
  leaveChannel(channel: string): void;
108
  leaveAllChannels(): void;
109
  connect(): void;
110
  disconnect(): void;
111
  socketId(): string | undefined;
112
}
113
```
114

115
[Echo Interface](./echo-interface.md)
116

117
### Channel System
118

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

121
```typescript { .api }
122
abstract class Channel {
123
  abstract listen(event: string, callback: CallableFunction): this;
124
  abstract stopListening(event: string, callback?: CallableFunction): this;
125
  abstract subscribed(callback: CallableFunction): this;
126
  abstract error(callback: CallableFunction): this;
127
  listenForWhisper(event: string, callback: CallableFunction): this;
128
  stopListeningForWhisper(event: string, callback?: CallableFunction): this;
129
  notification(callback: CallableFunction): this;
130
}
131

132
interface PresenceChannel extends Channel {
133
  here(callback: CallableFunction): this;
134
  joining(callback: CallableFunction): this;
135
  leaving(callback: CallableFunction): this;
136
  whisper(eventName: string, data: Record<any, any>): this;
137
}
138
```
139

140
[Channel System](./channels.md)
141

142
### Broadcasting Connectors
143

144
WebSocket client abstractions providing consistent APIs across different broadcasting services with automatic authentication and connection management.
145

146
```typescript { .api }
147
abstract class Connector<TBroadcastDriver, TPublic, TPrivate, TPresence> {
148
  constructor(options: EchoOptions<TBroadcastDriver>);
149
  abstract connect(): void;
150
  abstract disconnect(): void;
151
  abstract channel(channel: string): TPublic;
152
  abstract privateChannel(channel: string): TPrivate;
153
  abstract presenceChannel(channel: string): TPresence;
154
  abstract leave(channel: string): void;
155
  abstract leaveChannel(channel: string): void;
156
  abstract socketId(): string | undefined;
157
}
158
```
159

160
[Broadcasting Connectors](./connectors.md)
161

162
### Event Formatting Utilities
163

164
Event name formatting utilities for handling Laravel event namespacing and formatting conventions.
165

166
```typescript { .api }
167
class EventFormatter {
168
  constructor(namespace: string | boolean | undefined);
169
  format(event: string): string;
170
  setNamespace(value: string | boolean): void;
171
}
172

173
function isConstructor(obj: unknown): obj is new (...args: any[]) => any;
174
```
175

176
## Configuration Types
177

178
```typescript { .api }
179
type BroadcastDriver = "pusher" | "reverb" | "ably" | "socket.io" | "null";
180

181
type EchoOptions<T extends keyof Broadcaster> = Broadcaster[T]["options"];
182

183
type Broadcaster = {
184
  reverb: {
185
    connector: PusherConnector<"reverb">;
186
    public: PusherChannel<"reverb">;
187
    private: PusherPrivateChannel<"reverb">;
188
    encrypted: PusherEncryptedPrivateChannel<"reverb">;
189
    presence: PusherPresenceChannel<"reverb">;
190
    options: GenericOptions<"reverb"> & Partial<PusherOptions<"reverb">>;
191
  };
192
  pusher: {
193
    connector: PusherConnector<"pusher">;
194
    public: PusherChannel<"pusher">;
195
    private: PusherPrivateChannel<"pusher">;
196
    encrypted: PusherEncryptedPrivateChannel<"pusher">;
197
    presence: PusherPresenceChannel<"pusher">;
198
    options: GenericOptions<"pusher"> & Partial<PusherOptions<"pusher">>;
199
  };
200
  ably: {
201
    connector: PusherConnector<"pusher">;
202
    public: PusherChannel<"pusher">;
203
    private: PusherPrivateChannel<"pusher">;
204
    encrypted: PusherEncryptedPrivateChannel<"pusher">;
205
    presence: PusherPresenceChannel<"pusher">;
206
    options: GenericOptions<"ably"> & Partial<PusherOptions<"ably">>;
207
  };
208
  "socket.io": {
209
    connector: SocketIoConnector;
210
    public: SocketIoChannel;
211
    private: SocketIoPrivateChannel;
212
    encrypted: never;
213
    presence: SocketIoPresenceChannel;
214
    options: GenericOptions<"socket.io">;
215
  };
216
  null: {
217
    connector: NullConnector;
218
    public: NullChannel;
219
    private: NullPrivateChannel;
220
    encrypted: NullEncryptedPrivateChannel;
221
    presence: NullPresenceChannel;
222
    options: GenericOptions<"null">;
223
  };
224
};
225

226
interface GenericOptions<TBroadcaster extends keyof Broadcaster> {
227
  broadcaster: TBroadcaster;
228
  auth?: { headers: Record<string, string> };
229
  authEndpoint?: string;
230
  userAuthentication?: { endpoint: string; headers: Record<string, string> };
231
  csrfToken?: string | null;
232
  bearerToken?: string | null;
233
  host?: string | null;
234
  key?: string | null;
235
  namespace?: string | false;
236
  withoutInterceptors?: boolean;
237
}
238
```