이벤트
업데이트됨번역일: 2026년 10월 8일
이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.
- 원문 수정
- 2026년 11월 15일
- 번역 갱신
- 2026년 10월 8일
이벤트
소개
Laravel 이벤트는 간단한 옵저버 패턴 구현을 제공하여 애플리케이션에서 발생하는 다양한 이벤트를 구독하고 처리할 수 있게 합니다. 이벤트 클래스는 보통 app/Events, 리스너는 app/Listeners에 저장됩니다. 디렉터리가 아직 없어도 Artisan 콘솔 명령어로 이벤트나 리스너를 생성하면 함께 만들어집니다.
하나의 이벤트에 서로 의존하지 않는 여러 리스너를 연결할 수 있으므로 애플리케이션의 여러 기능을 분리하기에 좋습니다. 예를 들어 주문을 발송할 때마다 사용자에게 Slack 알림을 보내려면 주문 처리 코드와 알림 코드를 직접 결합하는 대신 App\Events\OrderShipped를 발생시키고, 리스너가 이를 받아 Slack 알림을 전달하도록 할 수 있습니다.
이벤트와 리스너 생성
make:event와 make:listener Artisan 명령어로 이벤트와 리스너를 빠르게 생성할 수 있습니다:
php artisan make:event PodcastProcessedphp artisan make:listener SendPodcastNotification --event=PodcastProcessed추가 인수 없이 명령어를 실행할 수도 있습니다. 이 경우 Laravel이 클래스 이름을 묻고, 리스너를 생성할 때는 처리할 이벤트도 묻습니다:
php artisan make:eventphp artisan make:listener이벤트와 리스너 등록
이벤트 자동 발견
기본적으로 Laravel은 애플리케이션의 Listeners 디렉터리를 스캔하여 리스너를 자동으로 찾고 등록합니다. 리스너 클래스에서 이름이 handle 또는 __invoke로 시작하는 메서드를 발견하면, 메서드 시그니처의 타입 힌트로 지정한 이벤트에 대한 리스너로 등록합니다:
use App\Events\PodcastProcessed;
class SendPodcastNotification
{
/**
* Handle the event.
*/
public function handle(PodcastProcessed $event): void
{
// ...
}
}PHP 유니온 타입으로 여러 이벤트를 처리할 수 있습니다:
/**
* Handle the event.
*/
public function handle(PodcastProcessed|PodcastPublished $event): void
{
// ...
}다른 디렉터리나 여러 디렉터리에 리스너를 저장한다면 bootstrap/app.php의 withEvents로 해당 디렉터리를 스캔하도록 지정합니다:
->withEvents(discover: [
__DIR__.'/../app/Domain/Orders/Listeners',
])* 와일드카드로 구조가 비슷한 여러 디렉터리의 리스너를 검색할 수 있습니다:
->withEvents(discover: [
__DIR__.'/../app/Domain/*/Listeners',
])event:list로 애플리케이션에 등록된 모든 리스너를 확인할 수 있습니다:
php artisan event:list운영 환경의 이벤트 자동 발견
애플리케이션 성능을 높이려면 optimize 또는 event:cache Artisan 명령어로 모든 리스너의 매니페스트를 캐시해야 합니다. 보통 배포 과정에 포함합니다. 프레임워크는 이 매니페스트로 이벤트 등록을 빠르게 처리합니다. event:clear로 이벤트 캐시를 제거할 수 있습니다.
동적 이벤트 자동 발견
리스너의 자동 발견 여부를 동적으로 제어하려면 리스너 클래스에 ShouldBeDiscovered 인터페이스를 구현하고 불리언을 반환하는 shouldBeDiscovered를 정의합니다. false를 반환하면 자동 발견 과정에서 등록되지 않습니다:
use Illuminate\Contracts\Events\ShouldBeDiscovered;
class SendPodcastNotification implements ShouldBeDiscovered
{
/**
* Handle the event.
*/
public function handle(PodcastProcessed $event): void
{
// ...
}
/**
* Determine if the listener should be discovered.
*/
public static function shouldBeDiscovered(): bool
{
return app()->environment('production');
}
}이벤트 수동 등록
Event 파사드로 AppServiceProvider의 boot에서 이벤트와 해당 리스너를 수동 등록할 수 있습니다:
use App\Domain\Orders\Events\PodcastProcessed;
use App\Domain\Orders\Listeners\SendPodcastNotification;
use Illuminate\Support\Facades\Event;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Event::listen(
PodcastProcessed::class,
SendPodcastNotification::class,
);
}event:list로 애플리케이션에 등록된 모든 리스너를 확인할 수 있습니다:
php artisan event:list클로저 리스너
리스너는 보통 클래스로 정의하지만 AppServiceProvider의 boot에서 클로저 기반 리스너를 수동 등록할 수도 있습니다:
use App\Events\PodcastProcessed;
use Illuminate\Support\Facades\Event;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Event::listen(function (PodcastProcessed $event) {
// ...
});
}큐로 실행할 수 있는 익명 이벤트 리스너
클로저 기반 리스너를 등록할 때 Illuminate\Events\queueable 함수로 감싸면 Laravel이 큐에서 실행하도록 지정할 수 있습니다:
use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Event::listen(queueable(function (PodcastProcessed $event) {
// ...
}));
}큐 Job처럼 onConnection, onQueue, delay로 큐 리스너의 실행 방식을 조정할 수 있습니다:
Event::listen(queueable(function (PodcastProcessed $event) {
// ...
})->onConnection('redis')->onQueue('podcasts')->delay(now()->plus(seconds: 10)));익명 큐 리스너의 실패를 처리하려면 queueable 리스너를 정의할 때 catch에 클로저를 전달합니다. 이 클로저는 이벤트 인스턴스와 실패 원인인 Throwable 인스턴스를 받습니다:
use App\Events\PodcastProcessed;
use function Illuminate\Events\queueable;
use Illuminate\Support\Facades\Event;
use Throwable;
Event::listen(queueable(function (PodcastProcessed $event) {
// ...
})->catch(function (PodcastProcessed $event, Throwable $e) {
// The queued listener failed...
}));와일드카드 이벤트 리스너
* 와일드카드로 리스너를 등록하면 하나의 리스너에서 여러 이벤트를 처리할 수 있습니다. 첫 번째 인수로 이벤트 이름을, 두 번째 인수로 전체 이벤트 데이터 배열을 받습니다:
Event::listen('event.*', function (string $eventName, array $data) {
// ...
});이벤트 정의
이벤트 클래스는 기본적으로 이벤트 관련 정보를 담는 데이터 컨테이너입니다. 예를 들어 App\Events\OrderShipped가 Eloquent ORM 객체를 받는다고 가정해 보겠습니다:
<?php
namespace App\Events;
use App\Models\Order;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
class OrderShipped
{
use Dispatchable, InteractsWithSockets, SerializesModels;
/**
* Create a new event instance.
*/
public function __construct(
public Order $order,
) {}
}이 이벤트 클래스에는 로직이 없고 구매한 주문의 App\Models\Order 인스턴스만 담습니다. 큐 리스너처럼 PHP의 serialize로 이벤트 객체를 직렬화할 때, SerializesModels 트레이트는 포함된 Eloquent 모델도 적절히 직렬화합니다.
리스너 정의
이제 예제 이벤트의 리스너를 살펴보겠습니다. 이벤트 리스너는 handle에서 이벤트 인스턴스를 받습니다. make:listener에 --event 옵션을 사용하면 적절한 이벤트 클래스를 자동으로 가져오고 handle에 타입 힌트를 지정합니다. 이 메서드 안에서 이벤트에 응답하기 위한 작업을 수행합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
class SendShipmentNotification
{
/**
* Create the event listener.
*/
public function __construct() {}
/**
* Handle the event.
*/
public function handle(OrderShipped $event): void
{
// Access the order using $event->order...
}
}NOTE
리스너 생성자에도 필요한 의존성의 타입 힌트를 지정할 수 있습니다. 모든 리스너는 Laravel 서비스 컨테이너에서 해결하므로 의존성이 자동 주입됩니다.
이벤트 전파 중지
다른 리스너로 이벤트가 전파되는 것을 멈추려면 리스너의 handle에서 false를 반환합니다.
큐 이벤트 리스너
이메일 발송이나 HTTP 요청처럼 느린 작업을 수행하는 리스너는 큐로 실행하면 유용합니다. 사용 전에 큐를 설정하고 서버나 로컬 개발 환경에서 큐 워커를 시작해야 합니다.
리스너를 큐로 실행하려면 클래스에 ShouldQueue 인터페이스를 추가합니다. make:listener로 생성한 리스너에는 이미 해당 인터페이스가 현재 네임스페이스로 가져와져 있어 바로 사용할 수 있습니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue
{
// ...
}이제 이 리스너가 처리할 이벤트를 전달하면 이벤트 디스패처가 Laravel 큐 시스템을 이용해 리스너를 자동으로 큐에 넣습니다. 큐에서 실행되는 동안 예외가 발생하지 않으면 처리가 끝난 Job은 자동 삭제됩니다.
큐 연결, 이름, 지연 시간 설정
이벤트 리스너의 큐 연결, 큐 이름, 지연 시간을 조정하려면 클래스에 Connection, Queue, Delay 속성을 사용합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Connection;
use Illuminate\Queue\Attributes\Delay;
use Illuminate\Queue\Attributes\Queue;
#[Connection('sqs')]
#[Queue('listeners')]
#[Delay(60)]
class SendShipmentNotification implements ShouldQueue
{
// ...
}실행 시점에 큐 연결, 이름, 지연 시간을 결정하려면 리스너에 viaConnection, viaQueue, withDelay 메서드를 정의합니다:
/**
* Get the name of the listener's queue connection.
*/
public function viaConnection(): string
{
return 'sqs';
}
/**
* Get the name of the listener's queue.
*/
public function viaQueue(): string
{
return 'listeners';
}
/**
* Get the number of seconds before the job should be processed.
*/
public function withDelay(OrderShipped $event): int
{
return $event->highPriority ? 0 : 60;
}모든 큐 리스너가 같은 큐를 사용하게 하려면 각 클래스를 수정하는 대신 ShouldQueue 계약을 큐로 라우팅할 수 있습니다.
조건부 큐 실행
실행 시점에만 알 수 있는 데이터로 리스너를 큐에 넣을지 판단해야 할 때가 있습니다. 리스너에 shouldQueue를 추가하면 됩니다. false를 반환하면 리스너는 큐에 들어가지 않습니다:
<?php
namespace App\Listeners;
use App\Events\OrderCreated;
use Illuminate\Contracts\Queue\ShouldQueue;
class RewardGiftCard implements ShouldQueue
{
/**
* Reward a gift card to the customer.
*/
public function handle(OrderCreated $event): void
{
// ...
}
/**
* Determine whether the listener should be queued.
*/
public function shouldQueue(OrderCreated $event): bool
{
return $event->order->subtotal >= 5000;
}
}큐와 직접 상호작용
리스너의 내부 큐 Job에 있는 delete와 release에 직접 접근하려면 Illuminate\Queue\InteractsWithQueue 트레이트를 사용합니다. 생성된 리스너에는 기본적으로 가져와져 있으며 이 메서드들에 대한 접근을 제공합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
class SendShipmentNotification implements ShouldQueue
{
use InteractsWithQueue;
/**
* Handle the event.
*/
public function handle(OrderShipped $event): void
{
if ($condition) {
$this->release(30);
}
}
}큐 이벤트 리스너와 데이터베이스 트랜잭션
데이터베이스 트랜잭션 안에서 큐 리스너를 전달하면 트랜잭션이 커밋되기 전에 큐에서 처리될 수 있습니다. 이때 트랜잭션 중 수정한 모델이나 레코드의 변경 사항이 아직 데이터베이스에 반영되지 않았을 수 있고, 새로 생성한 모델이나 레코드가 존재하지 않을 수도 있습니다. 리스너가 이러한 모델에 의존하면 큐 리스너를 전달하는 Job을 처리할 때 예상치 못한 오류가 발생할 수 있습니다.
큐 연결의 after_commit이 false여도 리스너 클래스에 ShouldQueueAfterCommit을 구현하면 열려 있는 모든 데이터베이스 트랜잭션이 커밋된 뒤 해당 큐 리스너를 전달하도록 지정할 수 있습니다:
<?php
namespace App\Listeners;
use Illuminate\Contracts\Queue\ShouldQueueAfterCommit;
use Illuminate\Queue\InteractsWithQueue;
class SendShipmentNotification implements ShouldQueueAfterCommit
{
use InteractsWithQueue;
}NOTE
이 문제를 해결하는 자세한 방법은 큐 Job과 데이터베이스 트랜잭션 문서를 참고하세요.
큐 리스너 미들웨어
큐 리스너도 Job 미들웨어를 사용할 수 있습니다. 리스너 실행 전후를 사용자 정의 로직으로 감싸 리스너 내부의 반복 코드를 줄일 수 있습니다. Job 미들웨어를 생성한 다음 리스너의 middleware에서 반환하여 연결합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use App\Jobs\Middleware\RateLimited;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue
{
/**
* Handle the event.
*/
public function handle(OrderShipped $event): void
{
// Process the event...
}
/**
* Get the middleware the listener should pass through.
*
* @return array<int, object>
*/
public function middleware(OrderShipped $event): array
{
return [new RateLimited];
}
}암호화된 큐 리스너
Laravel은 암호화를 통해 큐 리스너 데이터의 기밀성과 무결성을 보호할 수 있게 합니다. 클래스에 ShouldBeEncrypted를 추가하면 큐에 넣기 전에 리스너를 자동 암호화합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldBeEncrypted;
use Illuminate\Contracts\Queue\ShouldQueue;
class SendShipmentNotification implements ShouldQueue, ShouldBeEncrypted
{
// ...
}고유 이벤트 리스너
WARNING
고유 리스너에는 잠금을 지원하는 캐시 드라이버가 필요합니다. 현재 memcached, redis, dynamodb, database, file, array가 원자적 잠금을 지원합니다.
특정 리스너 인스턴스가 어느 시점에도 큐에 하나만 존재하게 하려면 클래스에 ShouldBeUnique를 구현합니다:
<?php
namespace App\Listeners;
use App\Events\LicenseSaved;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
class AcquireProductKey implements ShouldQueue, ShouldBeUnique
{
public function __invoke(LicenseSaved $event): void
{
// ...
}
}위 예제의 AcquireProductKey는 고유 리스너입니다. 다른 인스턴스가 이미 큐에 있고 처리를 마치지 않았다면 새 리스너는 큐에 들어가지 않습니다. 따라서 라이선스를 짧은 시간에 여러 번 저장하더라도 각 라이선스에 대해 제품 키를 한 번만 획득하도록 합니다.
고유성을 결정하는 키나 고유성이 유지되는 제한 시간을 지정하려면 클래스에 uniqueId와 uniqueFor 속성 또는 메서드를 정의합니다. 메서드는 이벤트 인스턴스를 받아 이벤트 데이터로 반환값을 구성할 수 있습니다:
<?php
namespace App\Listeners;
use App\Events\LicenseSaved;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
class AcquireProductKey implements ShouldQueue, ShouldBeUnique
{
/**
* The number of seconds after which the listener's unique lock will be released.
*
* @var int
*/
public $uniqueFor = 3600;
public function __invoke(LicenseSaved $event): void
{
// ...
}
/**
* Get the unique ID for the listener.
*/
public function uniqueId(LicenseSaved $event): string
{
return 'listener:'.$event->license->id;
}
}위 예제에서는 라이선스 ID로 AcquireProductKey의 고유성을 구분합니다. 같은 라이선스에 대한 새 리스너 전달은 기존 처리가 완료될 때까지 무시하므로 중복 제품 키 획득을 방지합니다. 기존 리스너를 한 시간 안에 처리하지 못하면 고유 잠금이 해제되고 같은 키의 다른 리스너를 큐에 넣을 수 있습니다.
WARNING
여러 웹 서버나 컨테이너에서 이벤트를 전달한다면 모든 서버가 같은 중앙 캐시 서버를 사용해야 Laravel이 리스너의 고유성을 정확히 판단할 수 있습니다.
처리 시작 전까지 고유성 유지
기본적으로 고유 리스너는 처리를 완료하거나 모든 재시도에 실패하면 잠금이 해제됩니다. 처리 직전에 해제하려면 ShouldBeUnique 대신 ShouldBeUniqueUntilProcessing 계약을 구현합니다:
<?php
namespace App\Listeners;
use App\Events\LicenseSaved;
use Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing;
use Illuminate\Contracts\Queue\ShouldQueue;
class AcquireProductKey implements ShouldQueue, ShouldBeUniqueUntilProcessing
{
// ...
}고유 리스너 잠금
ShouldBeUnique 리스너가 전달되면 Laravel은 내부적으로 uniqueId 키의 잠금을 획득하려고 시도합니다. 이미 잠금이 있으면 리스너를 전달하지 않습니다. 처리를 완료하거나 모든 재시도에 실패하면 잠금이 해제됩니다. 기본 캐시 드라이버를 사용하지만 다른 드라이버가 필요하면 사용할 캐시 드라이버를 반환하는 uniqueVia를 정의합니다:
<?php
namespace App\Listeners;
use App\Events\LicenseSaved;
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;
class AcquireProductKey implements ShouldQueue, ShouldBeUnique
{
// ...
/**
* Get the cache driver for the unique listener lock.
*/
public function uniqueVia(LicenseSaved $event): Repository
{
return Cache::driver('redis');
}
}NOTE
리스너의 동시 처리만 제한하려면 대신 WithoutOverlapping Job 미들웨어를 사용하세요.
디바운스 이벤트 리스너
짧은 시간 동안 반복해서 전달되는 이벤트 중 가장 최신 인스턴스만 처리하려면 큐 리스너에 DebounceFor 속성을 추가합니다:
<?php
namespace App\Listeners;
use App\Events\ProductUpdated;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\DebounceFor;
#[DebounceFor(30)]
class UpdateProductSearchIndex implements ShouldQueue
{
/**
* Handle the event.
*/
public function handle(ProductUpdated $event): void
{
// Update the product's search index...
}
/**
* Get the debounce ID for the listener.
*/
public function debounceId(ProductUpdated $event): string
{
return (string) $event->product->getKey();
}
}위 예제에서 같은 제품의 ProductUpdated를 30초 안에 반복 전달하면 리스너가 디바운스되어 최신 이벤트만 처리합니다. 서로 다른 디바운스 ID는 독립적으로 처리됩니다.
자주 전달되는 이벤트가 리스너를 지연시킬 수 있는 최대 시간을 제한하려면 DebounceFor에 maxWait를 지정합니다:
#[DebounceFor(30, maxWait: 120)]
class UpdateProductSearchIndex implements ShouldQueue
{
// ...
}디바운스 추적용 캐시 저장소를 변경하려면 리스너에 debounceVia를 정의합니다. 이벤트 인스턴스를 받으며 캐시 저장소를 반환해야 합니다:
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;
public function debounceVia(ProductUpdated $event): Repository
{
return Cache::driver('redis');
}디바운스 리스너와 고유 리스너는 함께 사용할 수 없습니다. DebounceFor를 사용하는 리스너는 ShouldBeUnique를 구현하면 안 됩니다.
WARNING
여러 웹 서버나 컨테이너에서 이벤트를 전달한다면 모든 서버가 같은 중앙 캐시 서버를 사용해야 합니다.
실패한 Job 처리
큐 이벤트 리스너가 실패할 수 있습니다. 큐 워커에 정의한 최대 시도 횟수를 초과하면 리스너의 failed가 호출됩니다. 이벤트 인스턴스와 실패 원인인 Throwable을 받습니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Throwable;
class SendShipmentNotification implements ShouldQueue
{
use InteractsWithQueue;
/**
* Handle the event.
*/
public function handle(OrderShipped $event): void
{
// ...
}
/**
* Handle a job failure.
*/
public function failed(OrderShipped $event, Throwable $exception): void
{
// ...
}
}큐 리스너 최대 시도 횟수 지정
오류가 발생하는 리스너를 무한히 재시도하지 않도록 Laravel은 시도 횟수나 재시도 가능 시간을 지정하는 여러 방법을 제공합니다.
클래스에 Tries를 사용하면 실패로 간주하기 전까지 시도할 횟수를 지정할 수 있습니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\InteractsWithQueue;
#[Tries(5)]
class SendShipmentNotification implements ShouldQueue
{
use InteractsWithQueue;
// ...
}횟수 대신 더 이상 시도하지 않을 시각을 정의할 수도 있습니다. 지정한 시간 범위 안에서는 횟수 제한 없이 시도할 수 있습니다. 클래스에 retryUntil을 추가하고 DateTimeInterface 인스턴스를 반환합니다:
use DateTimeInterface;
/**
* Determine the time at which the listener should timeout.
*/
public function retryUntil(): DateTimeInterface
{
return now()->plus(minutes: 5);
}retryUntil과 tries를 모두 정의하면 Laravel은 retryUntil을 우선합니다.
큐 리스너 재시도 대기 시간 지정
예외가 발생한 리스너를 재시도하기 전에 기다릴 초 단위 시간을 설정하려면 클래스에 Backoff 속성을 사용합니다:
<?php
namespace App\Listeners;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Backoff;
#[Backoff(3)]
class SendShipmentNotification implements ShouldQueue
{
// ...
}더 복잡한 계산이 필요하면 클래스에 backoff 메서드를 정의합니다:
/**
* Calculate the number of seconds to wait before retrying the queued listener.
*/
public function backoff(OrderShipped $event): int
{
return 3;
}backoff에서 대기 시간 배열을 반환하여 단계별로 증가하는 대기 시간을 쉽게 설정할 수 있습니다. 아래 예제에서는 첫 재시도에 1초, 두 번째에 5초, 세 번째에 10초를 기다리며, 시도가 더 남아 있다면 이후에도 10초씩 기다립니다:
/**
* Calculate the number of seconds to wait before retrying the queued listener.
*
* @return list<int>
*/
public function backoff(OrderShipped $event): array
{
return [1, 5, 10];
}큐 리스너 최대 예외 수 지정
시도 횟수는 많이 허용하되, release를 직접 호출해서가 아니라 처리되지 않은 예외로 재시도가 발생한 횟수가 일정 수에 이르면 실패하게 할 수 있습니다. 클래스에 Tries와 MaxExceptions를 사용합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\InteractsWithQueue;
#[Tries(25)]
#[MaxExceptions(3)]
class SendShipmentNotification implements ShouldQueue
{
use InteractsWithQueue;
/**
* Handle the event.
*/
public function handle(OrderShipped $event): void
{
// Process the event...
}
}이 예제의 리스너는 최대 25회까지 재시도하지만, 처리되지 않은 예외가 세 번 발생하면 실패합니다.
큐 리스너 타임아웃 지정
리스너 실행에 필요한 시간을 대략 예상할 수 있다면 타임아웃을 지정할 수 있습니다. 지정한 초 단위 시간보다 오래 처리하면 해당 워커가 오류와 함께 종료됩니다. 클래스의 Timeout 속성으로 최대 실행 시간을 정의합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\Timeout;
#[Timeout(120)]
class SendShipmentNotification implements ShouldQueue
{
// ...
}타임아웃 발생 시 리스너를 실패 상태로 표시하려면 FailOnTimeout 속성을 사용합니다:
<?php
namespace App\Listeners;
use App\Events\OrderShipped;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\Attributes\FailOnTimeout;
#[FailOnTimeout]
class SendShipmentNotification implements ShouldQueue
{
// ...
}이벤트 전달
이벤트의 정적 dispatch를 호출하여 전달할 수 있습니다. 이 메서드는 Illuminate\Foundation\Events\Dispatchable 트레이트가 제공합니다. 전달한 인수는 이벤트 생성자로 넘어갑니다:
<?php
namespace App\Http\Controllers;
use App\Events\OrderShipped;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
class OrderShipmentController extends Controller
{
/**
* Ship the given order.
*/
public function store(Request $request): RedirectResponse
{
$order = Order::findOrFail($request->order_id);
// Order shipment logic...
OrderShipped::dispatch($order);
return redirect('/orders');
}
}조건부로 이벤트를 전달하려면 dispatchIf와 dispatchUnless를 사용합니다:
OrderShipped::dispatchIf($condition, $order);
OrderShipped::dispatchUnless($condition, $order);NOTE
테스트에서는 실제 리스너를 실행하지 않고 특정 이벤트가 전달되었는지 검증하는 것이 유용할 수 있습니다. Laravel 내장 테스트 헬퍼로 쉽게 할 수 있습니다.
데이터베이스 트랜잭션 이후 이벤트 전달
활성 데이터베이스 트랜잭션이 커밋된 후에만 이벤트를 전달하려면 이벤트 클래스에 ShouldDispatchAfterCommit을 구현합니다.
이 인터페이스는 현재 트랜잭션이 커밋될 때까지 이벤트 전달을 보류하도록 Laravel에 지시합니다. 트랜잭션이 실패하면 이벤트는 버려집니다. 진행 중인 트랜잭션이 없다면 즉시 전달됩니다:
<?php
namespace App\Events;
use App\Models\Order;
use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
class OrderShipped implements ShouldDispatchAfterCommit
{
use Dispatchable, InteractsWithSockets, SerializesModels;
/**
* Create a new event instance.
*/
public function __construct(
public Order $order,
) {}
}이벤트 지연
지연 이벤트는 특정 코드 블록이 완료될 때까지 모델 이벤트 전달과 리스너 실행을 미룹니다. 특히 리스너 실행 전에 관련 레코드가 모두 생성되어야 할 때 유용합니다.
Event::defer()에 클로저를 전달합니다:
use App\Models\User;
use Illuminate\Support\Facades\Event;
Event::defer(function () {
$user = User::create(['name' => 'Victoria Otwell']);
$user->posts()->create(['title' => 'My first post!']);
});클로저 안에서 발생한 모든 이벤트는 클로저 실행이 끝난 뒤 전달됩니다. 따라서 리스너는 지연된 실행 중 생성한 모든 관련 레코드에 접근할 수 있습니다. 클로저에서 예외가 발생하면 지연한 이벤트는 전달되지 않습니다.
특정 이벤트만 지연하려면 defer의 두 번째 인수로 이벤트 배열을 전달합니다:
use App\Models\User;
use Illuminate\Support\Facades\Event;
Event::defer(function () {
$user = User::create(['name' => 'Victoria Otwell']);
$user->posts()->create(['title' => 'My first post!']);
}, ['eloquent.created: '.User::class]);이벤트 구독자
이벤트 구독자 작성
이벤트 구독자는 클래스 내부에서 여러 이벤트를 구독할 수 있는 클래스입니다. 하나의 클래스에 여러 이벤트 핸들러를 정의할 수 있습니다. 이벤트 디스패처 인스턴스를 받는 subscribe를 정의하고, 전달받은 디스패처의 listen으로 리스너를 등록합니다:
<?php
namespace App\Listeners;
use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;
use Illuminate\Events\Dispatcher;
class UserEventSubscriber
{
/**
* Handle user login events.
*/
public function handleUserLogin(Login $event): void {}
/**
* Handle user logout events.
*/
public function handleUserLogout(Logout $event): void {}
/**
* Register the listeners for the subscriber.
*/
public function subscribe(Dispatcher $events): void
{
$events->listen(
Login::class,
[UserEventSubscriber::class, 'handleUserLogin']
);
$events->listen(
Logout::class,
[UserEventSubscriber::class, 'handleUserLogout']
);
}
}리스너 메서드가 구독자 클래스 자체에 있다면 subscribe에서 이벤트와 메서드 이름의 배열을 반환하는 편이 더 간편할 수 있습니다. Laravel이 리스너를 등록할 때 구독자의 클래스 이름을 자동으로 판단합니다:
<?php
namespace App\Listeners;
use Illuminate\Auth\Events\Login;
use Illuminate\Auth\Events\Logout;
use Illuminate\Events\Dispatcher;
class UserEventSubscriber
{
/**
* Handle user login events.
*/
public function handleUserLogin(Login $event): void {}
/**
* Handle user logout events.
*/
public function handleUserLogout(Logout $event): void {}
/**
* Register the listeners for the subscriber.
*
* @return array<string, string>
*/
public function subscribe(Dispatcher $events): array
{
return [
Login::class => 'handleUserLogin',
Logout::class => 'handleUserLogout',
];
}
}이벤트 구독자 등록
구독자 핸들러가 Laravel의 이벤트 자동 발견 규칙을 따르면 자동으로 등록됩니다. 그렇지 않다면 Event 파사드의 subscribe로 수동 등록할 수 있습니다. 보통 AppServiceProvider의 boot에서 수행합니다:
<?php
namespace App\Providers;
use App\Listeners\UserEventSubscriber;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Event::subscribe(UserEventSubscriber::class);
}
}테스트
이벤트를 전달하는 코드를 테스트할 때는 실제 리스너를 실행하지 않도록 할 수 있습니다. 리스너 자체의 코드는 이벤트 전달 코드와 분리해서 직접 테스트할 수 있기 때문입니다. 리스너를 테스트하려면 인스턴스를 생성하고 테스트에서 handle을 직접 호출하면 됩니다.
Event 파사드의 fake로 리스너 실행을 막고 테스트 대상 코드를 실행한 뒤, assertDispatched, assertNotDispatched, assertNothingDispatched로 어떤 이벤트가 전달되었는지 검증할 수 있습니다:
Pest
<?php
use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;
test('orders can be shipped', function () {
Event::fake();
// Perform order shipping...
// Assert that an event was dispatched...
Event::assertDispatched(OrderShipped::class);
// Assert an event was dispatched twice...
Event::assertDispatched(OrderShipped::class, 2);
// Assert an event was dispatched once...
Event::assertDispatchedOnce(OrderShipped::class);
// Assert an event was not dispatched...
Event::assertNotDispatched(OrderFailedToShip::class);
// Assert that no events were dispatched...
Event::assertNothingDispatched();
});PHPUnit
<?php
namespace Tests\Feature;
use App\Events\OrderFailedToShip;
use App\Events\OrderShipped;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;
class ExampleTest extends TestCase
{
/**
* Test order shipping.
*/
public function test_orders_can_be_shipped(): void
{
Event::fake();
// Perform order shipping...
// Assert that an event was dispatched...
Event::assertDispatched(OrderShipped::class);
// Assert an event was dispatched twice...
Event::assertDispatched(OrderShipped::class, 2);
// Assert an event was dispatched once...
Event::assertDispatchedOnce(OrderShipped::class);
// Assert an event was not dispatched...
Event::assertNotDispatched(OrderFailedToShip::class);
// Assert that no events were dispatched...
Event::assertNothingDispatched();
}
}assertDispatched와 assertNotDispatched에 클로저를 전달하면 주어진 조건에 부합하는 이벤트의 전달 여부를 검증할 수 있습니다. 조건을 만족하는 이벤트가 하나 이상 전달되었다면 전달되었음을 확인하는 검증은 성공합니다:
Event::assertDispatched(function (OrderShipped $event) use ($order) {
return $event->order->id === $order->id;
});또는 assertDispatched나 assertNotDispatched의 두 번째 인수로 예상 속성 값의 배열을 전달할 수 있습니다:
Event::assertDispatched(OrderShipped::class, ['order' => $order]);지정한 모든 속성이 일치해야 합니다. 값은 엄격한 동등 비교로 확인하고, Eloquent 모델은 is 메서드로 비교합니다.
리스너가 특정 이벤트를 처리하도록 등록되어 있는지만 확인하려면 assertListening을 사용합니다:
Event::assertListening(
OrderShipped::class,
SendShipmentNotification::class
);WARNING
Event::fake() 이후에는 이벤트 리스너가 실행되지 않습니다. 모델의 creating 이벤트에서 UUID를 만드는 경우처럼 이벤트에 의존하는 모델 팩토리를 사용한다면 팩토리 사용 후에 Event::fake()를 호출해야 합니다.
일부 이벤트만 가짜 처리
특정 이벤트 집합의 리스너만 가짜 처리하려면 fake나 fakeFor에 이벤트 목록을 전달합니다:
Pest
test('orders can be processed', function () {
Event::fake([
OrderCreated::class,
]);
$order = Order::factory()->create();
Event::assertDispatched(OrderCreated::class);
// Other events are dispatched as normal...
$order->update([
// ...
]);
});PHPUnit
/**
* Test order process.
*/
public function test_orders_can_be_processed(): void
{
Event::fake([
OrderCreated::class,
]);
$order = Order::factory()->create();
Event::assertDispatched(OrderCreated::class);
// Other events are dispatched as normal...
$order->update([
// ...
]);
}except로 지정한 이벤트를 제외한 나머지 모든 이벤트를 가짜 처리할 수 있습니다:
Event::fake()->except([
OrderCreated::class,
]);범위가 제한된 이벤트 가짜 처리
테스트 일부에서만 리스너를 가짜 처리하려면 fakeFor를 사용합니다:
Pest
<?php
use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;
test('orders can be processed', function () {
$order = Event::fakeFor(function () {
$order = Order::factory()->create();
Event::assertDispatched(OrderCreated::class);
return $order;
});
// Events are dispatched as normal and observers will run...
$order->update([
// ...
]);
});PHPUnit
<?php
namespace Tests\Feature;
use App\Events\OrderCreated;
use App\Models\Order;
use Illuminate\Support\Facades\Event;
use Tests\TestCase;
class ExampleTest extends TestCase
{
/**
* Test order process.
*/
public function test_orders_can_be_processed(): void
{
$order = Event::fakeFor(function () {
$order = Order::factory()->create();
Event::assertDispatched(OrderCreated::class);
return $order;
});
// Events are dispatched as normal and observers will run...
$order->update([
// ...
]);
}
}