브로드캐스팅

번역일: 2026년 6월 25일

브로드캐스팅

소개
서버 사이드 설치
클라이언트 사이드 설치
개념 개요
- 예제 애플리케이션으로 살펴보기
브로드캐스트 이벤트 정의
채널 인증
이벤트 브로드캐스팅
- 다른 사용자에게만 전송
- 커넥션 커스터마이징
브로드캐스트 수신
Presence 채널
모델 브로드캐스팅
- 모델 브로드캐스팅 컨벤션
- 모델 브로드캐스트 리스닝
클라이언트 이벤트
알림

소개

현대적인 웹 애플리케이션에서는 WebSocket을 활용해 페이지를 새로 고침하지 않고도 실시간으로 UI를 갱신하는 기능이 점점 일반화되고 있습니다. 서버에서 데이터가 변경되면 WebSocket 연결을 통해 클라이언트에 메시지를 전달하는 방식으로, 클라이언트가 서버에 반복적으로 폴링(polling)하는 방식보다 훨씬 효율적입니다.

예를 들어, 사용자의 데이터를 CSV로 내보내 이메일로 전송하는 기능을 구현한다고 가정해 보겠습니다. CSV 생성에 몇 분이 걸릴 수 있으므로 큐 Job으로 처리합니다. 작업이 완료되면 App\Events\UserDataExported 이벤트를 브로드캐스트하여 JavaScript 쪽에서 이를 수신하고, 사용자에게 페이지 새로 고침 없이 "CSV 파일이 이메일로 전송되었습니다"라는 메시지를 보여줄 수 있습니다.

Laravel의 이벤트 브로드캐스팅은 서버 사이드의 이벤트를 WebSocket을 통해 클라이언트로 전달하는 기능을 제공합니다. 서버와 클라이언트가 동일한 이벤트 이름과 데이터 구조를 공유하므로, 일관성 있는 실시간 기능을 손쉽게 구축할 수 있습니다.

핵심 개념은 간단합니다. 클라이언트(프런트엔드)는 특정 이름의 채널에 구독하고, Laravel 백엔드는 해당 채널로 이벤트를 브로드캐스트합니다. 이벤트에는 원하는 데이터를 자유롭게 담을 수 있습니다.

지원 드라이버

Laravel은 기본적으로 세 가지 서버 사이드 브로드캐스팅 드라이버를 제공합니다: Laravel Reverb, Pusher Channels, Ably.

NOTE

이벤트 브로드캐스팅을 시작하기 전에 Laravel의 이벤트와 리스너 문서를 먼저 읽어두시길 권장합니다.

서버 사이드 설치

이벤트 브로드캐스팅을 사용하려면 Laravel 애플리케이션 설정과 몇 가지 패키지 설치가 필요합니다.

브로드캐스팅은 서버 사이드 드라이버가 이벤트를 WebSocket 서버로 전송하고, 클라이언트의 Laravel Echo(JavaScript 라이브러리)가 이를 수신하는 구조로 동작합니다. 아래에서 설치 과정을 단계별로 안내합니다.

설정

브로드캐스팅 관련 설정은 config/broadcasting.php에 모두 모여 있습니다. Laravel은 Pusher Channels, Redis, 로컬 개발·디버깅용 log 드라이버를 기본 지원합니다. 테스트 시 브로드캐스팅을 완전히 비활성화하는 null 드라이버도 포함되어 있습니다. 각 드라이버별 설정 예시가 config/broadcasting.php 안에 준비되어 있습니다.

Broadcast 서비스 프로바이더

이벤트를 브로드캐스트하기 전에 App\Providers\BroadcastServiceProvider를 등록해야 합니다. 새 Laravel 프로젝트라면 config/app.php의 providers 배열에서 해당 프로바이더의 주석을 해제하기만 하면 됩니다. 이 서비스 프로바이더는 브로드캐스트 인증 라우트와 콜백 등록에 필요한 코드를 포함합니다.

큐 설정

이벤트 브로드캐스팅은 모두 큐를 통해 처리됩니다. 브로드캐스팅이 애플리케이션 응답 속도에 영향을 주지 않도록, 큐 워커를 설정하고 실행해야 합니다.

Reverb

Composer를 통해 Reverb 패키지를 설치합니다:

composer require laravel/reverb

설치 후, 아래 Artisan 명령어를 실행하면 설정 파일이 퍼블리시되고, 브로드캐스팅 설정이 업데이트되며, 필요한 환경 변수가 자동으로 추가됩니다:

php artisan reverb:install

자세한 설치 및 사용 방법은 Reverb 문서를 참고하세요.

Pusher Channels

Pusher Channels를 사용하려면 먼저 Pusher PHP SDK를 설치합니다:

composer require pusher/pusher-php-server

다음으로, config/broadcasting.php에 Pusher 인증 정보를 설정합니다. 파일에 이미 예시 설정이 포함되어 있으므로, 아래 환경 변수를 .env에 추가하면 됩니다:

PUSHER_APP_ID=your-pusher-app-id
PUSHER_APP_KEY=your-pusher-key
PUSHER_APP_SECRET=your-pusher-secret
PUSHER_APP_CLUSTER=mt1

config/broadcasting.php의 pusher 섹션에서 클러스터 등 추가 옵션도 설정할 수 있습니다.

그리고 .env에서 브로드캐스트 드라이버를 pusher로 변경합니다:

BROADCAST_DRIVER=pusher

이제 클라이언트 사이드 설치(Laravel Echo)를 진행할 준비가 되었습니다.

Pusher 호환 오픈 소스 대안

soketi는 Pusher 호환 WebSocket 서버로, 유료 서비스 없이도 Laravel 브로드캐스팅의 모든 기능을 활용할 수 있습니다. 자세한 내용은 오픈 소스 대안 섹션을 참고하세요.

Ably

NOTE

아래 내용은 Ably를 "Pusher 호환 모드"로 사용하는 방법을 설명합니다. Ably 팀은 Ably 고유 기능을 최대한 활용할 수 있는 전용 broadcaster와 Echo 클라이언트를 별도로 유지 관리하고 있습니다. 자세한 내용은 Ably의 Laravel broadcaster 문서를 참고하세요.

Ably를 사용하려면 Ably PHP SDK를 설치합니다:

composer require ably/ably-php

다음으로, config/broadcasting.php에 Ably 인증 정보를 설정합니다. 파일에 예시 설정이 이미 포함되어 있으며, 일반적으로 ABLY_KEY 환경 변수를 통해 값을 설정합니다:

ABLY_KEY=your-ably-key

.env에서 브로드캐스트 드라이버를 ably로 변경합니다:

BROADCAST_DRIVER=ably

이제 클라이언트 사이드 설치(Laravel Echo)를 진행할 준비가 되었습니다.

오픈 소스 대안

Node

Soketi는 Node.js 기반의 Pusher 호환 WebSocket 서버입니다. 내부적으로 µWebSockets.js를 사용하여 높은 확장성과 속도를 자랑합니다. 유료 WebSocket 서비스 없이 Laravel 브로드캐스팅의 모든 기능을 사용할 수 있습니다. 설치 및 사용법은 공식 문서를 참고하세요.

클라이언트 사이드 설치

Reverb

Laravel Echo는 채널 구독과 이벤트 수신을 간편하게 처리해주는 JavaScript 라이브러리입니다. Reverb는 WebSocket 구독·채널·메시지에 Pusher 프로토콜을 사용하므로, pusher-js도 함께 설치합니다:

npm install --save-dev laravel-echo pusher-js

설치 후, resources/js/bootstrap.js 파일 하단에 Echo 인스턴스를 생성합니다. 해당 파일에 기본 예시 설정이 주석 처리되어 있으므로, 주석을 해제하고 broadcaster를 reverb로 변경하면 됩니다:

import Echo from 'laravel-echo';

import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT,
    wssPort: import.meta.env.VITE_REVERB_PORT,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

설정 후 에셋을 빌드합니다:

npm run build

WARNING

Laravel Echo의 reverb broadcaster를 사용하려면 laravel-echo v1.16.0 이상이 필요합니다.

Pusher Channels

Laravel Echo와 pusher-js를 NPM으로 설치합니다:

npm install --save-dev laravel-echo pusher-js

설치 후, resources/js/bootstrap.js 파일에서 Echo 인스턴스를 생성합니다. 파일 내 기본 예시 설정의 주석을 해제하면 됩니다:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true
});

설정 완료 후 에셋을 빌드합니다:

npm run build

NOTE

JavaScript 에셋 컴파일에 대한 자세한 내용은 Vite 문서를 참고하세요.

기존 클라이언트 인스턴스 사용

이미 설정된 Pusher Channels 클라이언트 인스턴스가 있다면 client 옵션을 통해 Echo에 전달할 수 있습니다:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

const options = {
    broadcaster: 'pusher',
    key: 'your-pusher-channels-key'
}

window.Echo = new Echo({
    ...options,
    client: new Pusher(options.key, options)
});

Ably

NOTE

Laravel Echo와 pusher-js를 설치합니다. Ably가 Pusher 호환 모드를 지원하므로 pusher-js가 필요합니다:

npm install --save-dev laravel-echo pusher-js

계속하기 전에 Ably 애플리케이션 설정의 "Protocol Adapter Settings"에서 Pusher 프로토콜 지원을 활성화해야 합니다.

Echo 인스턴스를 생성할 때 아래 설정을 사용하세요. bootstrap.js의 기본 설정은 Pusher용이므로 아래 내용으로 교체합니다:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_ABLY_PUBLIC_KEY,
    wsHost: 'realtime-pusher.ably.io',
    wsPort: 443,
    disableStats: true,
    encrypted: true,
});

VITE_ABLY_PUBLIC_KEY는 Ably 키에서 : 문자 앞부분(공개 키)을 사용합니다.

설정 후 에셋을 빌드합니다:

npm run dev

NOTE

JavaScript 에셋 컴파일에 대한 자세한 내용은 Vite 문서를 참고하세요.

개념 개요

Laravel의 이벤트 브로드캐스팅은 서버 사이드 이벤트를 클라이언트 JavaScript 애플리케이션에 드라이버 기반으로 전달합니다. 현재 Pusher Channels와 Ably 드라이버가 내장되어 있으며, 클라이언트에서는 Laravel Echo 패키지로 이벤트를 수신합니다.

이벤트는 채널(channel) 을 통해 브로드캐스트되며, 채널은 공개(public) 또는 비공개(private) 로 구분됩니다. 공개 채널은 인증 없이 누구나 구독할 수 있지만, 비공개 채널은 인증된 사용자만 구독할 수 있으며 별도의 인증 과정이 필요합니다.

NOTE

Pusher의 오픈 소스 대안에 관심이 있다면 오픈 소스 대안 섹션을 참고하세요.

예제 애플리케이션으로 살펴보기

각 컴포넌트를 살펴보기 전에, 쇼핑몰 애플리케이션을 예로 들어 브로드캐스팅의 전체 흐름을 살펴보겠습니다.

사용자가 주문의 배송 상태를 확인하는 페이지가 있다고 가정합니다. 배송 상태가 업데이트되면 OrderShipmentStatusUpdated 이벤트가 발생합니다:

use App\Events\OrderShipmentStatusUpdated;

OrderShipmentStatusUpdated::dispatch($order);

`ShouldBroadcast` 인터페이스

사용자가 페이지를 새로 고침하지 않고 상태 변경을 실시간으로 확인하려면, OrderShipmentStatusUpdated 이벤트에 ShouldBroadcast 인터페이스를 구현해야 합니다. 이 인터페이스를 구현하면 Laravel은 이벤트가 발생할 때 자동으로 브로드캐스트합니다:

<?php

namespace App\Events;

use App\Models\Order;
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class OrderShipmentStatusUpdated implements ShouldBroadcast
{
    /**
     * 주문 인스턴스
     *
     * @var \App\Models\Order
     */
    public $order;
}

ShouldBroadcast 인터페이스를 구현한 이벤트는 broadcastOn 메서드를 정의해야 합니다. 이 메서드는 이벤트를 브로드캐스트할 채널을 반환합니다. 주문 생성자만 상태를 확인할 수 있도록 주문 ID에 연결된 비공개 채널로 브로드캐스트합니다:

use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\PrivateChannel;

/**
 * 이벤트를 브로드캐스트할 채널을 반환합니다.
 */
public function broadcastOn(): Channel
{
    return new PrivateChannel('orders.'.$this->order->id);
}

여러 채널에 브로드캐스트하려면 배열을 반환합니다:

use Illuminate\Broadcasting\PrivateChannel;

/**
 * 이벤트를 브로드캐스트할 채널 목록을 반환합니다.
 *
 * @return array<int, \Illuminate\Broadcasting\Channel>
 */
public function broadcastOn(): array
{
    return [
        new PrivateChannel('orders.'.$this->order->id),
        // ...
    ];
}

채널 인증

비공개 채널을 구독하려면 사용자 인증이 필요합니다. routes/channels.php 파일에서 채널 인증 규칙을 정의합니다. 여기서는 orders.1 채널에 접근하는 사용자가 실제 해당 주문의 생성자인지 확인합니다:

use App\Models\Order;
use App\Models\User;

Broadcast::channel('orders.{orderId}', function (User $user, int $orderId) {
    return $user->id === Order::findOrNew($orderId)->user_id;
});

channel 메서드는 채널 이름과 인증 여부(true/false)를 반환하는 콜백을 인수로 받습니다. 콜백의 첫 번째 인수는 현재 인증된 사용자이고, 이후 인수는 채널 이름의 와일드카드 파라미터입니다.

이벤트 브로드캐스트 수신

마지막으로 JavaScript에서 Laravel Echo를 사용해 이벤트를 수신합니다. private 메서드로 비공개 채널을 구독하고, listen 메서드로 이벤트를 수신합니다. 이벤트의 모든 public 프로퍼티는 자동으로 포함됩니다:

Echo.private(`orders.${orderId}`)
    .listen('OrderShipmentStatusUpdated', (e) => {
        console.log(e.order);
    });

브로드캐스트 이벤트 정의

이벤트를 브로드캐스트하려면 이벤트 클래스에 Illuminate\Contracts\Broadcasting\ShouldBroadcast 인터페이스를 구현합니다. 이 인터페이스는 프레임워크가 생성하는 모든 이벤트 클래스에 이미 임포트되어 있어 바로 추가할 수 있습니다.

ShouldBroadcast는 broadcastOn 메서드 하나만 구현하면 됩니다. 이 메서드는 이벤트를 브로드캐스트할 채널(또는 채널 배열)을 반환합니다. 채널은 Channel(공개), PrivateChannel(비공개), PresenceChannel(Presence) 인스턴스 중 하나입니다. 비공개 채널과 Presence 채널은 채널 인증이 필요합니다:

<?php

namespace App\Events;

use App\Models\User;
use Illuminate\Broadcasting\Channel;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PresenceChannel;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
use Illuminate\Queue\SerializesModels;

class ServerCreated implements ShouldBroadcast
{
    use SerializesModels;

    /**
     * 새 이벤트 인스턴스를 생성합니다.
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * 이벤트를 브로드캐스트할 채널 목록을 반환합니다.
     *
     * @return array<int, \Illuminate\Broadcasting\Channel>
     */
    public function broadcastOn(): array
    {
        return [
            new PrivateChannel('user.'.$this->user->id),
        ];
    }
}

ShouldBroadcast를 구현한 후에는 평소처럼 이벤트를 발생시키면 됩니다. 이벤트가 발생하면 큐 Job이 자동으로 설정된 브로드캐스트 드라이버를 통해 이벤트를 전송합니다.

브로드캐스트 이름

기본적으로 Laravel은 이벤트 클래스 이름을 브로드캐스트 이름으로 사용합니다. broadcastAs 메서드를 정의하면 이름을 커스터마이징할 수 있습니다:

/**
 * 이벤트의 브로드캐스트 이름을 반환합니다.
 */
public function broadcastAs(): string
{
    return 'server.created';
}

broadcastAs로 이름을 커스터마이징한 경우, Echo에서 이벤트를 수신할 때 이름 앞에 .을 붙여야 합니다. 이렇게 하면 Echo가 애플리케이션 네임스페이스를 자동으로 추가하지 않습니다:

.listen('.server.created', function (e) {
    // ...
});

브로드캐스트 데이터

이