Skip to main content

Getting Started

The following guide describes the basic module structure and extended module features as well as important considerations regarding your own custom modules. Since HumHub is based on the Yii Application Framework you should at least be familiar with the basic concepts of this framework before writing your own code as:

You should also follow the Coding Standards and keep an eye on the Migration Guide in order to keep your module compatible with new HumHub versions and facilitate new features.

Before you start

Before starting with the development of your custom module, first consider the following module options:

Furthermore, you may have to consider the following issues:


It's always a good idea to get some inspiration from existing modules which may already solved some of the problems you are facing in your custom module. For example have a look at repositories at:

Setup a module skeleton

The easiest way of setting up a basic HumHub module is by using the Developer Tools Module. Once you've generated a module skeleton, copy the module to a module loader path. Now the module should be visible under Administration -> Modules and can be enabled.

Alternatively, you can take a look at the following GitHub template project: Example Module.

Module Structure

Basically HumHub modules are identical to Yii2 modules.

A minimal HumHub module at least has to define the following files and metadata:

├── config.php
│ ├── id
│ ├── namespace
│ └── class
├── module.json
│ ├── id
│ ├── name
│ ├── description
│ └── version
└── Module.php


The config.php can be used to define event handlers, and the definition of URL Rules and consists of the following data:

idUnique module ID (required)
classNamespaced classname of the module class (required)
namespaceThe namespace of your module (required)
eventsArray containing the modules event configuration
urlManagerRulesArray of URL Manager Rules
modulesCan be used to define submodules
consoleControllerMapList of console controllers. See also: Yii2 API (HumHub 1.7+)


// @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']
'consoleControllerMap' => [
'example' => 'johndoe\example\console\ExampleController'

Do not execute any dynamic code directly within config.php since the result will be cached!


Do choose a preferably unique module id which does not interfere with any core or other available module.


The module.json file holds basic metadata of a module used by the marketplace.

Available attributes:

idThe module ID (required)
versionThe module version. This must follow the format of X.Y.Z. (required)
nameThe modules name (required)
descriptionA short module description (required)
humhubHumHub core minVersion and maxVersion requirements
keywordsModule related keywords as string array
screenshotsSome screenshots file names for the marketplace, those should reside in the Module::$resourcesPath
homepageA URL to the website of the module
authorsAuthor information as name, email, homepage, role
licenceLicence identifier See ( or use proprietary


"id": "example",
"version": "1.0",
"name": "My Example Module",
"description": "My testing module.",
"humhub": {
"minVersion": "1.2"
"keywords": ["my", "cool", "module"],
"screenshots": ["assets/screen_1.jpg"],
"homepage": "",
"authors": [
"name": "Tom Coder",
"email": "",
"role": "Developer"
"name": "Sarah Mustermann",
"email": "",
"homepage": "",
"role": "Translator"
"licence": "AGPL-3.0-or-later"

Align the minVersion of your module when using new features and test your modules on all supported versions. In case you are not sure about the minVersion use the version you are testing with or the latest stable HumHub version.


The module class of a module may contain basic install/uninstall functionality as well as module class level configuration. See chapter Module Class for an introduction of the base module class.


The documentation files of a module must be located in the module's docs folder.

The following table lists files which can be added in order to provide module documentation for the marketplace. Note, the required field only applies to the marketplace modules and is not required for private modules.

README.mdYesA description and overview of the features
CHANGELOG.mdYesA file which contains a curated, chronologically ordered list of changes for each version
MANUAL.mdNoInformation on how to use this module
INSTALLATION.mdNoAdditional installation information
LICENCE.mdNoLicencing information including the licence
DEVELOPER.mdNoAdditional information for developers

Extended module structure example

The following table describes other common module directories used for more specific use cases:

activitiesActivity classes
assetsAsset Bundles
controllersWeb or Console controller
liveHumHub live related classes used for live frontend updates
jobsAsynchronous jobs (queue)
messagesTranslation message files
migrationsDatabase migration files
helpersHelper and utility classes
notificationsModule notifications
permissionsModule permissions
resourcesAssets as scripts, style sheets, images
testsModule tests
viewsView files
widgetsWidget classes
Events.phpEvent handlers

Module Icon

Each module should also provide an icon image.

The icon must be provided in PNG format, squared and with a minimum size of 128x128 pixels.

By default, the image must be stored as module_image.png in your module's ressource directory (see Module::$resourcesPath), hence defaulting to assets/module_image.png. You can also override the getImage() method of your module, if you need to return a different URL.

Module Lifecycle

Install a Module

A module is considered as installed once it resides in one of the module autoloader paths. By default modules from the marketplace reside in @humhub/protected/modules. Custom modules should be installed by adding them manually to an autoload path such as @app/custom-modules or by loading them from the marketplace.


You can add additional module paths by means of the moduleAutoloadPaths parameter. Please see the Development Environment Section for more information.

Enabled a Module

In order to use a module, you'll have to enable it first. This can be achieved by:

  • Administration Backend Administration -> Modules
  • Console command php yii module/enable

Enabling a module will automatically run the modules database migrations and add an entry to the modules_enabled table.

The ModuleManager responsible for enabling modules will trigger the following events right before and after enabling a module:


ContentContainerModules also have to be enabled within a space or user profile within the container's module management section.

Module Bootstrap

Every request during the application bootstrap phase, the humhub\components\bootstrap\ModuleAutoLoader will search for all enabled modules within the module autoload paths and register configured module event listeners defined in the modules config.php.

Disable Module

Disabling a module will usually drop all related module data from the database and will detach the module from the bootstrap process.

Modules can be disabled by means of

  • Administration Backend Administration -> Modules
  • Console command php yii module/disable

The ModuleManager responsible for disabling modules will trigger the following events right before and after enabling a module:


See Module::disable() and ContentContainerModule::disable() for more information about how to implement custom disable logic.

Uninstall Module

Uninstalling a module means removing it from the autoload path.


You should never delete an enabled module folder manually without disabling it first.