はじめに
ふと見回してみたが、日本語でのhumhub運用記事はやや見かけるもののの、モジュール開発の情報は少ないようだと気づいた。また、業務でhumhubを運用している仲間内で、技術の情報を記録・情報発信してはどうかと意見がでた。そこで、自分の作業の備忘録、技術継承の意味もかねて記録を作り、情報を発信しておこうと思った。
この文書は、必要最低限の情報を記載したもの。詳しくは、公式ページの”最新”の情報ドキュメントを頼ってほしい。公式のサイトは、予告も更新履歴も示さずにいきなり書き換わるので要注意だ。なお、この文章のところどころに公式に対する棘が感じられるかもしれないが、棘を生やしたくもなるような公式ドキュメントであるためだということに読者の共感が得られるのではないかと、昭和のおじさんは思うのだ。平成生まれの略語感覚の若者の発想についていけない僻みであろう。許してほしい。
以下、心を広く持って読んでほしい。なぜなら、公式の情報でわからない部分について経験から作成した駄文注釈満載だからだ。間違った解釈かもしれないし、余計な情報を含んでいるかもしれない。フェィクニュースでないと言い切れないが、最低限、システムイベントのコールバックは使えるようになるよう真面目に書いている。日本語でしか書いていないので申し訳ないが、世界に最低1人はこの情報が役立つと思ってくれるひとが絶対にいると信じて書いている。繰り返すが、許してほしいという気持ちをあわせもちながら作成し、情報発信を決意したことを何卒理解していただきたい。
カスタムモジュールの仕組み
カスタムモジュールの配置場所
デフォルト： (humhub root) /protected/modules
デフォルトのまま使用していても支障はない（はず）。このフォルダの変更設定も（humhubシステムとしては）可能だけど、その方法はこのドキュメントには関係ない。moduleAutoloadPathsの設定値による、と参考程度に覚えておけば十分だ。https://docs.humhub.org/docs/develop/environment#module-loader-path
必要最低限の動作ファイル
カスタムモジュールには、次の３つのファイルが必要。
・config.php
・module.json
・Module.php
humhubシステムがカスタムモジュール配置場所にあるフォルダをクローリングしてこれらのファイルを探す。もし、ファイルが足りなかったり、ファイルに描き誤りがあると、「モジュールが読み込めない」エラーがでるだけでなくシステムが起動をそこで停止してしまう仕様。記述操作は要注意だ。
それぞれのファイルの内容について、簡単に述べる。
・config.php モジュールの基本情報を書き込んでおくファイル。
次の情報の連想配列を返す(return)する作りにしなければならない。ほかにもオプションがあるが、ここでは必須項目（requirement）だけ書いておく。項目名はシステム内で文字列比較されるらしいのでアルファベット小文字で記載しておく方が無難。また、ここには静的な宣言のみを記載することがルールになっていて、動的なコードはこのphpファイルの中には書いてはいけない（書いてもうまく動作しない）。
| 項目名 | 値 |
|---|---|
| id | モジュールのID。アルファベット小文字で記述。スペースや数字は使えない。また、他のモジュールと被らないUniqueなものでなければならない。システム内で扱われる情報。 |
| class | モジュールクラスのネームスペースでの位置を記述。 |
| namespace | モジュールのネームスペースを記述。ネームスペースはユーザー固有の識別名も加えることはできるが、発行者（発行社）銘を先頭につけたフォルダパスぐらいにしておく方が管理上わかりやすいかも。 |
この３つが公式ドキュメントの「必須項目」である。しかし、実際にモジュールを動作させる場合、このような「モジュールの自己紹介みたいな情報」だけで動作するわけがない。次の項目を記載することで、humhubシステムのイベントをトリガーにしたコールバックを記述して動作させることができるようになる。
| 項目名 | 値 |
|---|---|
| events | モジュールのイベントコンフィグ情報の配列。 |
公式情報のとおりにeventsを紹介してみたが、どうだろう？これだけでプログラムの書ける天才が世界に大いにいるのだろう、昭和のおじさんは驚愕を隠しきれなかった。イベントコンフィグ情報の配列（原文：Array containing the modules event configuration）だけで、配列の中身について触れないのかって誰も思わないのだろうか？気になった方、公式の別ページ（Event Handler）のページに解説があるので安心を。
https://docs.humhub.org/docs/develop/modules-event-handler
さて、このeventsの配列の中身については、次のようになっている（ようだ）。
events項目の値として記述する配列の中の配列
| 配列内項目名 | 値 |
|---|---|
| class | イベントトリガーを発するクラスのクラス名をネームスペース付きで記述。 |
| event | イベント名。イベント名はイベントを発するクラスが管理している。 |
| callback | コールバックで動作させたい関数（function）の記述ファイルと、関数名をリスト記入する。 |
以上を踏まえて作成するconfig.phpは次のような例になる。
// @example/config.php
use humhub\widgets\TopMenu;
return [
'id' => 'example',
'class' => 'johndoe\example\Module',
'namespace' => 'johndoe\example',
'events' => [
[
'class' => TopMenu::class, 'event' => TopMenu::EVENT_INIT,
'callback' => ['johndoe\example\Events', 'onTopMenuInit']
]
]
];
(この例は、公式の説明文から引用した。）
events配列の、第一要素のcallback項目に、関数のファイルと実行したい関数名を記載しているところに注目しておいてほしい。events配列に要素を加えて複数のトリガーにそれぞれ反応するモジュールを作成することも可能である。
・module.json モジュールのメタデータを記述しておくファイル。
このファイルは、humhubシステムのモジュールマネージャやマーケットプレースで使われる。外部向けのモジュール紹介情報を書き込むファイルだと思えばよい。これも必須項目のみ解説しておく。
| 項目名 | 値｜ |
|---|---|
| id | モジュールID。config.phpに記載したものと同じものであることが肝要。アルファベット小文字。 |
| name | モジュール名。外部に表示される名称。 |
| description | モジュールの説明。英語表記が望ましい。 |
| version | バージョン情報。通例として大抵は、"##.##.##"とバージョンを数字で書いているようだが、記述形式は文字列情報であればよいのでアルファベットでも記号でもよい。 |
以上がシステムの要求する必須項目。公式も注釈をいれているが、筆者個人的にも開発モジュールが対応するHumhubのバージョンを記載しておくことをオススメしたい。とりあえず自身の開発環境のHumhubシステムのバージョンをminVersionに記載しておくことは、他の利用者に利用可能システムバージョンがわかって安心を与えるはずだからだ。
以上を踏まえて作成するmodule.jsonは次のような例になる。
{
"id": "example",
"version": "1.0",
"name": "My Example Module",
"description": "My testing module.",
"humhub": {
"minVersion": "1.2",
"maxVersion": "2.0"
},
"keywords": ["my", "cool", "module"],
"screenshots": ["assets/screen_1.jpg"],
"homepage": "https://www.example.com",
"authors": [
{
"name": "Tom Coder",
"email": "tc@example.com",
"role": "Developer"
},
{
"name": "Sarah Mustermann",
"email": "sm@example.com",
"homepage": "http://example.com",
"role": "Translator"
}
]
}
（この例は、公式の説明文から引用した。）
・Module.php モジュールの基本動作を、ベースモジュールクラスを継承して記述するファイル。
eventsのコールバック関数だけでなく、インストール/アンインストール時の動作オプションや、多言語対応のDescriptionを記述することも。詳しくは、公式の次のページを参照。
https://docs.humhub.org/docs/develop/modules-base-class
継承対象となるクラスは、humhub\components\Moduleかhumhub\modules\content\components\ContentContainerModuleの２つ。この２つのベースモジュールの選別の基準は、前者がグローバルレベル（global level）に作用するモジュールを対象としたもの、後者がスペースまたはユーザーレベル（space and/or user level)を対象にしたものか、ということだが・・・。具体的にいうと、前者が投稿に対するいいね機能やユーザー情報のように、システムから広く利用されるタイプ、後者はカレンダーやWikiなど、スペースのモジュールとしてユーザーが都度選択利用するタイプとして発想して貰えばよいと思う。（humhub仕様経験者しかわからない解説で申し訳ない）
モジュールのライフサイクル
説明は公式に譲る。https://docs.humhub.org/docs/develop/modules#module-lifecycle
その他モジュールに含めることができるファイル
ドキュメント類
ドキュメント類は、docsフォルダを作って収めておく。Marketplaceに出品する場合は、必須になるファイルもあるので留意のこと。
| ファイル名 | 必須？ | 解説 |
|---|---|---|
| README.md | Yes | 機能など概要解説を記述。 |
| CHANGELOG.md | Yes | 時系列で変更点を記載。マーケットプレイスのいくつかのモジュールのChangelogを記述スタイルの参考にするとよい。 |
| MANUAL.md | No | 仕様手順書。 |
| INSTALLATION.md | No | インストール手順書。 |
| LICENCE.md | No | ライセンス説明書。 |
| DEVELOPER.md | No | 開発社の紹介・説明書。 |
（表は、公式の説明文から引用。一部加筆）
モジュールのファイル構成
公式では、ファイル配置にあたって次のようなcommon module diretoriesを示唆している。一部はシステムによる指定でもあるので、基本に則っておいたほうが無難だろう。
| フォルダ（ディレクトリ）名 | 解説 |
|---|---|
| activities | Activity classes に関連するもの |
| assets | Asset Bundles モジュールで使用するアセット（素材） |
| components | Components |
| controllers | Web or Console controller に関するもの |
| live | HumHub live related classes used for live frontend updates |
| jobs | Asynchronous jobs (queue)に関するもの |
| messages | Translation message files （ yii message/extract-module "モジュール名" のコマンドで生成することができる。詳細は、https://docs.humhub.org/docs/develop/i18n ） |
| migrations | Database migration files データベースに独自のテーブルを作成する場合、migrationファイルを設置する。migration fileの生成方法は、https://docs.humhub.org/docs/develop/models |
| helpers | Helper and utility classes |
| notifications | Module notifications |
| permissions | Module permissions |
| resources | Assets as scripts, style sheets, images JSやCSSをおくならこのresourcesフォルダの下に |
| tests | Module tests テストコード（Codeception）を書くときはこちら） |
| views | View files |
| widgets | Widget classes |
以上で、カスタムモジュールの作り方の公式ページの解説は終了。
ご覧のとおり型枠の作り方についての解説になっているので、実践的でない。実践としてカスタムモジュールを作るにあたってのポイントは、config.phpで記述するevents項目の書き方だ。特に、eventsの拾いかたの理解が重要だ。
eventsの拾いかたについては、次のページの解説を検討中。
https://docs.humhub.org/docs/develop/modules-event-handler
本稿はここまで。