Creating a Module

1. Implement Required Interfaces

In your plugin class, implement IModule and any scope interface you need:

Scope Interface Lifecycle Method
System ISystemSpaceModule onLoadSystemSpaceModule()
Workspace IWorkSpaceModule onLoadWorkSpaceModule()
User IUserSpaceModule onLoadUserSpaceModule()

These lifecycle methods replace onInit() for module-specific initialization. Keep onInit() only for logic that must run unconditionally (e.g. facade setup).

Which Switch Decides

ModulesManager knows the signed-in user in every scope, and workSpace alone tells where the request is. isActive() asks the switches in this order:

  1. A workspace module inside a workspace: the switch of the workspace.
  2. A user module with a signed-in user: the user's own switch, also with a workspace left in the session.
  3. A system module: the platform switch.

onLoadUserSpaceModule() runs in my-space only, that is, when no workspace is set.

  • A user module that is switched on from /modules/user/manage/ while a workspace is in the session gets its onLoadUserSpaceModule() call on the next request in my-space, not at once.
  • WorkspaceModuleTrait::loadModulesByWorkspace() sets a workspace while the user stays set. After it, a module that is both a workspace and a user module follows the switch of that workspace, not the user's switch, and onLoadUserSpaceModule() is not called again.
  • libs\common\ModulesHelper::isModuleActive() asks getActiveModule(), so it follows the same order.

A request to a method of a module that is off is refused with DisabledModuleException, a PermissionsException with the code 403. Its display message names the module by its caption and follows the switch that decided:

Switch Message
User %s is switched off. It can be switched on in My Workspace > User Modules.
Workspace %s is switched off in this workspace. It can be switched on by the workspace administrator in Settings > Workspace Modules.
System %s is not available. It can be switched on by the platform administrator.

Before the refusal the manager dispatches BeforeRefuseDisabledModuleEvent (domain/event/BeforeRefuseDisabledModuleEvent.php). It carries the module, the ModuleScope that decided (null for a module of no scope), the caption, the message and the HTTP code. A listener may name the module by another caption with setCaption() (the message of the scope is kept), replace the message with setMessage(), or change the code with setCode(); the manager builds the exception from the event afterwards.

$core->addEventListener(
    BeforeRefuseDisabledModuleEvent::EVENT_TYPE,
    function (BeforeRefuseDisabledModuleEvent $event): void {
        if ($event->getModule()->getName() === 'MyModule') {
            $event->setMessage(__('My Module is switched off. It can be switched on by support.'));
        }
    }
);

2. SQL Migration

Register the module in the modules table. The plugin column holds the class name without the Plugin suffix.

MySQL

INSERT INTO `modules` (`caption`, `ident`, `plugin`, `required`, `description`, `hooks`, `is_active`, `is_workspace`)
VALUES ('Test Module', 'test_module', 'TestModule', NULL, 'Test description.', NULL, 1, 1);

Postgres

INSERT INTO modules (caption, ident, plugin, required, description, hooks, is_active, is_workspace)
VALUES ('Test Module', 'test_module', 'TestModule', NULL, 'Test description.', NULL, true, true);

Set is_workspace = true/1 for workspace-scoped modules.

3. Add a Menu Item (optional)

Implement IModuleMenuFetcher and add the item inside onFetchModuleMenuHandler. Gate it behind a permission check.

use DisplayPlugin;
use plugin\Modules\IModule;
use plugin\Modules\domain\listener\IModuleMenuFetcher;
use plugin\Modules\domain\model\MenuItemValuesObject;

class TestModulePlugin extends DisplayPlugin implements IModule, IModuleMenuFetcher
{
    /**
     * @event IModuleMenuListener
     * @param array $menuItems
     * @param string|null $area
     */
    public function onFetchModuleMenuHandler(array &$menuItems, ?string $area): void
    {
        if (!$this->hasUserPermissionToSection('some_section')) {
            return;
        }

        $menuIdents = array_column($menuItems, MenuItemValuesObject::FIELD_IDENT);
        $idParentMenuItem = array_search('parent', $menuIdents);

        if (!$idParentMenuItem || empty($menuItems[$idParentMenuItem])) {
            return;
        }

        if (empty($menuItems[$idParentMenuItem][MenuItemValuesObject::FIELD_ITEMS])) {
            $menuItems[$idParentMenuItem][MenuItemValuesObject::FIELD_ITEMS] = [];
        }

        $menuItems[$idParentMenuItem][MenuItemValuesObject::FIELD_ITEMS][] = [
            MenuItemValuesObject::FIELD_CAPTION => __('Menu item 1'),
            MenuItemValuesObject::FIELD_URL     => $this->getUrl('/test/module/menu/'),
            MenuItemValuesObject::FIELD_IDENT   => 'menu-item-1',
        ];
    }
}