Modules.php - Backend module configuration

Changed in version 12.0

Registration of backend modules was changed with version 12. If you are using an older version of TYPO3 please use the version switcher on the top left of this document to go to the respective version.

The configuration of backend modules is placed in the dedicated Configuration/Backend/Modules.php configuration file.

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
parent	string
path	string
access	string
workspaces	string
position	array
appearance	array
appearance.renderInModuleMenu	bool
iconIdentifier	string
icon	string
labels	array of strings or string
component	string
navigationComponent	string
navigationComponentId	string
inheritNavigationComponentFromMainModule	bool
moduleData	array
aliases	array
routeOptions	array

parent

Type: string

If the module should be a submodule, the parent identifier, for example web 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. Currently only appearance.renderInModuleMenu is available.

appearance.renderInModuleMenu

Type: bool

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

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

An array with the following keys:

title
description
shortDescription

The value of each array entry can either be a string containing the static text, or a locallang label reference.

Alternatively define the path of a locallang file reference. A referenced file should contain the following label keys:

mlang_tabs_tab (used as module title)
mlang_labels_tabdescr (used as module description)
mlang_labels_tablabel (used as module short description)

component

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

The view component, responsible for rendering the module.

navigationComponent

Type: string

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

@typo3/backend/page-tree/page-tree-element: The page tree as used in the Web module.
@typo3/backend/tree/file-storage-tree-container: The file tree as used in the Filelist module.

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,
        ],
    ],
];

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' => 'web',
        // ...
        // 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

<?php

declare(strict_types=1);

return [
    'file_editcontent' => [
        // ...
        'path' => '/file/editcontent',
        'aliases' => ['file_edit'],
    ],
];

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

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');

Extbase module configuration options

Note

Using these Extbase configurations tells the Core to bootstrap Extbase and expecting controllers based on \TYPO3\CMS\Extbase\Mvc\Controller\ActionController . Do not use it for non-Extbase controller. Use routes instead.

Name	Type
extensionName	string
controllerActions	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',
            ],
        ],
    ],
];

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/MyModuleController/list
https://example.com/typo3/module/web/ExtkeyExample/MyModuleController/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.MyModuleController_list
web_ExtkeyExample.MyModuleController_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,
            ],
        ],
    ],
];