bitrix-events

Bitrix イベント

基準：main 23.0+ · 検証済み：main 26.800.0

ディスパッチャーによってハンドラーのシグネチャが決まります

ディスパッチャー（呼び出し元で確認）	例	ハンドラーが受け取る値	結果
new Event(...) + ->send()	独自イベント、main:OnBeforeMailSend、ORM タブレットイベント	VERSION 2（registerEventHandler、addEventHandler）：Event オブジェクト。VERSION 1（*Compatible）：...array_values($params)	$event->getResults()。EventResult 以外の戻り値は UNDEFINED としてラップされます
GetModuleEvents() + ExecuteModuleEventEx()（レガシー）	main:OnBeforeUserAdd、OnAfterUserAdd、OnPageStart、OnEpilog、iblock:OnBeforeIBlockElementAdd	生の引数。登録時に指定された VERSION に関係なく、たとえば array &$arFields	呼び出し元によって異なります

• レガシーな OnBefore*：キャンセルするには $APPLICATION->ThrowException('…'); return false; とします（呼び出し元は === false を確認します）。参照 &$arFields を通じてデータを変更します。戻り値の配列（['FIELDS' => …]）は無視されます。
• ORM タブレット／ハイロードレコードイベントでは Bitrix\Main\ORM\EventManager と ORM\EventResult::modifyFields() を使用します。bitrix-orm を参照してください。HL イベント名については bitrix-highloadblock を参照してください。

D7 イベントを公開する

php bitrix.php make:event PostCreated -m vendor.blog -C Post（main 25.900 以降。それ以前はクラスを作成します）→ Vendor\Blog\Public\Event\Post\PostCreatedEvent（-C なしの場合：…\Public\Event\）。生成されたクラスにはパラメーターが渡されないため、追加してください：

namespace Vendor\Blog\Public\Event\Post;

use Bitrix\Main\Event;

final class PostCreatedEvent extends Event
{
    public function __construct(public readonly int $postId, public readonly int $authorId)
    {
        parent::__construct('vendor.blog', 'PostCreated', ['postId' => $postId, 'authorId' => $authorId]);
    }
}

$event = new PostCreatedEvent($post->getId(), $post->getAuthorId());
$event->send();
foreach ($event->getResults() as $result)
{
    if ($result->getType() === \Bitrix\Main\EventResult::ERROR)
    {
        // caller decides: abort, log, collect errors
    }
}

理由を付けてキャンセルするには、new EventResult(EventResult::ERROR, ['error' => new Error('…', 'CODE')]) を返します。この結果を尊重するのは、それを読み取る呼び出し元のみです（メールイベントについては bitrix-mail を参照）。

イベントを処理する

php bitrix.php make:eventhandler PostCreated --event-module=vendor.blog -m vendor.notify — name はイベント名、-m はハンドラーモジュールです → Vendor\Notify\Internals\Integration\Vendor\Blog\EventHandler\PostCreatedEventHandler::handle(PostCreatedEvent $event)。イベントクラスの不足している use を追加してください。

public static function handle(PostCreatedEvent $event): EventResult
{
    $notifier = ServiceLocator::getInstance()->get(Notifier::class);
    $result = $notifier->notifyAuthor($event->authorId);

    return new EventResult($result->isSuccess() ? EventResult::SUCCESS : EventResult::ERROR, $result->getErrorMessages());
}

ハンドラーは静的コールバックであり、コンテナーによって生成されることはありません。サービスは内部で解決してください（bitrix-framework）。

登録する

永続登録（モジュールインストーラーで登録し、DoUninstall で同じ引数を使って登録解除します）：

EventManager::getInstance()->registerEventHandler(
    fromModuleId: 'vendor.blog',
    eventType: 'PostCreated',
    toModuleId: 'vendor.notify',
    toClass: PostCreatedEventHandler::class,
    toMethod: 'handle',
);

• registerEventHandlerCompatible()（引数は同じ、VERSION 1）：D7 イベントは Event の代わりに ...array_values($params) を渡します。レガシーな ExecuteModuleEventEx イベントでは、どちらの呼び出しでも生の引数が渡されます。カーネルでは慣例として、これらのイベントに *Compatible を使用します。
• main 26.600* 以降：install/migrations/events.php でハンドラーを宣言します（register() = VERSION 2、registerCompatible() = VERSION 1）。bitrix-modules を参照してください。
• リクエスト単位のみ：addEventHandler($fromModuleId, $eventType, $callback, $includeFile = false, $sort = 100)（VERSION 2）／addEventHandlerCompatible()（VERSION 1）。たとえば init.php から呼び出します。
• 実行順：$sort の昇順（デフォルトは 100）。addEventHandler では第 5 引数、registerEventHandler では第 6 引数です。
• Event::send() は ERROR の後もすべてのハンドラーを実行しますが、ハンドラー内で例外がスローされるとチェーンが停止し、呼び出し元に伝播します。

チェックリスト

• ハンドラーのシグネチャがディスパッチャーと一致している（Event と生の &$arFields）。
• すべての registerEventHandler に対し、アンインストール時に同一の引数で unRegisterEventHandler を実行している。
• 名前付き引数にカーネルの名前を使用している（fromModule ではなく fromModuleId）。
• ハンドラー内で例外を捕捉して記録している。重い処理は Messenger に渡している（bitrix-background-jobs）。
• 独自イベントは lib/Public/Event/ に、ハンドラーは lib/Internals/Integration/<Module>/EventHandler/ に配置している。