diff --git a/events.md b/events.md index c88345fee7..0f079be705 100644 --- a/events.md +++ b/events.md @@ -1,33 +1,33 @@ -# Events - -- [Introduction](#introduction) -- [Registering Events & Listeners](#registering-events-and-listeners) - - [Generating Events & Listeners](#generating-events-and-listeners) - - [Manually Registering Events](#manually-registering-events) -- [Defining Events](#defining-events) -- [Defining Listeners](#defining-listeners) -- [Queued Event Listeners](#queued-event-listeners) - - [Manually Accessing The Queue](#manually-accessing-the-queue) - - [Handling Failed Jobs](#handling-failed-jobs) -- [Dispatching Events](#dispatching-events) -- [Event Subscribers](#event-subscribers) - - [Writing Event Subscribers](#writing-event-subscribers) - - [Registering Event Subscribers](#registering-event-subscribers) +# 事件 + +- [介紹](#introduction) +- [註冊事件與監聽器](#registering-events-and-listeners) + - [產生事件與監聽器](#generating-events-and-listeners) + - [手動註冊事件](#manually-registering-events) +- [定義事件](#defining-events) +- [定義監聽器](#defining-listeners) +- [隊列事件監聽器](#queued-event-listeners) + - [手動存取隊列](#manually-accessing-the-queue) + - [處理失敗的任務](#handling-failed-jobs) +- [調度事件](#dispatching-events) +- [事件訂閱者](#event-subscribers) + - [撰寫事件訂閱者](#writing-event-subscribers) + - [註冊事件訂閱者](#registering-event-subscribers) -## Introduction +## 介紹 -Laravel's events provides a simple observer implementation, allowing you to subscribe and listen for various events that occur in your application. Event classes are typically stored in the `app/Events` directory, while their listeners are stored in `app/Listeners`. Don't worry if you don't see these directories in your application, since they will be created for you as you generate events and listeners using Artisan console commands. +Laravel 的事件提供了簡單的觀察者實作,可以讓你訂閱並監聽各種發生在你的應用程式的事件。事件類別通常會存放在 `app/Events` 目錄,而它們的監聽器則存放在 `app/Listeners`。如果你沒在你的應用程式中看到這些目錄,別擔心!因為他們會在你使用 Artisan 指令列指令來產生事件和監聽器時被建立。 -Events serve as a great way to decouple various aspects of your application, since a single event can have multiple listeners that do not depend on each other. For example, you may wish to send a Slack notification to your user each time an order has shipped. Instead of coupling your order processing code to your Slack notification code, you can simply raise an `OrderShipped` event, which a listener can receive and transform into a Slack notification. +事件服務作為解耦應用程式的各種方面的好方法,因為單一個事件能有多個不依賴彼此的監聽器。例如,你可能希望在每次訂單出貨得時候就發送 Slack 通知給使用者。不是將你的訂單處理程式碼耦合到你的 Slack 通知的程式碼中,而是你能簡單的觸發 `OrderShipped` 事件,讓監聽器可以來接收並轉換成一個 Slack 通知。 -## Registering Events & Listeners +## 註冊事件與監聽器 -The `EventServiceProvider` included with your Laravel application provides a convenient place to register all of your application's event listeners. The `listen` property contains an array of all events (keys) and their listeners (values). Of course, you may add as many events to this array as your application requires. For example, let's add a `OrderShipped` event: +Laravel 應用程式中引入的 `EventServiceProvider` 提供一個便捷的地方來註冊應用程式的所有事件監聽器。`listen` 屬性包含一組所有事件(鍵)和它們的監聽器(值)的陣列。當然,你可以盡量新增多個事件到這組陣列來滿足應用程式的需求。例如,讓我們新增 `OrderShipped` 事件: /** - * The event listener mappings for the application. + * 應用程式的事件監聽器映射。 * * @var array */ @@ -38,19 +38,19 @@ The `EventServiceProvider` included with your Laravel application provides a con ]; -### Generating Events & Listeners +### 產生事件與監聽器 -Of course, manually creating the files for each event and listener is cumbersome. Instead, simply add listeners and events to your `EventServiceProvider` and use the `event:generate` command. This command will generate any events or listeners that are listed in your `EventServiceProvider`. Of course, events and listeners that already exist will be left untouched: +當然,為每個事件和監聽器手動建立檔案是件麻煩的事情。不過,你可以簡單的新增監聽器和事件到 `EventServiceProvider`,並使用 `event:generate` 指令。這個指令會產生在 `EventServiceProvider` 被列出的任何事件或監聽器。當然,已存在的事件和監聽器就不會被動到: php artisan event:generate -### Manually Registering Events +### 手動註冊事件 -Typically, events should be registered via the `EventServiceProvider` `$listen` array; however, you may also register Closure based events manually in the `boot` method of your `EventServiceProvider`: +通常事件會透過 `EventServiceProvider` 的 `$listen`陣列來註冊。不過,你也可以在 `EventServiceProvider` 的 `boot` 方法手動以閉包的方式註冊事件: /** - * Register any other events for your application. + * 為你的應用程式註冊其他任何事件。 * * @return void */ @@ -63,18 +63,18 @@ Typically, events should be registered via the `EventServiceProvider` `$listen` }); } -#### Wildcard Event Listeners +#### 使用萬用字元的事件監聽器 -You may even register listeners using the `*` as a wildcard parameter, allowing you to catch multiple events on the same listener. Wildcard listeners receive the event name as their first argument, and the entire event data array as their second argument: +你甚至可以使用 `*` 作為萬用字元參數來註冊監聽器,可以讓你在同個監聽器上抓到多個事件。萬用字元的監聽器將接收到的名稱作為它們的第一個參數,並將整個事件資料的陣列作為第二個參數: Event::listen('event.*', function ($eventName, array $data) { // }); -## Defining Events +## 定義事件 -An event class is simply a data container which holds the information related to the event. For example, let's assume our generated `OrderShipped` event receives an [Eloquent ORM](/docs/{{version}}/eloquent) object: +事件類別是保存與事件相關的資訊的資料容器。例如,假設我們產生的 `OrderShipped` 事件要去接收 [Eloquent ORM](/docs/{{version}}/eloquent) 物件: -## Defining Listeners +## 定義監聽器 -Next, let's take a look at the listener for our example event. Event listeners receive the event instance in their `handle` method. The `event:generate` command will automatically import the proper event class and type-hint the event on the `handle` method. Within the `handle` method, you may perform any actions necessary to respond to the event: +接著,讓我們看一下範例事件的監聽器。事件監聽器會在它們的 `handle` 方法接收事件實例。`event:generate` 指令會自動導入合適的事件類別並在 `handle` 方法注入事件。在 `handle` 方法中,你可以執行任何必要的操作來回應事件: order... + // 使用 $event->order 存取訂單... } } -> {tip} Your event listeners may also type-hint any dependencies they need on their constructors. All event listeners are resolved via the Laravel [service container](/docs/{{version}}/container), so dependencies will be injected automatically. +> {tip} 事件監聽器也可以在建構子上注入任何需要的依賴。所有的事件監聽器都會透過 Laravel [服務容器](/docs/{{version}}/container)來解析,所以依賴才會被自動注入。 -#### Stopping The Propagation Of An Event +#### 停止一個事件的傳播 -Sometimes, you may wish to stop the propagation of an event to other listeners. You may do so by returning `false` from your listener's `handle` method. +有時候,你可能希望停止一個事件的傳播到其他的監聽器。你可以在監聽器的 `handle` 方法回傳 `false` 達到這項目的。 -## Queued Event Listeners +## 隊列事件監聽器 -Queueing listeners can be beneficial if your listener is going to perform a slow task such as sending an e-mail or making an HTTP request. Before getting started with queued listeners, make sure to [configure your queue](/docs/{{version}}/queues) and start a queue listener on your server or local development environment. +使用隊列監聽器會是有助於你的隊列要執行一個要處理很久的任務,像是發送電子郵件或發出 HTTP 請求。在使用隊列監聽器之前,請先確認你的[隊列設定](/docs/{{version}}/queues),並在你的伺服器或本機開發環境啟動隊列監聽器。 -To specify that a listener should be queued, add the `ShouldQueue` interface to the listener class. Listeners generated by the `event:generate` Artisan command already have this interface imported into the current namespace, so you can use it immediately: +要讓監聽器能夠被指定隊列,新增 `ShouldQueue` 介面到監聽器的類別。由 Artisan 指令的 `event:generate` 產生的監聽器會同時把這個介面導入當前的命名空間中,所以你可以馬上使用它: -### Manually Accessing The Queue +### 手動存取隊列 -If you need to manually access the listener's underlying queue job's `delete` and `release` methods, you may do so using the `Illuminate\Queue\InteractsWithQueue` trait. This trait is imported by default on generated listeners and provides access to these methods: +如果你需要手動存取監聽器底層的隊列任務的 `delete` 和 `release` 方法,你可以使用 `Illuminate\Queue\InteractsWithQueue` trait 來做。這個 trait 預設會導入剛產生的監聽器中,並提供存取這些方法: -### Handling Failed Jobs +### 處理失敗的任務 -Sometimes your queued event listeners may fail. If queued listener exceeds the maximum number of attempts as defined by your queue worker, the `failed` method will be called on your listener. The `failed` method receives the event instance and the exception that caused the failure: +有時隊列中的事件監聽器可能會失敗。如果隊列監聽器的嘗試執行超過了隊列器定義的最大嘗試次數,會在你的監聽器上呼叫 `failed` 方法。`failed` 方法會接收事件實例和導致失敗的例外: -## Dispatching Events +## 調度事件 -To dispatch an event, you may pass an instance of the event to the `event` helper. The helper will dispatch the event to all of its registered listeners. Since the `event` helper is globally available, you may call it from anywhere in your application: +想要調度一個事件,你可以傳入一個事件實例到 `event` 輔助函式。輔助函式會指派事件到它註冊的所有監聽器。因為 `event` 輔助函式是全域可用的,你可以在應用程式的任何地方呼叫它: {tip} When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](/docs/{{version}}/mocking#event-fake) makes it a cinch. +> {tip} 在測試的時候,它是有助於斷言某些沒有實際觸發監聽器的事件。Laravel 的[內建測試的輔助函式](/docs/{{version}}/mocking#event-fake)將它設計得很簡單。 -## Event Subscribers +## 事件訂閱者 -### Writing Event Subscribers +### 撰寫事件訂閱者 -Event subscribers are classes that may subscribe to multiple events from within the class itself, allowing you to define several event handlers within a single class. Subscribers should define a `subscribe` method, which will be passed an event dispatcher instance. You may call the `listen` method on the given dispatcher to register event listeners: +事件訂閱者可以從類別中訂閱多個事件的類別,可讓你在單一類別中定義多個事件處理器。訂閱者會定義 `subscribe` 方法,該方法會被傳入事件指派器實例。你可以在給定指派器上呼叫 `listen` 方法來註冊事件監聽器: -### Registering Event Subscribers +### 註冊事件訂閱者 -After writing the subscriber, you are ready to register it with the event dispatcher. You may register subscribers using the `$subscribe` property on the `EventServiceProvider`. For example, let's add the `UserEventSubscriber` to the list: +撰寫訂閱者後,你就已經準備好註冊它與事件指派器。你可以使用在 `EventServiceProvider` 上的 `$subscribe` 屬性註冊訂閱者。例如,我們新增 `UserEventSubscriber` 到清單上: