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:
- A workspace module inside a workspace: the switch of the workspace.
- A user module with a signed-in user: the user's own switch, also with a workspace left in the session.
- 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 itsonLoadUserSpaceModule()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, andonLoadUserSpaceModule()is not called again.libs\common\ModulesHelper::isModuleActive()asksgetActiveModule(), 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',
];
}
}