イベント

symfony のコアコンポーネントは sfEventDispatcher オブジェクトによって疎結合されています。イベントディスパッチャ (Event Dispatcher) はコアコンポーネントのあいだのコミュニケーションを司ります。

あるオブジェクトがディスパッチャにイベントを通知すれば、ディスパッチャに接続しているほかのオブジェクトがそのイベントをリスニングできるようになります。

イベントは単なる名前で、ドット (.) で区切られた名前空間と名前からなります。

使いかた

最初にイベントオブジェクトを作ります。

[php]
$event = new sfEvent($this, 'user.change_culture', array('culture' => $culture));

そしてディスパッチャにイベントを通知させます。

$dispatcher->notify($event);

sfEvent コンストラクタは3つの引数をとります。

  • イベントの「サブジェクト (対象)」 (ほとんどの場合、これはイベントを通知するオブジェクトになりますが、null にもなります)
  • イベントの名前
  • リスナーに渡すパラメータの配列

リスナーがイベントをリスニングできるようにするために、リスナーをディスパッチャに接続させます。

[php]
$dispatcher->connect('user.change_culture', array($this, 'listenToChangeCultureEvent'));

ディスパッチャの connect メソッドは2つの引数をとります。

  • イベントの名前
  • イベントが通知されるときに呼び出される関数/メソッド

リスナーの実装例は次のようになります。

[php]
public function listenToChangeCultureEvent(sfEvent $event)
{
  // メッセージフォーマットオブジェクトを新しいカルチャで変更します
  $this->setCulture($event['culture']);
}

リスナーはイベントを第1引数にとります。イベントオブジェクトにはイベント情報を提供するためのメソッドがいくつか備わっています。

  • getSubject(): イベントにアタッチされているサブジェクトオブジェクトを取得します。
  • getParameters(): イベントパラメータを返します。

配列方式によるイベントオブジェクトへのアクセス方法も用意されています。

イベントの種類

イベントは3つの異なるメソッドによって作られます。

  • notify()
  • notifyUntil()
  • filter()

~notify~

notify() メソッドはすべてのリスナーに通知します。リスナーは値を返すことはできません。すべてのリスナーの実行は保証されています。

~notifyUntil~

1つのリスナーが true の値を返されることで、チェーンが止まるまで、notifyUntil() メソッドはすべてのリスナーに通知しつづけます。

チェーンを止めるリスナーは setReturnValue() メソッドを呼び出すこともできます。

リスナーが処理ずみのイベントをもっていることをチェックするには、通知オブジェクトのなかで isProcessed() メソッドを呼び出します。

[php]
if ($event->isProcessed())
{
  // ...
}

~filter~

filter() メソッドは、通知オブジェクトから第2引数に渡される任意の値にフィルタをかけ、リスナーの第2引数に渡される関数/メソッドによって結果がとり出されたことを通知します。すべてのリスナーは受けとった値にフィルタをかけて返さなければなりません。すべてのリスナーの実行は保証されています。

通知オブジェクトは getReturnValue() メソッドを呼び出すことで、フィルタ処理ずみの値を得ることができます。

[php]
$ret = $event->getReturnValue();

イベント

application

~application.log~

通知メソッド: notify

デフォルトの通知オブジェクト: さまざまなクラス

| パラメータ | 説明 | ------------ | ---------------------------------------------------------------------------------- | priority | 優先順位 (sfLogger::EMERG、sfLogger::ALERT、sfLogger::CRIT、sfLogger::ERR、 sfLogger::WARNING、sfLogger::NOTICE、sfLogger::INFO もしくは sfLogger::DEBUG)

application.log イベントは HTTP リクエストのロギングシステムに利用されています (logger ファクトリをご参照ください)。さまざまな symfony のコアコンポーネントがこのイベントを通知します。

~application.throw_exception~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfException

リクエスト処理のあいだに捕まえられない例外が投げられたときに application.throw_exception イベントが通知されます。

このイベントをリスニングしていれば、捕まえられない例外が投げられた場合に、メールを送信する、もしくはエラーログに記録するなどの措置を講じることができます。イベントを扱うことで、symfony におけるデフォルトの例外管理メカニズムをオーバーライドすることもできます。

command

~command.log~

通知メソッド: notify

デフォルトの通知オブジェクト: sfCommand* クラス

| パラメータ | 説明 | ------------ | ----------------------------------------------------------------------------------- | priority | 優先順位 (sfLogger::EMERG、sfLogger::ALERT、sfLogger::CRIT、sfLogger::ERR、 sfLogger::WARNING、sfLogger::NOTICE、sfLogger::INFO もしくは sfLogger::DEBUG)

command.log イベントは symfony CLI ユーティリティによるロギングにも利用できます (logger ファクトリをご参照ください)。

~command.pre_command~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfTask

| パラメータ | 説明 | ------------ | ------------------------------ | arguments | CLI に渡される引数の配列 | options | CLI に渡されるオプションの配列

タスクの実行直前に command.pre_command イベントが通知されます。

~command.post_command~

通知メソッド: notify

デフォルトの通知オブジェクト: sfTask

タスクの実行直後に command.post_command イベントが通知されます。

~command.filter_options~

通知メソッド: filter

デフォルトの通知オブジェクト: sfTask

| パラメータ | 説明 | ----------------- | ------------------------------- | command_manager | sfCommandManager のインスタンス

タスクオプションが CLI によってパースされる前に command.filter_options イベントが通知されます。このイベントはユーザーに渡すオプションにフィルタをかけます。

configuration

~configuration.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfProjectConfiguration

| パラメータ | 説明 | ------------ | ----------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfProjectConfiguration クラスで定義されていなければ、configuration.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

component

~component.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfComponent

| パラメータ | 説明 | ------------ | ----------------------------------- | method | 呼び出されたが見つからなかったメソッド | arguments | メソッドに渡される引数

呼び出されたメソッドが sfComponent クラスで定義されていなければ、component.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

context

~context.load_factories~

通知メソッド: notify

デフォルトの通知オブジェクト: sfContext

すべてのファクトリが初期化された直後から、リクエストが来るたびに、sfContext オブジェクトによって context.load_factories イベントが1回通知されます。すべてのコアクラスが初期化された際にこのイベントが最初に通知されます。

context.method_not_found

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfContext

| パラメータ | 説明 | ----------- | ----------------------------------- | method | 呼び出されたが見つからなかったメソッド | arguments | メソッドに渡される引数

sfContext クラスで定義されていないメソッドが呼び出された際に context.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

controller

~controller.change_action~

通知メソッド: notify

デフォルトの通知オブジェクト: sfController

| パラメータ | 説明 | ------------ | --------------------------- | module | 実行されるモジュールの名前 | action | 実行されるアクションの名前

アクションが実行される直前に controller.change_action イベントが通知されます。

~controller.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfController

| パラメータ | 説明 | ------------ | ----------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfController クラスで定義されていなければ、controller.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

~controller.page_not_found~

通知メソッド: notify

デフォルトの通知オブジェクト: sfController

| パラメータ | 説明 | ------------ | ------------------------------------ | module | 404エラーが発生したモジュールの名前 | action | 404エラーが発生したアクションの名前

リクエスト処理のあいだに404エラーが発生したときに controller.page_not_found イベントが通知されます。

このイベントをリスニングしていれば、404ページが表示されるときに、メールを送信する、エラー、イベントのログをとるなどの措置を講じることができます。

debug

debug.web.load_panels

通知メソッド: notify

デフォルトの通知オブジェクト: sfWebDebug

sfWebDebug インスタンスの configure() メソッドを呼び出した後に、debug.web.load_panels イベントが通知されます。このイベントをパネルの管理に使うことができます。

debug.web.view.filter_parameter_html

通知メソッド: filter

デフォルトの通知オブジェクト: sfWebDebugPanelView

| パラメータ | 説明 | ----------- | ----------------------------- | parameter | フィルタをかけるパラメータ

debug.web.view.filter_parameter_html イベントは sfWebDebugPanelView パネルによってレンダリングされるそれぞれのパラメータにフィルタをかけます。

doctrine

doctrine.configure

通知メソッド: notify

デフォルトの通知オブジェクト: sfDoctrinePluginConfiguration

Doctrine プラグインのコンフィギュレーションが変更された後で doctrine.configure イベントが通知されます。

doctrine.filter_model_builder_options

通知メソッド: filter

デフォルトの通知オブジェクト: sfDoctrinePluginConfiguration

doctrine.filter_model_builder_options イベントは Doctrine スキーマビルダーのオプションにフィルタをかけます。

doctrine.filter_cli_config

通知メソッド: filter

デフォルトの通知オブジェクト: sfDoctrinePluginConfiguration

doctrine.filter_cli_config イベントは Doctrine CLI のコンフィギュレーション配列にフィルタをかけます。

doctrine.configure_connection

通知メソッド: notify

デフォルトの通知オブジェクト: Doctrine_Manager (sfDoctrineDatabase)

| パラメータ | 説明 | ------------ | -------------------------------------- | connection | Doctrine_Connection のインスタンス | database | sfDoctrineDatabase のインスタンス

Doctrine のデータベースオブジェクトがはじめて初期化されたときに doctrine.configure_connection イベントが通知されます。

doctrine.admin.delete_object

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータのモジュールクラス

| パラメータ | 説明 | --------- | ------------------------------ | object | 削除された Doctrine オブジェクト

アドミンジェネレータモジュールのなかで Doctrine オブジェクトが削除されたときに doctrine.admin.delete_object イベントが通知されます。

doctrine.admin.save_object

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

| パラメータ | 説明 | --------- | -------------------------------- | object |保存された Doctrine オブジェクト

アドミンジェネレータモジュールのなかで Doctrine オブジェクトが保存されたときに doctrine.admin.save_object イベントが通知されます。

doctrine.admin.build_query

通知メソッド: filter

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

アドミンジェネレータモジュールのなかで Doctrine Query オブジェクトが生成されたときに doctrine.admin.build_query イベントが通知されます。

doctrine.admin.pre_execute

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

| パラメータ | 説明 | ---------------- | ----------- | configuration | アドミンジェネレータのコンフィギュレーションオブジェクト

アドミンジェネレータモジュールの preExecute() メソッドが呼び出されたときに doctrine.admin.pre_execute イベントが通知されます。

form

~form.post_configure~

通知メソッド: notify

デフォルトの通知オブジェクト: sfFormSymfony

form.post_configure イベントはフォームのコンフィギュレーションが変更されたときに通知されます。

~form.filter_values~

通知メソッド: filter

デフォルトの通知オブジェクト: sfFormSymfony

form.filter_values イベントは、バインドされる直前の、マージされ、汚染されているパラメータとファイルの配列にフィルタをかけます。

~form.validation_error~

通知メソッド: notify

デフォルトの通知オブジェクト: sfFormSymfony

| パラメータ | 説明 | ------------ | --------------------- | error | エラーのインスタンス

フォームバリデーションが通らないときに form.validation_error イベントはつねに通知されます。

~form.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfFormSymfony

| パラメータ | 説明 | ------------ | ---------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfFormSymfony クラスで定義されていなければ、form.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

mailer

mailer.configure

通知メソッド: notify

デフォルトの通知オブジェクト: sfMailer

メーラーのコンフィギュレーションが変更された後で mailer.configure イベントが通知されます。メーラーのインスタンスはイベントのサブジェクトです。

plugin

~plugin.pre_install~

通知メソッド: notify

デフォルトの通知オブジェクト: sfPluginManager

| パラメータ | 説明 | ------------ | ------------------------------------------------------------------------------------ | channel | プラグインのチャンネル | plugin | プラグインの名前 | is_package | ローカルパッケージ (true)、もしくは Web 公開パッケージ (false) をインストールするかどうか

プラグインがインストールされる直前に plugin.pre_install イベントが通知されます。

~plugin.post_install~

通知メソッド: notify

デフォルトの通知オブジェクト: sfPluginManager

| パラメータ | 説明 | ------------ | ------------------------ | channel | プラグインのチャンネル | plugin | プラグインの名前

プラグインがインストールされた直後に plugin.post_install イベントが通知されます。

~plugin.pre_uninstall~

通知メソッド: notify

デフォルトの通知オブジェクト: sfPluginManager

| パラメータ | 説明 | ------------ | ------------------------ | channel | プラグインのチャンネル | plugin | プラグインの名前

プラグインがアンインストールされる直前に plugin.pre_uninstall イベントが通知されます。

~plugin.post_uninstall~

通知メソッド: notify

デフォルトの通知オブジェクト: sfPluginManager

| パラメータ | 説明 | ------------ | ----------------------- | channel | プラグインのチャンネル | plugin | プラグインの名前

プラグインがアンインストールされた直後に plugin.post_uninstall イベントが通知されます。

propel

propel.configure

通知メソッド: notify

デフォルトの通知オブジェクト: sfPropelPluginConfiguration

Propel プラグインのコンフィギュレーションが変更された後で propel.configure イベントが通知されます。

propel.filter_phing_args

通知メソッド: filter

デフォルトの通知オブジェクト: sfPropelBaseTask

propel.filter_phing_args イベントは Propel CLI のコンフィギュレーション配列にフィルタをかけます。

propel.filter_connection_config

通知メソッド: filter

デフォルトの通知オブジェクト: sfPropelDatabase

| パラメータ | 説明 | ------------ | ---------------------------------- | name | コネクションの名前 | database | sfPropelDatabase のインスタンス

Propel データベースが最初に初期化されたときに propel.filter_connection_config イベントが通知されます。

propel.admin.delete_object

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

| パラメータ | 説明 | --------- | ----------- | object | 削除された Propel オブジェクト

Propel オブジェクトが削除されたときに propel.admin.delete_object イベントが通知されます。

propel.admin.save_object

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

| パラメータ | 説明 | --------- | ------------------------------ | object | 保存された Propel オブジェクト

アドミンジェネレータモジュールのなかで Propel オブジェクトが保存されたときに propel.admin.save_object イベントが通知されます。

propel.admin.build_criteria

通知メソッド: filter

デフォルトの通知オブジェクト: アドミンジェネレータモジュールのクラス

アドミンジェネレータモジュールのなかで Propel の Criteria が生成されたときに propel.admin.build_criteria イベントが通知されます。

propel.admin.pre_execute

通知メソッド: notify

デフォルトの通知オブジェクト: アドミンジェネレータモジュールクラス

| パラメータ | 説明 | ---------------- | --------------------------------------------------------- | configuration | アドミンジェネレータのコンフィギュレーションオブジェクト

アドミンジェネレータモジュールの preExecute() メソッドが呼び出されたときに propel.admin.pre_execute イベントが通知されます。

request

~request.filter_parameters~

通知メソッド: filter

デフォルトの通知オブジェクト: sfWebRequest

| パラメータ | 説明 | ------------ | ----------------- | path_info | リクエストのパス

リクエストパラメータが初期化されたときに request.filter_parameters イベントが通知されます。

~request.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfRequest

| パラメータ | 説明 | ----------- | ------------------------------------------ | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfRequest クラスで定義されていなければ、request.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

response

~response.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfResponse

| パラメータ | 説明 | ----------- | ------------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfResponse クラスで定義されていなければ、response.method_not_found イベントが通知されます。このメソッドをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

~response.filter_content~

通知メソッド: filter

デフォルトの通知オブジェクト: sfResponse

レスポンスが送信される前に response.filter_content イベントが通知されます。このイベントをリスニングしていれば、送信される前のレスポンスの内容に手を加えることができます。

routing

~routing.load_configuration~

通知メソッド: notify

デフォルトの通知オブジェクト: sfRouting

ルーティングファクトリがルーティングコンフィギュレーションをロードしたときに routing.load_configuration イベントが通知されます。

task

~task.cache.clear~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfCacheClearTask

| パラメータ | 説明 | ---------- | -------------------------- | app | アプリケーションの名前 | type | キャッシュの種類 (all、config、i18n、routing、module、そして template) | env | 環境

キャッシュが cache:clear タスクによって一掃されたときに task.cache.clear イベントが通知されます。

template

~template.filter_parameters~

通知メソッド: filter

デフォルトの通知オブジェクト: sfViewParameterHolder

ビューファイルがレンダリングされる前に template.filter_parameters イベントが通知されます。このイベントをリスニングしていれば、テンプレートに渡される変数にアクセスして、変数に収められている値を書き換えることができます。

user

~user.change_culture~

通知メソッド: notify

デフォルトの通知オブジェクト: sfUser

| パラメータ | 説明 | ----------- | ----------------- | culture | ユーザーカルチャ

リクエストのあいだにユーザーカルチャが変更されたときに user.change_culture イベントが通知されます。

~user.method_not_found~

通知メソッド: notifyUntil

デフォルトの通知オブジェクト: sfUser

| パラメータ | 説明 | ----------- | ------------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfUser クラスで定義されていなければ、user.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

~user.change_authentication~

通知メソッド: notify

デフォルトの通知オブジェクト: sfBasicSecurityUser

| パラメータ | 説明 | --------------- | ---------------------------------- | authenticated | ユーザーが認証されているかどうか

ユーザーの認証ステータスが変更されるたびに user.change_authentication イベントが通知されます。

view

~view.configure_format~

通知メソッド: notify

デフォルトの通知オブジェクト: sfView

| パラメータ | 説明 | ---------- | ------------------------------- | format | リクエストされたフォーマット | response | レスポンスオブジェクト | request | リクエストオブジェクト

リクエストにおいて sf_format パラメータセットが存在しているときに view.configure_format イベントが通知されます。symfony が設定を変更するもしくはレイアウトの設定を解除するなどの処理を施した後でこのイベントが通知されます。このイベントによってリクエストされたフォーマットに応じてビューとレスポンスオブジェクトを変更することができます。

~view.method_not_found~

通知メソッド: notifyUntil

通知元クラス: sfView

| パラメータ | 説明 | ----------- | ------------------------------------------- | method | 呼び出されたが見つからなかったメソッドの名前 | arguments | メソッドに渡される引数

呼び出されたメソッドが sfView クラスで定義されていなければ、view.method_not_found イベントが通知されます。このイベントをリスニングしていれば、継承を使わなくても、クラスにメソッドを追加できます。

view.cache

~view.cache.filter_content~

通知メソッド: filter

デフォルトの通知オブジェクト: sfViewCacheManager

| パラメータ | 説明 | ---------- | ---------------------------------------------------------- | response | レスポンスオブジェクト | uri | キャッシュずみのコンテンツの URI | new | コンテンツがキャッシュのなかで新しいものであるかどうか

view.cache.filter_content イベントはキャッシュからコンテンツが読み込まれるたびに通知されます。