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.

Module configuration options 

parent
Type
string

If the module should be a submodule, the parent identifier, for example content has to be set here. Have a look into the list of available toplevel modules.

Extensions can add additional parent modules, see Toplevel modules.

path
Type
string
Default
/module/<mainModule>/<subModule>

Define the path to the default endpoint. The path can be anything, but will fallback to the known /module/<mainModule>/<subModule> pattern, if not set.

access
Type
string

Can be user (editor permissions), admin, or systemMaintainer.

workspaces
Type
string

Can be * (= always), live or offline. If not set, the value of the parent module - if any - is used.

position
Type
array

The module position. Allowed values are top and bottom as well as the key value pairs before => <identifier> and after => <identifier>.

appearance
Type
array

Allows to define additional appearance options.

appearance.dependsOnSubmodules
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.

appearance.renderInModuleMenu
Type
bool

If set to false the module is not displayed in the module menu.

showSubmoduleOverview
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.

iconIdentifier
Type
string

The module icon identifier

icon
Type
string

Path to a module icon (Deprecated: Use iconIdentifier instead)

labels
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_extension.modules.conference. The file has to contain the keys title, description and short_description.

New in version 14.0 Feature: #93334 - Translation Domain Mapping

Labels can be referenced by their translation domain.

Alternatively, pass an array with the keys title, description and shortDescription. The value of each key is either static text or a label reference.

The path of a locallang file can be passed as well. The file has to contain the keys mlang_tabs_tab (title), mlang_labels_tabdescr (description) and mlang_labels_tablabel (short description).

component
Type
string
Default
TYPO3/CMS/Backend/Module/Iframe

The view component, responsible for rendering the module.

navigationComponent
Type
string

Changed in version 14.0

The @typo3/backend/page-tree/page-tree-element , which was deprecated in TYPO3 v13.1, has been removed in favor of @typo3/backend/tree/page-tree-element .

The module navigation component. The following are provided by the Core:

@typo3/backend/tree/page-tree-element
The page tree as used in the Content module.
@typo3/backend/tree/file-storage-tree-container
The file tree as used in the Media module.
Migration
EXT:my_extension/Configuration/Backend/Modules.php (excerpt)
'mymodule' => [
    'parent' => 'content',
    ...
-   'navigationComponent' => '@typo3/backend/page-tree/page-tree-element',
+   'navigationComponent' => '@typo3/backend/tree/page-tree-element',
],
Copied!
navigationComponentId
Type
string

The module navigation component (Deprecated: Use navigationComponent)

inheritNavigationComponentFromMainModule
Type
bool
Default
true

Whether the module should use the parents navigation component. This option defaults to true and can therefore be used to stop the inheritance for submodules.

moduleData
Type
array

All properties of the module data object that may be overridden by GET / POST parameters of the request get their default value defined here.

Example

Excerpt of EXT:my_extension/Configuration/Backend/Modules.php
<?php

declare(strict_types=1);

return [
  'my_module' => [
    // ...
    'moduleData' => [
      'allowedProperty' => '',
      'anotherAllowedProperty' => true,
    ],
  ],
];
Copied!
aliases
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\CMS\Backend\Routing\UriBuilder . Additionally, the aliases can also be used for references in other modules, for example to specify a module's parent.

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'],
  ],
];
Copied!

Example for a route alias identifier:

Excerpt of EXT:my_extension/Configuration/Backend/Modules.php
<?php

declare(strict_types=1);

return [
  'file_editcontent' => [
    // ...
    'path' => '/file/editcontent',
    'aliases' => ['file_edit'],
  ],
];
Copied!
routeOptions
Type
array

Generic side information that will be merged with each generated \TYPO3\CMS\Backend\Routing\Route::$options 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.

Default module configuration options (without Extbase) 

Name Type
array
routes
Type
array

Define the routes to this module. Each route requires at least the target. The _default route is mandatory, except for modules which can fall back to a submodule. The path of the _default route is taken from the top-level configuration. For all other routes, the route identifier is taken as path, 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'],
      ],
    ],
  ],
];
Copied!

All subroutes are automatically registered in a \TYPO3\CMS\Core\Routing\RouteCollection . The full syntax for route identifiers is <module_identifier>.<sub_route>, for example, my_module.edit. Therefore, using the \TYPO3\CMS\Backend\Routing\UriBuilder to create a link to such a sub-route might look like this:

\TYPO3\CMS\Backend\Routing\UriBuilder->buildUriFromRoute('my_module.edit');
Copied!

Extbase module configuration options 

Name Type
string
array
extensionName
Type
string

The extension name in UpperCamelCase for which the module is registered. If the extension key is my_example_extension the extension name would be MyExampleExtension.

controllerActions
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',
      ],
    ],
  ],
];
Copied!

The modules define explicit routes for each controller/action combination, as long as the enableNamespacedArgumentsForBackend feature 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.

This leads to the following URLs:

  • https://example.com/typo3/module/web/ExtkeyExample
  • https://example.com/typo3/module/web/ExtkeyExample/MyModule/list
  • https://example.com/typo3/module/web/ExtkeyExample/MyModule/detail

The route identifier of corresponding routes is registered with similar syntax as standard backend modules: <module_identifier>.<controller>_<action> . Above configuration will therefore register the following routes:

  • web_ExtkeyExample
  • web_ExtkeyExample.MyModule_list
  • web_ExtkeyExample.MyModule_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:

EXT:my_extension/Configuration/Backend/Modules.php
<?php

use TYPO3\CMS\Backend\Security\SudoMode\Access\AccessLifetime;

return [
  'tools_ExtensionmanagerExtensionmanager' => [
    // ...
    'routeOptions' => [
      'sudoMode' => [
        'group' => 'systemMaintainer',
        'lifetime' => AccessLifetime::M,
      ],
    ],
  ],
];
Copied!

See also Custom backend modules requiring the sudo mode.