Bốn pattern. Một file. Toàn bộ bề mặt mở rộng.

Bản đồ bốn pattern

Mọi hook trong codebase đều rơi vào đúng một trong bốn hình thái. Hình thái quyết định conflict semantics, cách xử lý giá trị trả về, và kiểu tương tác nào hợp lý giữa core và plugin. Chọn sai pattern sẽ hiện ra sau dưới dạng edge case lạ — biết cái nào là cái nào ngay từ đầu giúp tiết kiệm việc viết lại integration.

Một mental model hữu ích: REGISTRY trả lời "bạn muốn đóng góp gì"; EVENT trả lời "bạn có muốn biết không"; BEHAVIOR trả lời "tôi nên làm việc này như thế nào"; FILTER trả lời "cái này nên trở thành gì". Bốn section tiếp theo nói chi tiết từng pattern, với callsite thực tế đang chạy trong core.

REGISTRY — add() + collect()

Plugin đóng góp một hoặc nhiều item vào một danh sách được đặt tên. Host gọi collect() để lấy mảng mọi đóng góp. Mọi callback đều chạy, mọi giá trị trả về đều được giữ, theo thứ tự đăng ký.

Cơ chế

// Plugin (in ServiceProvider::boot())
Hook::add('register_sending_server_driver', fn() => [
    'type'   => 'postal',
    'driver' => '\\AcmeCorp\\Postal\\Driver',
    'name'   => 'Postal MTA',
]);

// Core (app/Model/SendingServer.php:191)
foreach (Hook::collect('register_sending_server_driver') as $meta) {
    $drivers[$meta['type']] = $meta['driver'];
}

Hook REGISTRY thực tế trong core

Khi nào dùng REGISTRY

• Nhiều plugin có thể đóng góp (sending driver, captcha method, sidebar item).
• Host muốn mọi đóng góp, không chỉ cái cuối cùng.
• Các đóng góp compose mà không xung đột — list item, menu entry, banner fragment, configuration metadata.

Convention đặt tên

Trong codebase, tên REGISTRY thường đọc như cụm động từ mô tả đóng góp: register_sending_server_driver, add_translation_file, captcha_method, generate_big_notice_for_sending_server. Tên có động từ số ít (register_*, add_*) gợi ý "đóng góp một item", nhưng cơ chế collect() vẫn gom mọi đóng góp — không có gì phía registration giới hạn plugin chỉ một entry.

EVENT — on() + fire()

Plugin phản ứng khi có gì đó xảy ra trong host. Giá trị trả về bị bỏ — contract một chiều: core thông báo, plugin compose side effect. Mọi listener đều chạy, theo thứ tự đăng ký.

Cơ chế

// Plugin (in ServiceProvider::boot())
Hook::on('customer_added', function ($customer) {
    LoyaltyPoints::award($customer, 100, 'welcome_bonus');
});

// Core (app/Model/Customer.php:1410)
Hook::fire('customer_added', [$customer]);

Hook EVENT thực tế core bắn ra

Khi nào dùng EVENT

• Plugin muốn phản ứng nhưng không cần ảnh hưởng đến outcome của core.
• Chỉ side effect — gửi webhook, ghi log, cộng điểm loyalty, dispatch queue job.
• Core đã commit hành động trước khi event fire; listener không thể cancel.

BEHAVIOR — set() + perform()

Một callable sở hữu behaviour được đặt tên. Host gọi perform() để chạy bất cứ ai đang đăng ký. set() chiếm tên độc quyền — nếu caller thứ hai cố set cùng tên, HookManager::set() throw exception ngay. Không có silent override; conflict surface lúc boot, không phải production.

Cơ chế

// Plugin overrides (in ServiceProvider::boot())
Hook::set('dispatch_list_import_job', fn($list, $file) =>
    new \\AcmeCorp\\FastImport\\FasterImportJob($list, $file));

// Core registers default + executes (app/Http/Controllers/SubscriberController.php:433)
Hook::setIfEmpty('dispatch_list_import_job', function ($list, $filepath) use ($request) {
    return new ImportJob($list, $filepath, $request);
});
$currentJob = Hook::perform('dispatch_list_import_job', [$list, $filepath]);
dispatch($currentJob);

Quy tắc timing setIfEmpty

Default của host đi qua setIfEmpty(), không phải set() — sự khác biệt này là cố ý. setIfEmpty chỉ đăng ký callback nếu chưa ai claim tên đó; nếu plugin đã gọi set trong boot(), default của host bị bỏ im lặng.

Điều đó có nghĩa setIfEmpty phải được đặt ngay trước perform(), trong controller hoặc model, không phải trong service provider. Lý do: khi request handler của controller chạy, mọi ServiceProvider::boot() của plugin đã xong — bất cứ override nào plugin đăng ký qua set đã có hiệu lực. Đặt default trong register() hoặc boot() có nguy cơ chạy trước set() của plugin và khóa nó ra.

Hook BEHAVIOR thực tế trong core

Khi nào dùng BEHAVIOR

• Đúng một đoạn logic nên chạy.
• Có default hợp lý, nhưng plugin nên có thể swap hoàn toàn.
• Hai plugin claim cùng behaviour là bug, không phải feature — bạn muốn nó fail loudly.

FILTER — modify() + filter()

Một giá trị đi qua một chain callback. Mỗi callback nhận giá trị hiện tại (cộng các positional args thêm) và trả về giá trị truyền cho cái tiếp theo. Host gọi <code>filter()</code> với giá trị khởi tạo; return là giá trị cuối sau khi mọi plugin đã có lượt.

Cơ chế

// Plugin (in ServiceProvider::boot())
Hook::modify('sidebar-menu-items', function (array $items) {
    array_splice($items, 1, 0, [
        ['label' => 'Loyalty', 'url' => route('loyalty_points.dashboard'), 'icon' => 'star'],
    ]);
    return $items;
});

// Core
$items = Hook::filter('sidebar-menu-items', $defaultItems);

Positional args tùy chọn

Hook::filter($name, $value, $extraParams) nhận mảng thứ ba các positional argument được truyền cho mọi callback cùng với giá trị hiện tại. Ví dụ contract từ plugin guide là maillist redirect:

// Plugin
Hook::modify('page.maillist.show.redirect', function ($redirect, $list, $request) {
    if (MyPlugin::shouldRedirect($list, $request->user())) {
        return redirect()->route('my_plugin.custom_page', $list->uid);
    }
    return $redirect; // null means "do not redirect"
});

// Core
$redirect = Hook::filter('page.maillist.show.redirect', null, [$list, $request]);
if ($redirect) {
    return $redirect;
}
// continue rendering

Khi nào dùng FILTER

• Một giá trị đi qua nhiều plugin trước khi host dùng.
• Mỗi plugin có thể compose với plugin trước — thêm vào menu, sửa nội dung email, điều kiện một redirect, biến đổi payload.
• Trả về input không đổi là cách opt-out theo convention — không exception, không tín hiệu đặc biệt.

FILTER là pattern ít được dùng nhất trong code base core hiện tại. Phần triển khai HookManager ổn định (dòng 143-159 của file), và contract đã được tài liệu cho plugin author, nhưng core chưa gọi Hook::filter trong các hot path production ngoài ví dụ page.maillist.show.redirect đã tài liệu. Các hot path host-side mới muốn có plugin-composable transform nên chọn FILTER hơn BEHAVIOR — chain semantics chính xác là điều hầu hết các tình huống "tôi muốn plugin có thể thêm vào cái này" cần.

Conflict semantics across the four patterns

Khi hai plugin nhắm cùng tên hook, bốn pattern phản ứng khác nhau. Biết bạn có loại pattern nào nói cho bạn chính xác conflict trông thế nào, và liệu nó sẽ surface lúc boot hay rất lâu sau.

Ba trong bốn pattern không có conflict vì chúng aggregate. BEHAVIOR là cái duy nhất có ownership exclusive, và failure mode là exception cứng lúc boot — một lựa chọn thiết kế có chủ ý để misuse không thể tồn tại cùng một install đang chạy.

Convention args-bag

Mọi fire / collect / perform / filter đều có cùng hình thái: $name, $value (hoặc default), $params. Mảng $params được unpack theo vị trí vào callback đã đăng ký. Mọi callback trong chain nhận cùng args.

• Giữ args bag nhỏ và ổn định. Một khi hook đã ship, args trở thành contract — thêm một positional arg break mọi plugin đã bind closure với signature cố định.
• Truyền model, không phải field bag. fire('customer_added', [$customer]) để listener tự quyết đọc field nào; fire('customer_added', [$customer->email, $customer->uid, ...]) sẽ khóa args vào những field tồn tại lúc hook ship.
• Dùng hook mới thay vì overload args. Nếu một slot cần context phong phú hơn, đăng ký một hook key riêng thay vì thêm positional arg thứ năm tùy chọn.

Quirk collect by-reference

Một phần nhỏ của core dùng collect() với argument by-reference như một mutation hook — nằm ngoài mô hình canonical bốn pattern. Callsite filter_aws_ses_dns_records là ví dụ tiêu biểu:

// app/Http/Controllers/Refactor/SendingController.php:812
Hook::collect('filter_aws_ses_dns_records', [&$identity, &$dkims, &$spf]);

Host fire hook kỳ vọng plugin mutate $dkims và $spf tại chỗ. Nói thẳng ra đây là misuse REGISTRY — một FILTER chain thật sự sẽ là hình thái đúng. Behaviour hoạt động vì closure PHP tôn trọng arg by-reference, nhưng plugin author không nên viết callsite mới theo style này. Hãy chọn FILTER (giá trị đơn được transform) hoặc REGISTRY (nhiều đóng góp immutable) thay vì.

Sáu anti-pattern cần tránh

Các pattern dưới đây đều trông đúng thoạt nhìn và hỏng theo cách tinh vi. Mỗi cái dựa trên một loại bug đã từng thấy trong plugin production.

1. Đăng ký hook trong register() khi chúng cần boot()

Hàm register() của host chạy trước boot() của mọi service provider. Hook đăng ký ở đó fire trước khi dependency được wire bởi register() của provider khác. Triệu chứng: Class not found ngay request đầu tiên, trước khi bất kỳ code plugin nào chạy main path. Fix: chỉ hook add_translation_file thuộc về register(); mọi thứ khác vào boot().

2. Chọn BEHAVIOR khi mục tiêu là "shared"

BEHAVIOR throw ở lần set thứ hai. Nếu hai plugin chính đáng cần ảnh hưởng cùng một điểm, FILTER (compose) hoặc REGISTRY (collect) là hình thái đúng. Fix: viết lại hook contract — emit một chain hoặc một list, không phải một callable exclusive.

3. Đặt setIfEmpty trong service provider

setIfEmpty chỉ có hiệu lực nếu chưa ai đăng ký. Đặt nó trong register() hoặc boot() có nghĩa là nó có thể chạy trước set() của plugin, khóa plugin ra. Fix: đặt setIfEmpty ngay phía trên lệnh perform tương ứng, trong controller hoặc model, để boot() của mọi plugin đã xong.

4. Mutate shared state bên trong callback REGISTRY

collect gọi mọi callback theo thứ tự đăng ký. Một callback ghi vào shared cache hoặc session như side effect làm hook non-deterministic — chạy nó hai lần với thứ tự plugin khác nhau cho ra state cache khác. Fix: giữ callback add thuần. Nếu đóng góp phụ thuộc vào side effect, đăng ký một EVENT listener riêng.

5. Thêm positional args vào hook đã có

Một khi hook đã trong production, plugin đã bind closure với arity gốc. Thêm positional arg thứ năm break mọi binding bỏ qua nó. Fix: đăng ký tên hook mới (customer_added_v2) và chấp nhận một window chuyển tiếp, hoặc truyền context mới qua model object đã có trong args bag.

6. Dùng collect() cho một câu trả lời duy nhất

REGISTRY trả về một mảng — ngay cả khi chỉ một plugin đăng ký, host vẫn nhận [$result]. Coi đó như câu trả lời ($first = Hook::collect(...)[0]) chọn im lặng plugin nào boot trước, không có conflict semantics. Fix: dùng BEHAVIOR nếu kỳ vọng đúng một câu trả lời.

Cách chọn pattern

Quyết định thường gói lại thành bốn câu hỏi. Trả lời theo thứ tự sẽ chọn được hình thái đúng:

1. Nhiều plugin có nên compose không? Nếu có, REGISTRY (đóng góp độc lập) hoặc FILTER (transform có chain). Nếu không, BEHAVIOR (override exclusive).
2. Host có cần giá trị trả về không? Nếu không, EVENT (chỉ side effect). Nếu có, REGISTRY / BEHAVIOR / FILTER.
3. Giá trị có đi qua nhiều bàn tay không? Nếu có, FILTER (chain). Nếu mỗi bàn tay đóng góp độc lập, REGISTRY (collect).
4. Conflict giữa hai plugin có phải là bug không? Nếu có, BEHAVIOR (fail to lúc boot). Nếu không, các pattern không-conflict.

Khi phân vân, chọn pattern lỏng hơn. REGISTRY cộng với một EVENT "out of band" cho cleanup hầu như luôn linh hoạt hơn BEHAVIOR — conflict semantics chính là thứ giết BEHAVIOR trong thực tế, và các pattern lỏng cho phép plugin compose không cần phối hợp.

Đi tiếp đến đâu

Bạn giờ có bốn pattern ở độ sâu và conflict semantics khiến mỗi hình thái có thể đoán định. Ba trang biến kiến thức này thành các bề mặt dùng hằng ngày mà một plugin thực sự sẽ chạm đến:

• UI injection — các hook REGISTRY mức layout (layout.head.assets, layout.body.before_close, admin.sidebar.groups) và contract page.{controller}.{action}.{slot} để inject card vào trang cụ thể mà không fork một Blade nào.
• Sending driver — ví dụ hoàn chỉnh kết hợp register_sending_server_driver (REGISTRY) với event activate_plugin_* + delete_plugin_* để ship một MTA backend hoàn toàn mới dưới dạng plugin.
• Payment gateway — pattern song song dùng contract của package Cashier cộng REGISTRY plugin của host để thêm gateway theo vùng hoặc crypto.