Modules.php - backend module configuration
The configuration of backend modules is placed in the
dedicated Configuration/Backend/Modules.php configuration file.
See also the Backend module configuration examples.
Note
The Configuration/Backend/Modules.php configuration files are
read and processed when building the container. This
means the state is fixed and cannot be changed at runtime.
Table of contents
Module configuration options
| Name | Type |
|---|---|
| string | |
| string | |
| string | |
| string | |
| array | |
| array | |
| bool | |
| bool | |
| bool | |
| string | |
| string | |
| array of strings or string | |
| string | |
| string | |
| string | |
| bool | |
| array | |
| array | |
| array |
-
- Type
- string
If the module should be a submodule, the parent identifier, for example
contenthas to be set here. Have a look into the list of available toplevel modules.Extensions can add additional parent modules, see Toplevel modules.
-
- Type
- string
- Default
/module/<mainModule>/<sub Module>
Define the path to the default endpoint. The path can be anything, but will fallback to the known
/module/<mainpattern, if not set.Module>/<sub Module>
-
- Type
- string
Can be
user(editor permissions),admin, orsystem.Maintainer
-
- Type
- string
Can be
*(= always),liveoroffline. If not set, the value of the parent module - if any - is used.
-
- Type
- array
The module position. Allowed values are
topandbottomas well as the key value pairsbefore => <identifier>andafter => <identifier>.
-
- Type
- array
Allows to define additional appearance options.
-
- Type
- bool
- Default
- false
- Added
- 14.0
If true, the module will only be displayed in the module menu if at least one of its submodules is available to the current user.
If all submodules are either disabled, removed, or the user lacks access permissions to them, the parent module will automatically be hidden from the module menu.
The Content > Status module leverages this feature to seamlessly disappear from the module menu when extensions are uninstalled or users lack permissions to access its submodules, preventing dead-end navigation paths and enhancing the overall backend experience.
-
- Type
- bool
- Default
- false
- Added
- 14.0, Feature: #107712 - Introduce card-based submodule overview
If true and if a module has submodules, the submodules that the backend user has access to are displayed as a set of cards. Each card has an icon, a title, a description, and a button to open the submodule. See Showing third-level backend modules as cards for an example.
-
- Type
- string
The module icon identifier
-
- Type
- string
Path to a module icon (Deprecated: Use iconIdentifier instead)
-
- Type
- array of strings or string
The title of the module, the description shown in the About module (find it by clicking on your user profile then under Help), and the short description shown as a tooltip in the module menu.
Pass the translation domain of the XLIFF file that contains the labels, for example
my_. The file has to contain the keysextension. modules. conference title,descriptionandshort_.description New in version 14.0 Feature: #93334 - Translation Domain Mapping
Labels can be referenced by their translation domain.
Alternatively, pass an
arraywith the keystitle,descriptionandshort. The value of each key is either static text or a label reference.Description The path of a locallang file can be passed as well. The file has to contain the keys
mlang_(title),tabs_ tab mlang_(description) andlabels_ tabdescr mlang_(short description).labels_ tablabel
-
- Type
- string
- Default
- TYPO3/CMS/Backend/Module/Iframe
The view component, responsible for rendering the module.
-
- Type
- array
All properties of the module data object that may be overridden by
GET/POSTparameters of the request get their default value defined here.Example
Excerpt of EXT:my_extension/Configuration/Backend/Modules.php
-
- Type
- array
List of identifiers that are aliases to this module. Those are added as route aliases, which allows to use them for building links, for example with the
\TYPO3\. Additionally, the aliases can also be used for references in other modules, for example to specify a module's parent.CMS\ Backend\ Routing\ Uri Builder Examples
Example for a new module identifier:
Excerpt of EXT:my_extension/Configuration/Backend/Modules.php<?php declare(strict_types=1); return [ 'workspaces_admin' => [ 'parent' => 'content', // ... // choose the previous name or an alternative name 'aliases' => ['web_WorkspacesWorkspaces'], ], ];Example for a route alias identifier:
Excerpt of EXT:my_extension/Configuration/Backend/Modules.php
-
- Type
- array
Generic side information that will be merged with each generated
\TYPO3\array. This can be used for information, that is not relevant for a module aspect, but more relevant for the routing aspect, for example sudo mode.CMS\ Backend\ Routing\ Route::$options
Default module configuration options (without Extbase)
| Name | Type |
|---|---|
| array |
-
- Type
- array
Define the routes to this module. Each route requires at least the
target. The_defaultroute is mandatory, except for modules which can fall back to a submodule. Thepathof the_defaultroute is taken from the top-level configuration. For all other routes, the route identifier is taken aspath, if not explicitly defined. Each route can define any controller/action pair and can restrict the allowed HTTP methods:Excerpt of EXT:my_extension/Configuration/Backend/Modules.php<?php declare(strict_types=1); use MyVendor\MyExtension\Classes\Controller\AnotherController; use MyVendor\MyExtension\Classes\Controller\MyModuleController; return [ 'my_module' => [ // ... 'routes' => [ '_default' => [ 'target' => MyModuleController::class . '::overview', ], 'edit' => [ 'path' => '/edit-me', 'target' => MyModuleController::class . '::edit', ], 'manage' => [ 'target' => AnotherController::class . '::manage', 'methods' => ['POST'], ], ], ], ];All subroutes are automatically registered in a
\TYPO3\. The full syntax for route identifiers isCMS\ Core\ Routing\ Route Collection <module_, for example,identifier>.<sub_ route> my_. Therefore, using themodule. edit \TYPO3\to create a link to such a sub-route might look like this:CMS\ Backend\ Routing\ Uri Builder \TYPO3\CMS\Backend\Routing\UriBuilder->buildUriFromRoute('my_module.edit');Copied!
Extbase module configuration options
Note
Using these Extbase configurations tells the Core to bootstrap Extbase and expecting
controllers based on
\TYPO3\.
Do not use it for non-Extbase controller. Use routes
instead.
| Name | Type |
|---|---|
| string | |
| array |
-
- Type
- string
The extension name in UpperCamelCase for which the module is registered. If the extension key is
my_the extension name would beexample_ extension My.Example Extension
-
- Type
- array
Define the controller action pair. The array keys are the controller class names and the values are the actions, which can either be defined as array or comma-separated list:
Excerpt of EXT:my_extension/Configuration/Backend/Modules.php<?php declare(strict_types=1); use MyVendor\MyExtension\Controller\MyModuleController; return [ 'web_ExtkeyExample' => [ //... 'path' => '/module/web/ExtkeyExample', 'controllerActions' => [ MyModuleController::class => [ 'list', 'detail', ], ], ], ];The modules define explicit routes for each controller/action combination, as long as the
enablefeature toggle is turned off (which is the default). This effectively means human-readable URLs, since the controller/action combinations are no longer defined via query parameters, but are now part of the path.Namespaced Arguments For Backend This leads to the following URLs:
https://example. com/ typo3/ module/ web/ Extkey Example https://example. com/ typo3/ module/ web/ Extkey Example/ My Module/ list https://example. com/ typo3/ module/ web/ Extkey Example/ My Module/ detail
The route identifier of corresponding routes is registered with similar syntax as standard backend modules:
<module_. Above configuration will therefore register the following routes:identifier>.<controller>_<action> web_Extkey Example web_Extkey Example. My Module_ list web_Extkey Example. My Module_ detail
Debug the module configuration
All registered modules are stored as objects in a registry. They can be viewed in the backend in the System > Configuration > Backend Modules module.
Exploring registered backend modules in the Configuration module
The ModuleProvider API allows extension authors to work with the registered modules.
Backend modules with sudo mode
You can configure the sudo mode in your backend module like this:
<?php
use TYPO3\CMS\Backend\Security\SudoMode\Access\AccessLifetime;
return [
'tools_ExtensionmanagerExtensionmanager' => [
// ...
'routeOptions' => [
'sudoMode' => [
'group' => 'systemMaintainer',
'lifetime' => AccessLifetime::M,
],
],
],
];