Role definition

The text-based role definition is the main purpose of this extension's funcionality. This brings the advantage to have the access definitions under version control and add the roll-out of new or updated definitions to a CI or a deployment system.

New in version 2.0

Starting with backend_roles 2.0 it is possible to store the role definitions in YAML files.

New in version 2.0

Starting with backend_roles 2.0 it is possible to store the role definitions in the global configuration directory.

Definitions file

Location

The role definitions are expected to be found in either of following locations:

Global

Location: the project's configuration directory <project-root>/config/ (or typo3conf/ in legacy installations).

Filename BackendRoleDefinitions.yaml / BackendRoleDefinitions.php
Per extension

Location: an extension's configuration directory <extension>/Configuration.

Filename BackendRoleDefinitions.yaml / BackendRoleDefinitions.php

Note

Every such file that could be found by backend_roles will be interpreted as an independet role definitions file. It is not possible to overwrite role definitions from other sources.

The files are searched and loaded in the following order:

Global <project-root>/config/BackendRoleDefinitions.yaml
Global <project-root>/config/BackendRoleDefinitions.php
Per extension <extension>/Configuration/BackendRoleDefinitions.yaml
Per extension <extension>/Configuration/BackendRoleDefinitions.php

Format

The role definitions can be stored as YAML or PHP files. YAML files MUST contain an array RoleDefinitions, PHP files just return a plain array.

RoleDefinitions:
  -
    identifier: role-basic
    title: 'Basic role'
    # ...

return [
    [
        'identifier' => 'role-basic',
        'title' => 'Basic role',
        // ...
    ],
];

Role definition options

The available options correspond 1:1 to the fields of the be_groups record. Except for identifier and title.

The documentation of the types/formats can be found below.

Option name	Type	Description
`identifier`	Text	Required. Used to identify the role in a `be_groups` record
`title`	Text	Required. The title of the role is shown in the role-selector in `be_groups` records
`TSconfig`	Text	`be_groups.TSconfig`
`pagetypes_select`	Array	`be_groups.pagetypes_select`
`tables_select`	Array	`be_groups.tables_select`
`tables_modify`	Array	`be_groups.tables_modify`
`groupMods`	Array	`be_groups.groupMods`
`tables_modify`	Array	`be_groups.tables_modify`
`file_permissions`	Array	`be_groups.file_permissions`
`allowed_languages`	Array	`be_groups.allowed_languages`
`explicit_allowdeny`	Multi-Array	`be_groups.explicit_allowdeny`
`non_exclude_fields`	Multi-Array	`be_groups.non_exclude_fields`

Types / Format

The option formats are meant to be as close as "human-readable" as feasible to be a useful tool for site admins. They can be transformed to values of be_groups properites (and back).

Note

For the moment, refer to the role export in the Backend Module. The in-depth documentation of this format transformation is yet to be written.

Text

This is text only. It will be copied 1:1 to the corresponding field in be_groups.
Array

This array will be stored as comma-separated list in the corresponding field in be_groups.
Multi-Array

This multi-dimensional array will also be stored as comma-separated list in the corresponding field in be_groups. But the formatting is more complex as it stores lots of information.

Example: one file per role definition

It is common to have not one but lots of roles. For better overview and maintenance you can easily split the role definitions into multiple files. The "main" file only holds the relevant includes.

Create a directory <project-root>/config/BackendRoleDefinitions. In there add as much files as needed. Every file can then be included in the "main" file:

config/BackendRoleDefinitions.yaml

imports:
  - { resource: './BackendRoleDefinitions/AvdancedEditor.yaml' }
  - { resource: './BackendRoleDefinitions/SimpleEditor.yaml' }

config/BackendRoleDefinitions/AvdancedEditor.yaml

RoleDefinitions:
  -
    identifier: role-editor-advanced
    title: '[Role] Advanced editor'
    # ...

config/BackendRoleDefinitions/SimpleEditor.yaml

RoleDefinitions:
  -
    identifier: role-editor-simple
    title: '[Role] Simple editor'
    # ...

config/BackendRoleDefinitions.php

return [
    require __DIR__ . '/BackendRoleDefinitions/AvdancedEditor.php',
    require __DIR__ . '/BackendRoleDefinitions/SimpleEditor.php',
];

config/BackendRoleDefinitions/AvdancedEditor.php

return [
    'identifier' => 'role-editor-advanced',
    'title' => '[Role] Advanced editor',
    // ...
];

config/BackendRoleDefinitions/SimpleEditor.php

return [
    'identifier' => 'role-editor-simple',
    'title' => '[Role] Simple editor',
    // ...
];