브로드캐스팅

번역일: 2026년 6월 21일

브로드캐스팅

소개
빠른 시작
서버 사이드 설치
클라이언트 사이드 설치
개념 개요
- 예제 애플리케이션으로 살펴보기
브로드캐스트 이벤트 정의
채널 인가
- 인가 콜백 정의
- 채널 클래스 정의
이벤트 브로드캐스팅
브로드캐스트 수신
프레즌스 채널
모델 브로드캐스팅
- 모델 브로드캐스팅 컨벤션
- 모델 브로드캐스트 리스닝
클라이언트 이벤트
알림

소개

현대적인 웹 애플리케이션에서는 UI를 실시간으로 업데이트하기 위해 WebSocket을 활용하는 경우가 많습니다. 서버에서 데이터가 변경되면 WebSocket 연결을 통해 클라이언트로 메시지를 전송하고, 클라이언트는 이를 처리해 화면을 갱신합니다. WebSocket은 데이터 변경 여부를 확인하기 위해 서버를 반복 폴링하는 방식보다 훨씬 효율적입니다.

예를 들어, 사용자 데이터를 CSV 파일로 내보내 이메일로 전송하는 기능을 생각해 봅시다. CSV 생성에 몇 분이 걸릴 수 있으므로 이 작업을 큐 Job으로 처리합니다. CSV가 생성되어 이메일로 전송되면, 브로드캐스팅을 통해 App\Events\UserDataExported 이벤트를 발생시킬 수 있습니다. 클라이언트 JavaScript가 이 이벤트를 수신하면 페이지를 새로고침하지 않아도 "CSV가 이메일로 전송되었습니다"라는 안내 메시지를 사용자에게 즉시 보여줄 수 있습니다.

이런 기능을 손쉽게 구현하도록, Laravel은 서버 사이드 이벤트를 WebSocket 연결을 통해 "브로드캐스트"하는 기능을 제공합니다. 이벤트를 브로드캐스트하면 서버와 클라이언트 JavaScript 간에 동일한 이벤트 이름과 데이터를 공유할 수 있습니다.

핵심 개념은 간단합니다. 프런트엔드에서 클라이언트가 특정 이름의 채널에 구독하면, 백엔드의 Laravel 애플리케이션이 해당 채널로 이벤트를 브로드캐스트합니다. 이벤트에는 프런트엔드에서 활용할 임의의 추가 데이터를 포함할 수 있습니다.

지원 드라이버

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

NOTE

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

빠른 시작

새로운 Laravel 애플리케이션에서는 브로드캐스팅이 기본적으로 비활성화되어 있습니다. install:broadcasting Artisan 명령어를 실행하면 브로드캐스팅을 활성화할 수 있습니다:

php artisan install:broadcasting

이 명령어를 실행하면 사용할 브로드캐스팅 서비스를 선택하는 프롬프트가 표시됩니다. 또한 config/broadcasting.php 설정 파일과 브로드캐스트 인가 라우트 및 콜백을 등록하는 routes/channels.php 파일이 생성됩니다.

Laravel은 Laravel Reverb, Pusher Channels, Ably, 로컬 개발 및 디버깅용 log 드라이버를 기본으로 지원합니다. 테스트 중 브로드캐스팅을 비활성화할 때는 null 드라이버를 사용할 수 있습니다. config/broadcasting.php 파일에는 각 드라이버에 대한 설정 예시가 포함되어 있습니다.

모든 브로드캐스팅 설정은 config/broadcasting.php 파일에 저장됩니다. 이 파일이 없더라도 걱정하지 마세요. install:broadcasting 명령어를 실행하면 자동으로 생성됩니다.

다음 단계

이벤트 브로드캐스팅을 활성화했다면, 브로드캐스트 이벤트 정의와 이벤트 리스닝에 대해 더 알아보세요. Laravel의 React 또는 Vue 스타터 킷을 사용하고 있다면, Echo의 useEcho 훅을 통해 이벤트를 수신할 수 있습니다.

NOTE

이벤트를 브로드캐스트하기 전에 반드시 큐 워커를 설정하고 실행해야 합니다. 이벤트 브로드캐스팅은 모두 큐 Job을 통해 처리되므로, 브로드캐스팅이 애플리케이션의 응답 시간에 영향을 주지 않습니다.

서버 사이드 설치

Laravel의 이벤트 브로드캐스팅을 사용하려면 Laravel 애플리케이션에서 일부 설정을 수행하고 몇 가지 패키지를 설치해야 합니다.

이벤트 브로드캐스팅은 서버 사이드 브로드캐스팅 드라이버가 Laravel 이벤트를 처리하고, 브라우저 클라이언트 내의 JavaScript 라이브러리인 Laravel Echo가 이를 수신하는 방식으로 동작합니다. 아래에서 각 설치 과정을 단계별로 안내합니다.

Reverb

Reverb를 브로드캐스팅 드라이버로 사용하려면 install:broadcasting Artisan 명령어에 --reverb 옵션을 추가하여 실행하세요. 이 명령어는 필요한 Composer 및 NPM 패키지를 설치하고 .env 파일에 적절한 환경 변수를 추가합니다:

php artisan install:broadcasting --reverb

수동 설치

install:broadcasting 명령어 실행 시 Laravel Reverb 설치 여부를 묻는 프롬프트가 표시됩니다. Composer를 통해 직접 설치할 수도 있습니다:

composer require laravel/reverb

패키지 설치 후 Reverb의 설치 명령어를 실행하여 설정 파일을 게시하고, 필요한 환경 변수를 추가하며, 애플리케이션에서 이벤트 브로드캐스팅을 활성화합니다:

php artisan reverb:install

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

Pusher Channels

Pusher를 브로드캐스팅 드라이버로 사용하려면 install:broadcasting Artisan 명령어에 --pusher 옵션을 추가하여 실행하세요. 이 명령어는 Pusher 자격 증명을 입력하는 프롬프트를 표시하고, Pusher PHP 및 JavaScript SDK를 설치하며, .env 파일에 적절한 변수를 추가합니다:

php artisan install:broadcasting --pusher

수동 설치

Pusher 지원을 직접 설치하려면 Composer를 통해 Pusher Channels PHP SDK를 설치하세요:

composer require pusher/pusher-php-server

다음으로, config/broadcasting.php 파일에서 Pusher Channels 자격 증명을 설정합니다. 이 파일에는 Pusher Channels 설정 예시가 이미 포함되어 있어 키, 시크릿, 애플리케이션 ID를 바로 지정할 수 있습니다. 일반적으로 이 값들은 .env 파일에서 설정합니다:

PUSHER_APP_ID="your-pusher-app-id"
PUSHER_APP_KEY="your-pusher-key"
PUSHER_APP_SECRET="your-pusher-secret"
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME="https"
PUSHER_APP_CLUSTER="mt1"

config/broadcasting.php 파일의 pusher 설정에서 클러스터 등 Channels가 지원하는 추가 options를 지정할 수도 있습니다.

그런 다음, .env 파일에서 BROADCAST_CONNECTION 환경 변수를 pusher로 설정하세요:

BROADCAST_CONNECTION=pusher

이제 클라이언트 사이드에서 브로드캐스트 이벤트를 수신하는 Laravel Echo를 설치하고 설정할 준비가 되었습니다.

Ably

NOTE

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

Ably를 브로드캐스팅 드라이버로 사용하려면 install:broadcasting Artisan 명령어에 --ably 옵션을 추가하여 실행하세요. 이 명령어는 Ably 자격 증명을 입력하는 프롬프트를 표시하고, Ably PHP 및 JavaScript SDK를 설치하며, .env 파일에 적절한 변수를 추가합니다:

php artisan install:broadcasting --ably

계속 진행하기 전에 Ably 애플리케이션 설정에서 Pusher 프로토콜 지원을 활성화해야 합니다. Ably 애플리케이션 설정 대시보드의 "Protocol Adapter Settings" 섹션에서 이 기능을 활성화할 수 있습니다.

수동 설치

Ably 지원을 직접 설치하려면 Composer를 통해 Ably PHP SDK를 설치하세요:

composer require ably/ably-php

다음으로, config/broadcasting.php 파일에서 Ably 자격 증명을 설정합니다. 이 파일에는 Ably 설정 예시가 이미 포함되어 있어 키를 바로 지정할 수 있습니다. 일반적으로 이 값은 ABLY_KEY 환경 변수를 통해 설정합니다:

ABLY_KEY=your-ably-key

그런 다음, .env 파일에서 BROADCAST_CONNECTION 환경 변수를 ably로 설정하세요:

BROADCAST_CONNECTION=ably

이제 클라이언트 사이드에서 브로드캐스트 이벤트를 수신하는 Laravel Echo를 설치하고 설정할 준비가 되었습니다.

클라이언트 사이드 설치

Reverb

Laravel Echo는 서버 사이드 브로드캐스팅 드라이버가 브로드캐스트한 이벤트를 채널에 구독하고 수신하는 과정을 간편하게 만들어주는 JavaScript 라이브러리입니다.

install:broadcasting Artisan 명령어로 Laravel Reverb를 설치하면 Reverb 및 Echo의 스캐폴딩과 설정이 자동으로 애플리케이션에 추가됩니다. 직접 수동으로 설정하려면 아래 안내를 따르세요.

수동 설치

Reverb는 WebSocket 구독, 채널, 메시지에 Pusher 프로토콜을 사용하므로, 먼저 laravel-echo와 pusher-js 패키지를 설치하세요:

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

Echo 설치 후 애플리케이션의 JavaScript에서 새 Echo 인스턴스를 생성합니다. Laravel 프레임워크에 포함된 resources/js/bootstrap.js 파일 하단에 추가하는 것이 좋습니다:

JavaScript

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 ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

React

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    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'],
});

Vue

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    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 브로드캐스터는 laravel-echo v1.16.0 이상이 필요합니다.

Pusher Channels

install:broadcasting --pusher Artisan 명령어로 브로드캐스팅 지원을 설치하면 Pusher 및 Echo의 스캐폴딩과 설정이 자동으로 추가됩니다. 직접 수동으로 설정하려면 아래 안내를 따르세요.

수동 설치

laravel-echo와 pusher-js 패키지를 설치하세요:

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

Echo 설치 후 resources/js/bootstrap.js 파일에 새 Echo 인스턴스를 생성하세요:

JavaScript

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
});

React

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    broadcaster: "pusher",
    // key: import.meta.env.VITE_PUSHER_APP_KEY,
    // cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    // forceTLS: true,
    // wsHost: import.meta.env.VITE_PUSHER_HOST,
    // wsPort: import.meta.env.VITE_PUSHER_PORT,
    // wssPort: import.meta.env.VITE_PUSHER_PORT,
    // enabledTransports: ["ws", "wss"],
});

Vue

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    broadcaster: "pusher",
    // key: import.meta.env.VITE_PUSHER_APP_KEY,
    // cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    // forceTLS: true,
    // wsHost: import.meta.env.VITE_PUSHER_HOST,
    // wsPort: import.meta.env.VITE_PUSHER_PORT,
    // wssPort: import.meta.env.VITE_PUSHER_PORT,
    // enabledTransports: ["ws", "wss"],
});

다음으로 .env 파일에 Pusher 환경 변수를 추가하세요. 해당 변수가 없다면 아래 내용을 추가하세요:

PUSHER_APP_ID="your-pusher-app-id"
PUSHER_APP_KEY="your-pusher-key"
PUSHER_APP_SECRET="your-pusher-secret"
PUSHER_HOST=
PUSHER_PORT=443
PUSHER_SCHEME="https"
PUSHER_APP_CLUSTER="mt1"

VITE_APP_NAME="${APP_NAME}"
VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
VITE_PUSHER_HOST="${PUSHER_HOST}"
VITE_PUSHER_PORT="${PUSHER_PORT}"
VITE_PUSHER_SCHEME="${PUSHER_SCHEME}"
VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

Echo 설정을 애플리케이션에 맞게 조정한 후 에셋을 컴파일하세요:

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: import.meta.env.VITE_PUSHER_APP_KEY
}

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

Ably

NOTE

install:broadcasting --ably Artisan 명령어로 브로드캐스팅 지원을 설치하면 Ably 및 Echo의 스캐폴딩과 설정이 자동으로 추가됩니다. 직접 수동으로 설정하려면 아래 안내를 따르세요.

수동 설치

laravel-echo와 pusher-js 패키지를 설치하세요:

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

Echo 설치 후 resources/js/bootstrap.js 파일에 새 Echo 인스턴스를 생성하세요:

JavaScript

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,
});

React

import { configureEcho } from "@laravel/echo-react";

configureEcho({
    broadcaster: "ably",
    // key: import.meta.env.VITE_ABLY_PUBLIC_KEY,
    // wsHost: "realtime-pusher.ably.io",
    // wsPort: 443,
    // disableStats: true,
    // encrypted: true,
});

Vue

import { configureEcho } from "@laravel/echo-vue";

configureEcho({
    broadcaster: "ably",
    // key: import.meta.env.VITE_ABLY_PUBLIC_KEY,
    // wsHost: "realtime-pusher.ably.io",
    // wsPort: 443,
    // disableStats: true,
    // encrypted: true,
});

Ably Echo 설정에서 VITE_ABLY_PUBLIC_KEY 환경 변수를 참조하고 있습니다. 이 변수의 값은 Ably 퍼블릭 키이며, Ably 키에서 : 문자 앞의 부분이 퍼블릭 키입니다.

설정을 마치면 에셋을 컴파일하세요:

npm run dev