How to make a custom module for Humhub (some interpretation on the official page) (1)

Aug 29, 2020 PHP yii2 HumHub

#Introduction I took a quick look around, and although I found a humhub operation article in Japanese, I found that there was little information on module development. In addition, there was an opinion as to whether to record and disseminate technical information within the colleagues operating humhub. Therefore, I decided to make a memorandum of my work and the meaning of succession of technology to make a record and to disseminate the information.

This document contains the minimum required information. For more information, please rely on the “latest” information document on the official page. Please be aware that the official website will be rewritten suddenly without showing any notice or update history. In addition, although there may be some thorns against the formula in this text, the reader’s sympathy may be obtained because it is an official document that makes you want to grow thorns. It’s It may be a remoteness that cannot keep up with the ideas of adolescents born in Heisei. I want you to forgive me.

Below, please read with a broad mind. This is because there are a lot of junk commentary created from experience about parts that are not known from the official information. It may be a misinterpretation, or it may contain extra information. It’s hard to say it’s not fake news, but at the very least, I’m seriously writing that system event callbacks can be used. I’m sorry because it’s written only in Japanese, but at least one person in the world believes that this information will be useful, and I write it. Again, I would like you to understand that I made it with the feeling that I want you to forgive it and decided to send information.

#How custom modules work

Custom module location

 Default: (humhub root) /protected/modules

There is no problem even if you use the default settings (should). You can change this folder (as a humhub system), but that’s not relevant to this document. It is enough to remember for reference only that it depends on the setting value of moduleAutoloadPaths.

Required minimum operation file

The custom module requires the following three files:

・Config.php ・Module.json ・Module.php

The humhub system searches for these files by crawling the folder in the custom module location. If there are not enough files or there is a mistake in drawing the file, not only a “module cannot be read” error will occur, but the system will stop booting there. The description operation requires caution.

Briefly describe the contents of each file.

・Config.php A file in which the basic information of the module is written.

It must be made to return the associative array of the following information. There are other options, but only the required items (requirement) are written here. It seems safe to write the item names in lowercase letters because it seems that the character strings are compared in the system. Also, it is a rule to put only static declaration here, and dynamic code should not be written in this php file (it does not work well if written).

Item name value
id ID of the module. Described in lower case letters. Spaces and numbers cannot be used. Also, it must be unique so that it does not overlap with other modules. Information handled within the system.
class Describes the location of the module class in the namespace.
namespace Describes the namespace of the module. You can add a user-specific identification name to the namespace, but it may be easier to manage if you set it to a folder path starting with the issuer (publisher) name.

These three are the “mandatory items” in the official document. However, when actually operating a module, it is not possible to operate only with such “information about self-introduction of the module”. By describing the following items, it will be possible to describe and operate a callback triggered by an event of the humhub system.

Item name value
events Array of event configuration information for the module.

I have introduced events according to the official information, but what about? I think there are many geniuses in the world who can write programs with just this, and the Uncle of Showa couldn’t hide his astonishment. Does anyone wonder if the contents of the array will be touched only by the array of event configuration information (the original text: Array containing the modules event configuration)? If you are curious, please rest assured that there is a description on the official page of another page (Event Handler).

By the way, the contents of this array of events are as follows.

An array in the array to describe as the value of the events item

Item name in array Value
class Describe the class name of the class that issues the event trigger with a namespace.
event Event name. The event name is managed by the class that issues the event.
callback Enter the description file of the function you want to operate with the callback and the function name in the list.

The config.php created based on the above is the following example.

// @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']

(This example is taken from the official description.) Please note that the function file and the name of the function you want to execute are described in the callback item of the first element of the events array. It is also possible to add an element to the events array to create a module that responds to multiple triggers.

This file is used by humhub system’s module manager and marketplace. You can think of it as a file to write external module introduction information. Again, only the essential items are explained.

Item name value
id Module ID. It is important that it is the same as the one described in config.php. Lowercase alphabet.
name Module name. The name displayed externally.
description A description of the module. English notation is preferred.
version Version information. Usually, it seems that “##.##.##” and the version are written in numbers, but since the description format is only character string information, it may be alphabet or symbol.

The above are the required items required by the system. The official comment has been added, but I personally recommend that you also list the version of Humhub that the development module supports. For the time being, listing the version of the Humhub system of your own development environment in minVersion should give other users peace of mind knowing the available system version.

Module.json created based on the above is the following example.

    "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": "",
    "authors": [
            "name": "Tom Coder",
            "email": "[email protected]",
            "role": "Developer"
            "name": "Sarah Mustermann",
            "email": "[email protected]",
            "homepage": "",
            "role": "Translator"

(This example is taken from the official description.)

-Module.php A file that describes the basic operation of the module by inheriting the base module class.

Not only the callback function of events, but also the operation option at the time of installation/uninstallation, and the description for multilingual can be described. For details, see the official next page.

There are two classes to inherit: humhub\components\Module or humhub\modules\content\components\ContentContainerModule. The criteria for selecting these two base modules are whether the former is for modules that act on the global level, the latter is for the space or user level (space and/or user level), But… Specifically, the former is a type that is widely used by the system, such as a post-like function or user information, and the latter is a type that the user selects and uses as a space module such as a calendar or Wiki. I think you should get it. (I’m sorry for the explanation that only humhub specification experts can understand)

Module life cycleThe explanation is officially handed over.

Other files that can be included in the module


Docs folder is created and stored for documents. Please note that some files are required when listing on the Marketplace.

File name Required? Commentary Yes Describes the outline of functions. Yes Enter changes in chronological order. Use the Changelog of some modules in the Marketplace as a reference for writing style. No Specification procedure manual. No Installation instructions. No License description. No Introduction/manual of the developer.
(The table is quoted from the official description. Some additions)

Module file structure

Officially, the following common module diretories are suggested for file allocation. Some of them are designated by the system, so it may be safer to follow the basics.

Folder (directory) name Description
activities Things related to Activity classes
assets Asset Bundles Assets used in the module
components Components
controllers Web or Console controller related things
live HumHub live related classes used for live frontend updates
jobs Asynchronous jobs (queue) related things
messages Translation message files (yii message/extract-module “module name” command can be generated. For details, see ).
migrations Database migration files If you want to create your own table in the database, set the migration file. How to generate migration file is
helpers Helper and utility classes
notifications Module notifications
permissions Module permissions
resources Assets as scripts, style sheets, images If you put JS and CSS under this resources folder
tests Module tests Click here to write test code (Codeception)
views View files
widgets Widget classes

This is the end of the explanation on the official page on how to create a custom module.

As you can see, it is not practical because it explains how to make formwork. The point when making a custom module as a practice is how to write the events item described in config.php. Especially, understanding how to pick up events is important.

Regarding how to pick up events, we are considering the explanation on the next page.

This is the end of this article.