イベントフック

前のプラグインチュートリアルの章では、プラグインロジックが2つのメソッドに包含されていることにお気づきでしょうか。これらのメソッドonPluginsInitializedとonPageInitializedは、それぞれ Grav のライフサイクルを通じて利用可能なイベントフックに対応しています。

Grav プラグインを十分に活用するためには、どのイベントフックが利用可能で、どのような順番で呼び出され、呼び出し中に何が利用できるかを知っておく必要があります。イベントフックは、Grav のライフサイクル全体と直接的な関係があります。

イベントオーダー

Grav のほとんどのイベントは特定の順番で起動するので、プラグインを作成する場合は、この順番を理解することが重要です。

onFatalException (順序なし、いつでも発生)
PluginsLoadedEvent class (1.7)
PluginsLoadedEvent class (1.7)
onPluginsInitialized
FlexRegisterEvent class (1.7)
onThemeInitialized
onRequestHandlerInit (1.6)
onTask (1.6)
1. onTask.{task}
onAction (1.6)
1. onAction.{action} (1.6)
onBackupsInitialized
onSchedulerInitialized (1.6)
onAssetsInitialized
onTwigTemplatePaths
onTwigLoader
onTwigInitialized
onTwigExtensions
onBuildPagesInitialized (once when pages are reprocessed)
1. onPageProcessed (each page not cached yet)
2. onFormPageHeaderProcessed (1.6) (each page not cached yet)
3. onFolderProcessed (for each folder found)
onPagesInitialized
onPageInitialized
1. onPageContentRaw (each page not cached yet)
2. onMarkdownInitialized
3. onPageContentProcessed (each page not cached yet)
4. onPageContent (called first time Page::content() is called even when cached)
onPageNotFound
onPageAction (1.6)
1. onPageAction.{action} (1.6)
onPageTask (1.6)
1. onPageTask.{task} (1.6)
onTwigPageVariables (each page not cached yet)
onHttpPostFilter (1.5.2)
onTwigSiteVariables
onCollectionProcessed (when collection is requested)
onOutputGenerated
onOutputRendered
onShutdown

その他のイベント:

onBlueprintCreated
onTwigTemplateVariables
onTwigStringVariables
onBeforeDownload
onPageFallBackUrl
onMediaLocate
onGetPageBlueprints
onGetPageTemplates
onFlexObjectRender (1.6)
onFlexCollectionRender (1.6)
onBeforeCacheClear
onImageMediumSaved (ImageFile)
onAfterCacheClear (1.7)
onHttpPostFilter (1.7)
PermissionsRegisterEventclass (1.7)

Core Gravイベントフック

ページの処理中にトリガーされる、Gravの中核となるイベントフックがいくつかあります。

onFatalException

これは、PHP が致命的な例外をスローした場合に、いつでも発生させることができるイベントです。これは現在、Gravが致命的な例外をスローする潜在的な理由のリストを表示する処理をするために、problems プラグインによって使用されています。

onPluginsInitialized

これは、利用可能な最初のプラグインイベントです。この時点で、以下のオブジェクトが開始されています。

Uri
Config
Debugger
Cache
Plugins

プラグインに enabled: false という設定オプションが設定されている場合、そのプラグインは全く読み込まれません。

onAssetsInitialized

このイベントは、アセットマネージャーが初期化され、アセットを追加・管理できる状態になったことを示します。

onPagesInitialized

Grav の user/pages フォルダにあるすべてのページがオブジェクトとして読み込まれ、Pagesオブジェクトで利用可能になったことを示すイベントです。

onPageNotFound

これは、期待したページが見つからない場合に発生させることができるイベントです。これは現在、error プラグインによって、独自の 404 エラーページを表示するために使用されています。

onPageInitialized

URL で要求された現在のページがPage オブジェクトに読み込まれました。

onOutputGenerated

出力は Twig テンプレートエンジンによって処理され、今はただのHTMLの文字列になっています。

onOutputRendered

出力は完全に処理され、ディスプレイに送信されています。

onShutdown

Grav の処理が終了し、クライアントとの接続が切断された後にアクションを実行できる、新しく非常に強力なイベントです。これは、ユーザーとのインタラクションを必要としないアクションの実行に特に有用で、潜在的にパフォーマンスに影響を与える可能性があります。ユーザー追跡やジョブ処理などの用途が考えられます。

onBeforeDownload

この新しいイベントは、ファイルを含むイベントオブジェクトを渡します。このイベントは、ログの記録や、ファイルのダウンロードの許可／不許可を行うために使用できます。

onGetPageTemplates

このイベントにより、プラグインはテーマのディレクトリ構造とコアから集めたテンプレートに加え、独自のテンプレートを提供することができます。これは、プラグインが独自のテンプレートを提供することを望む場合に特に有用です。

例

/**
 * Add page template types.
 */
public function onGetPageTemplates(Event $event)
{
    /** @var Types $types */
    $types = $event->types;
    $types->register('downloads');
}

これにより、プラグインが提供するテンプレートを登録し、ページテンプレートタイプのドロップダウンリストに表示させることができます（ページを編集するときなど）。上の例では、downloads ディレクトリに downloads.html.twig ファイルがあるので、downloads というテンプレートタイプが追加されています。

onGetPageBlueprints

このイベントは onGetPageTemplates と同様に、コアやテーマ固有のものに加えて、プラグインが独自のリソースを提供できるようにします。この場合、それは blueprints です。

例

$scanBlueprintsAndTemplates = function () use ($grav) {
    // Scan blueprints
    $event = new Event();
    $event->types = self::$types;
    $grav->fireEvent('onGetPageBlueprints', $event);

    self::$types->scanBlueprints('theme://blueprints/');

    // Scan templates
    $event = new Event();
    $event->types = self::$types;
    $grav->fireEvent('onGetPageTemplates', $event);

    self::$types->scanTemplates('theme://templates/');
};

この例では、onGetPageTemplates と onGetPageBlueprints フックの両方を使用して、これらのプラグイン提供リソース（テンプレートとブループリント）を、継承やその他の用途のために Grav で利用できるようにします。

Twig イベントフック

Twigは独自のイベントフックを持っています。

onTwigTemplatePaths

テンプレートパスのベースロケーションは、Twig オブジェクトに設定されています。もし、Twig がテンプレートパスを検索する他の場所を追加する必要がある場合、このイベントを使用します。

例

/**
 * Add template directory to twig lookup path.
 */
 public function onTwigTemplatePaths()
 {
     $this->grav['twig']->twig_paths[] = __DIR__ . '/templates';
 }

onTwigInitialized

この時点でTwigテンプレートエンジンは初期化されています。

onTwigExtensions

コアTwigエクステンションはロードされていますが、独自のTwigエクステンションを追加する必要がある場合は、このイベントフックで追加することができます。

onTwigPageVariables

Twig がページを直接処理する場合、つまりページの YAML ヘッダでprocess: twig: trueを設定する場合です。ここで、この処理の間に Twig が利用できるようにする必要がある変数を追加します。

onTwigSiteVariables

Twigがサイトテンプレート階層を完全に処理する場所です。ここで、この処理中にTwigが利用できるようにする必要がある変数を追加してください。

コレクションイベントフック

onCollectionProcessed

処理後のコレクションを操作する必要がある場合は、このタイミングに行うことができます。

ページイベントフック

onBuildPagesInitializedを使用します。

このイベントは、ページが再処理されようとするときに一度だけ発生します。これは通常、キャッシュの有効期限が切れたり、リフレッシュが必要な場合に発生します。これは、コンテンツを操作してその結果をキャッシュする必要があるプラグインで使用するのに便利なイベントです。

onBlueprintCreated

フォームの処理、取り扱いに使用します。

onPageContentRaw

ページが見つかった後、ヘッダは処理されるが、コンテンツは処理されない。これは Grav システム内のすべてのページに対して発生します。このイベントはキャッシュされたページでは実行されず、キャッシュがクリアされるか、キャッシュクリアイベントが発生したときのみ実行されるため、パフォーマンスは問題ではありません。

onPageProcessed

ページがパースされ、処理された後。これは Grav システム内のすべてのページに対して発生します。このイベントはキャッシュされたページでは実行されず、キャッシュがクリアされたときやキャッシュクリアイベントが発生したときにのみ実行されるので、パフォーマンスは問題ではありません。

onMarkdownInitialized

Markdownが初期化されたときに呼び出されます。デフォルトのParsedown処理実装をオーバーライドすることを可能にします。これを導入したPRの使用例を参照してください。

onPageContentProcessed

このイベントは、ページのcontent()メソッドがページのコンテンツを処理した後に発生します。これは、処理後のコンテンツに対してアクションを実行したいが、その結果がキャッシュされていることを確認したい場合に特に有用です。このイベントはキャッシュされたページでは実行されず、キャッシュがクリアされるか、キャッシュクリアイベントが発生したときのみ実行されるので、パフォーマンスは問題ではありません。

onFolderProcessed

フォルダがパースされ、処理された後。これは Grav システム内のすべてのフォルダーに対して発生します。このイベントはキャッシュされたページでは実行されず、キャッシュがクリアされたときやキャッシュクリアイベントが発生したときのみ実行されるので、パフォーマンスは問題ではありません。

onPageFallBackUrl

ルートがページとして認識されない場合、Grav はページのメディアアセットにアクセスしようとします。このイベントは手続きが始まると同時に発生するので、プラグインがフックして追加機能を提供することができます。

onMediaLocate

抜粋版のカスタムメディアロケーションをサポートするようになりました。

onTwigLoader

Twig クラスの2つの新しいメソッドと組み合わせて、名前空間を使用するためのサポートを追加しました。Twig::addPath($path, $namespace)とTwig::prependPath($path, $namespace) の2つのメソッドを追加しました。

元ページ : https://learn.getgrav.org/17/plugins/event-hooks