> For the complete documentation index, see [llms.txt](https://docs.chamilo.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chamilo.org/3.x/zh-tw/kai-fa-zhe-zhi-nan/developer-guide/backend/events-and-listeners.md).

# 事件與監聽器

Chamilo 使用 Symfony 的事件系統，讓元件之間能以解耦方式溝通。

## 事件監聽器

Chamilo 使用兩個監聽器位置：

* **`src/CoreBundle/EventListener/`** — Symfony kernel／HTTP 監聽器（request、response、exception、登入／登出、課程／工作階段存取等）。範例：`CidReqListener`、`CourseAccessListener`、`LoginSuccessHandler`、`LogoutListener`、`ExceptionListener`、`ResourceDoctrineListener`。
* **`src/CoreBundle/Entity/Listener/`** — 附加於特定實體的 Doctrine 實體監聽器。範例：`ResourceNodeListener`、`CourseListener`、`SessionListener`、`LanguageListener`、`UserListener`、`MessageListener`。

請依您要回應的對象選擇位置：HTTP 管線事件放在 `EventListener/`；實體生命週期掛鉤放在 `Entity/Listener/`。

## 事件訂閱者

位於 `src/CoreBundle/EventSubscriber/`：

事件訂閱者可監聽多個事件：

* **安全性訂閱者** — 處理登入／登出事件、追蹤登入嘗試
* **API 訂閱者** — API 請求的前置／後置處理
* **Doctrine 訂閱者** — 回應實體生命週期事件

## Doctrine 生命週期事件

實體使用 `#[ORM\HasLifecycleCallbacks]` 處理資料庫層級事件：

```php
#[ORM\PrePersist]
public function prePersist(): void
{
    $this->createdAt = new DateTime();
}
```

## 建立自訂監聽器

若要加入自訂行為：

1. 在適當的 bundle 中建立監聽器／訂閱者類別
2. 在服務設定中將其標記為事件監聽器或訂閱者
3. 實作處理方法

```php
class MyListener
{
    public function onKernelRequest(RequestEvent $event): void
    {
        // Your logic here
    }
}
```

## 重要事件

| 事件                           | 觸發時機         |
| ---------------------------- | ------------ |
| `kernel.request`             | 每一次 HTTP 請求  |
| `kernel.response`            | 傳送 HTTP 回應之前 |
| `security.interactive_login` | 使用者登入時       |
| `doctrine.prePersist`        | 實體首次儲存之前     |
| `doctrine.postUpdate`        | 實體更新之後       |

## Chamilo 專屬事件

這些事件由 Chamilo 自身程式碼派發，是外掛的主要整合點。常數定義於 `Chamilo\CoreBundle\Event\Events`。

| 常數                                       | 事件字串                                           | 觸發時機           |
| ---------------------------------------- | ---------------------------------------------- | -------------- |
| `Events::COURSE_CREATED`                 | `chamilo.event.course_created`                 | 課程建立之後         |
| `Events::COURSE_ACCESS_CHECK`            | `chamilo.course_access_check`                  | 使用者存取課程之前      |
| `Events::COURSE_USER_SUBSCRIPTION_CHECK` | `chamilo.event.course_user_subscription_check` | 使用者報名課程之前      |
| `Events::SESSION_RESUBSCRIPTION`         | `chamilo.event.session_resubscription`         | 使用者嘗試重新訂閱工作階段時 |
| `Events::LOGIN_CREDENTIALS_CHECKED`      | `chamilo.event.login_credentials_checked`      | 登入憑證驗證之後       |
| `Events::LOGIN_CONDITION_CHECKED`        | `chamilo.event.login_condition_checked`        | 額外登入條件檢查之後     |
| `Events::DOCUMENT_ACTION`                | `chamilo.event.document_action`                | 文件工具列工具列被呈現時   |
| `Events::DOCUMENT_ITEM_ACTION`           | `chamilo.event.document_item_action`           | 各檔案動作按鈕被呈現時    |
| `Events::DOCUMENT_ITEM_VIEW`             | `chamilo.event.document_item_view`             | 文件被開啟檢視時       |
| `Events::EXERCISE_REPORT_ACTION`         | `chamilo.event.exercise_report_action`         | 練習報告頁面呈現其動作連結時 |
| `Events::EXERCISE_ENDED`                 | `chamilo.event.exercise_ended`                 | 學習者提交練習之後      |
| `Events::EXERCISE_QUESTION_ANSWERED`     | `chamilo.event.question_answered`              | 每一題作答之後        |
| `Events::LP_CREATED`                     | `chamilo.event.learning_path_created`          | 學習路徑建立之後       |
| `Events::LP_ITEM_VIEWED`                 | `chamilo.event.learning_path_item_viewed`      | 學習者開啟學習路徑項目時   |
| `Events::LP_ENDED`                       | `chamilo.event.learning_path_ended`            | 學習者完成學習路徑之後    |
| `Events::ADMIN_BLOCK_DISPLAYED`          | `chamilo.event.admin_block_displayed`          | 管理儀表板建立區塊清單時   |
| `Events::USER_CREATED`                   | `chamilo.event.user_created`                   | 使用者帳號建立之後      |
| `Events::USER_UPDATED`                   | `chamilo.event.user_updated`                   | 使用者帳號更新之後      |
| `Events::USER_DELETED`                   | `chamilo.event.user_deleted`                   | 使用者帳號刪除之後      |
| `Events::PORTFOLIO_ITEM_ADDED`           | `chamilo.event.portfolio_item_added`           | 作品集項目建立之後      |
| `Events::NOTIFICATION_CONTENT_FORMATTED` | `chamilo_hook_event.notification_content`      | 通知內文被格式化時      |

## 外掛範例：在文件檢視器中加入按鈕

本節說明外掛如何使用事件訂閱者，將按鈕注入既有的 Chamilo 頁面——無需修改核心程式碼。

### 情境

名為 **MyViewer** 的外掛希望在課程檔案管理員中，於每個文件旁新增「在 MyViewer 中開啟」按鈕。相關事件為 `Events::DOCUMENT_ITEM_VIEW`，由 Chamilo 在即將顯示文件時派發，並攜帶 `CDocument` 實體以及一份可變的連結清單。

### 外掛目錄結構

```
public/plugin/MyViewer/
├── plugin.php                          # Declares $plugin_info
├── install.php / uninstall.php
├── admin.php                           # Plugin settings page
├── lang/                               # Translation strings
└── src/
    ├── MyViewerPlugin.php              # Main plugin class (extends Plugin)
    └── EventSubscriber/
        └── MyViewerEventSubscriber.php # Event subscriber
```

### 主要外掛類別（`src/MyViewerPlugin.php`）

```php
declare(strict_types=1);

class MyViewerPlugin extends Plugin
{
    public const SETTING_SERVER_URL = 'server_url';

    protected function __construct()
    {
        parent::__construct('1.0', 'Your Name', [
            self::SETTING_SERVER_URL => 'text',
        ]);
    }

    public static function create(): static
    {
        static $instance = null;
        return $instance ??= new self();
    }

    public function getViewerUrl(int $documentId): string
    {
        $base = $this->get(self::SETTING_SERVER_URL);
        return sprintf('%s/view?doc=%d', rtrim((string) $base, '/'), $documentId);
    }
}
```

`Plugin` 基底類別提供 `isEnabled()`、`get($settingKey)`，以及安裝課程工具與設定的輔助方法。單例模式（`static $instance`）是 Chamilo 的標準慣例，因為外掛類別也會在 Symfony 容器之外（舊版 PHP 頁面中）被實例化。

### 事件訂閱者（`src/EventSubscriber/MyViewerEventSubscriber.php`）

```php
declare(strict_types=1);

use Chamilo\CoreBundle\Event\DocumentItemViewEvent;
use Chamilo\CoreBundle\Event\Events;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MyViewerEventSubscriber implements EventSubscriberInterface
{
    private MyViewerPlugin $plugin;

    public function __construct()
    {
        $this->plugin = MyViewerPlugin::create();
    }

    public static function getSubscribedEvents(): array
    {
        return [
            Events::DOCUMENT_ITEM_VIEW => 'onDocumentItemView',
        ];
    }

    public function onDocumentItemView(DocumentItemViewEvent $event): void
    {
        if (!$this->plugin->isEnabled()) {
            return;
        }

        $document = $event->getDocument();

        $url = $this->plugin->getViewerUrl($document->getIid());
        $label = $this->plugin->get_lang('OpenInMyViewer');

        $event->addLink(sprintf(
            '<a href="%s" target="_blank" class="btn btn--plain">%s</a>',
            htmlspecialchars($url, ENT_QUOTES),
            htmlspecialchars($label, ENT_QUOTES)
        ));
    }
}
```

`addLink()` 會將 HTML 附加到陣列中，Chamilo 的文件檢視範本會將該陣列與內建的「下載」及「預覽」動作一併呈現。訂閱者絕不修改 Chamilo 核心檔案。

### 註冊

無需手動註冊服務。Chamilo 的 `config/services.yaml` 全域啟用 Symfony 的 `autoconfigure` 旗標，會自動將任何實作 `EventSubscriberInterface` 的類別標記為 `kernel.event_subscriber`。只要外掛目錄已載入（透過 Composer 的 classmap 或 PSR-4 自動載入），Symfony 會在下次清除快取時偵測到該訂閱者。

```bash
php bin/console cache:clear
```

### 事件資料如何流動

```
Document list rendered
        │
        ▼
Chamilo dispatches DocumentItemViewEvent (carries CDocument entity + empty links[])
        │
        ├─► MyViewerEventSubscriber::onDocumentItemView()  → appends HTML link
        ├─► OnlyofficeEventSubscriber::onDocumentItemView() → appends "Edit" button
        │   (any number of plugins can listen to the same event)
        ▼
Template renders event->getLinks() alongside built-in file actions
```

多個外掛可獨立訂閱同一事件；各自向共用資料附加內容，而無須知曉其他外掛。執行順序遵循 Symfony 的優先權系統——若順序重要，請在 `getSubscribedEvents()` 的處理函式元組中以第二個元素傳入優先權整數：

```php
public static function getSubscribedEvents(): array
{
    return [
        Events::DOCUMENT_ITEM_VIEW => ['onDocumentItemView', 10], // higher = earlier
    ];
}
```