| ログ解析スクリプトAWStats 7.8ドキュメント |

# プラグインの開発

AWStatsは、使いやすく、強力な拡張を可能にするとてもフレキシブルなプラグインアーキテクチャを採用しています。ここでは、独自の開発を始めるために必要な情報があります。このドキュメントでは、プラグインやモジュールという用語は、同じ意味で使用されます。

- プラグインファイルの場所
- フック
- 必要な変数
- アクセスできる変数
- アクセスできる関数
- 利用できるフツク
- グラフのプラグイン

## プラグインファイルの場所

AWStatsのプラグインは.pmのファイル拡張子を持つPerlのモジュールとして実装されています。更新モードまたはHTML出力モードのいずれかで、AWStatsを実行するたびに、構成ファイルからロードするプラグインの名前を検索します。その後、AWStatsはpluginsフォルダをスキャンし一致するモジュールを探して、メモリにロードし、実行時に適切なタイミングでフックを実行します。したがって、プラグインを作成するときは、awstats.plが置かれているフォルダの下のpluginsディレクトリにファイルを格納する必要があります。

## フック

有用であるためには、プラグインはAWStatsが実行中のさまざまな時点で呼び出される"フック"を実装する必要があります。フックは、単に、様々なパラメタを受け取り、計算したり、修正または出力したり、必要に応じて値を返すといった必要な操作を実行するPerlのサブルーティンです。
注：すべてのプラグインは、モジュールを初期化し、プラグインは現在のバージョンのAWStats下で実行かを判定するInit_のフックを実装しなければならない。
利用可能なフックの詳細については、プラグインのフックを参照のこと。

## 必要な変数

各プラグインは、名前、フック、実装し、必要なAWStatsのバージョンという3つの必要なローカル変数を実装する必要があります。通常は、サンプルコードのようにプラグインファイルの先頭にこれらを実装します。

`#-----------------------------------------------------------------------------
# PLUGIN VARIABLES
#-----------------------------------------------------------------------------
# <-----
# ここにプラグインに必要な最小AWStatsのバージョンとプラグインが管理
# するすべての機能の名前を入力します。
my $PluginNeedAWStatsVersion="5.5";
my $PluginHooksFunctions="GetCountryCodeByAddr GetCountryCodeByName ShowInfoHost";
my $PluginName = "geoipfree";
my $PluginImplements = "mou";
# ----->`

$PluginNeedAWStatsVersionはプラグインを正常に実行するために必要なAWStatsのの最小バージョンを示します。ユーザーがプログラムの古いバージョンを使用してプラグインを実装しようとすると、プラグインがロードされません。

$PluginHooksFunctionsは、プラグインが実装するフックのスペースで区切られたリストです。このリストには、プラグインのフックで定義された名前をだけを含む必要があります。プライベートモジュールの機能やこのリストのInit_のフックは記載しません。すべてのフックの命名規則は、HookName_PluginNameです。フックは、下線のないフックの名前が含まれています。

$PluginNameは、フックとファイル名に表示されているとおり、単にプラグインの名前です。これは、ロード時にAWStatsが使用します。

$PluginImplementsは、プラグインが実行する操作に対応する文字コードのリストです。これらの文字コードの少なくとも一つがなければ、プラグインが実行されません。コードは次のとおりです。

- "m" - レポート内を移動するためのリンクを提供するメニューハンドラプラグイン。プラグインは、CGIモードの左側のフレームまたは静的モードで上部のナビゲーションのように、メニューが表示されるたびに呼び出されます。
- "o" - AWStatsは、動的CGIや静的HTMLを経由してレポートを生成するときにロードする出力プラグイン
- "u" - データを処理するとAWStatsがログファイルを解析し、履歴データファイルを更新しているときに実行される更新プログラムのプラグイン。

## アクセスできる変数

プラグインはawstats.plプログラムの先頭で宣言されたグローバル変数のすべてにアクセスできます。これらの変数に書き込むこともできますが、別のプラグインが予期しない変更を加える可能性があるのでそれらを読むだけにすることをお勧めします。しかし自身のプラグインの範囲内でグローバル変数を宣言し、他のプラグインと共有することができます。ただ独自のモジュール内の通常のvars qw/ブロック内部で宣言すること。

したがって、構成ファイルの設定のデバッグレベルを利用できます（するべきです）。

## アクセスできる関数

プラグインはメインawstats.plファイルで宣言された関数のすべてにアクセスすることができます。デバッグとエラー処理では、debugとerror関数を使用する必要があります。プラグインが利用できそうな一般的な関数は次のとおりです（車輪を再発明する必要がないことを思い出してください）。

debug("デバッグメッセージ", デバッグレベル) - ユーザが実行時に設定したデバッグレベル（整数）以下のデバッグレベルの場合に標準出力に"デバッグメッセージ"を書き込みます。高いデバッグレベルほど、重要度の低いまたは情報的なメッセージとなります。メッセージを出力した後も、プログラムは実行を継続します。

error("エラーメッセージ") - 標準出力に"エラーメッセージ"を書き込みプログラムの実行を停止します。

Format_Bytes(バイト) - バイトで指定された十進数値をキロバイト、メガバイト、ギガバイトなどに変換します。1024.5を指定すると"1 KB"が返されます。

Format_Date(YYYYMMDDHHMMSS) - - 入力されたタイムスタンプを2010年4月30日16:55のように変換します。

Format_Number(数字) - 読みやすいようにコンマまたはユーザー定義文字を[3桁ごとの]区切りとして追加します。[123456789を入力すると123,456,789を返します。]

Article written by Laurent Destailleur.
Follow @awstats_project