Backend roles for TYPO3

Backend roles for TYPO3

Version

main

Language

en

Description

Manual of the TYPO3 extension "Backend roles for TYPO3" (backend_roles)

Author

Christian Futterlieb

License

This document is published under the Creative Commons BY 4.0 license.

Rendered

Thu, 12 Jun 2025 21:00:26 +0000

The content of this document is related to TYPO3 CMS, a GNU/GPL CMS/Framework available from www.typo3.org

This TYPO3 extension allows the text-based definition and synchronization of (parts of) be_groups records.

Table of Contents:

Manual

Miscellaneous

Introduction

This extension allows the text-based definition and synchronization of (parts of) be_groups records.

Features

  • Define the access definitions for be_groups records
  • Set up be_groups records to be synchronized with the definitions
  • Synchronize via TYPO3 backend or CLI command
  • Export definitions representing existing be_groups records for an easy migration towards this extension. Either as download or text-based copy&paste

Screenshots

The Backend Module's overview

Backend Module

The Backend Module's overview

The Backend Module's export view

Backend role export

The Backend Module's export view

Installation

System requirements / compatibility

Backend roles TYPO3 PHP Support / Development
4.x 12.4 - 13.4 8.1 - 8.4 active development
3.x 12.4 8.1 - 8.2 security, priority bugfixes
2.x 11.5 7.4 - 8.2 security
1.x 9.5 - 10.4 7.2 - 7.3 none

Perform the installation

Install the extension the normal way in TYPO3.

For Composer users:

composer require christianfutterlieb/backend_roles
Copied!

Get the source code

git clone https://github.com/christianfutterlieb/backend_roles.git
Copied!

Upgrade

Before an upgrade of this extension, please read this section carefully.

Versioning

This extension follows the rules of Semantic Versioning.

Preparation

Before an upgrade, read the changelog of all versions between the currently installed and the target version (that one you want to upgrade to). They can be found here.

Extension configuration

  1. Go to Admin Tools > Settings > Extension Configuration
  2. Open backend_roles

Configuration options reference

hideManagedBackendUserGroupColumnns

hideManagedBackendUserGroupColumnns
type

bool

Default

true

If set, the columns of a be_groups record which are managed by backend_roles won't be shown in FormEngine.

$GLOBALS['EXTCONF']['backend_roles']['hideManagedBackendUserGroupColumnns'] = true;
Copied!

showSynchronizationStatus

showSynchronizationStatus
type

bool

Default

true

If set, the synchronization status of a be_groups record will be shown. At the moment this results in displaying an overlay to the be_groups record icon (only if there is not yet another overlay active, like the red sign for 'hidden').

$GLOBALS['EXTCONF']['backend_roles']['showSynchronizationStatus'] = true;
Copied!

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:

  1. Global

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

    Filename BackendRoleDefinitions.yaml / BackendRoleDefinitions.php

  2. Per extension

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

    Filename BackendRoleDefinitions.yaml / BackendRoleDefinitions.php

The files are searched and loaded in the following order:

  1. Global <project-root>/config/BackendRoleDefinitions.yaml
  2. Global <project-root>/config/BackendRoleDefinitions.php
  3. Per extension <extension>/Configuration/BackendRoleDefinitions.yaml
  4. 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'
    # ...
Copied! 
return [
    [
        'identifier' => 'role-basic',
        'title' => 'Basic role',
        // ...
    ],
];
Copied!

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

  1. Text

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

  2. Array

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

  3. 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' }
Copied!
config/BackendRoleDefinitions/AvdancedEditor.yaml 
RoleDefinitions:
  -
    identifier: role-editor-advanced
    title: '[Role] Advanced editor'
    # ...
Copied!
config/BackendRoleDefinitions/SimpleEditor.yaml 
RoleDefinitions:
  -
    identifier: role-editor-simple
    title: '[Role] Simple editor'
    # ...
Copied!
config/BackendRoleDefinitions.php 
return [
    require __DIR__ . '/BackendRoleDefinitions/AvdancedEditor.php',
    require __DIR__ . '/BackendRoleDefinitions/SimpleEditor.php',
];
Copied!
config/BackendRoleDefinitions/AvdancedEditor.php 
return [
    'identifier' => 'role-editor-advanced',
    'title' => '[Role] Advanced editor',
    // ...
];
Copied!
config/BackendRoleDefinitions/SimpleEditor.php 
return [
    'identifier' => 'role-editor-simple',
    'title' => '[Role] Simple editor',
    // ...
];
Copied!

4.0.0

Breaking changes

No breaking changes.

Support for TYPO3 12.4 and 13.4

This version supports both TYPO3 LTS versions: 12.4 and 13.4, with their respective PHP versions.

All Changes

This is a list of all changes in this release:

a2a78ef [DOCS] Update current system requirements / compatibility
8630fc2 [DOCS] Add system requirements to installation section
b12c2e4 [BUGFIX] Do not look for the removed ext_tables.php
eaa0e75 [FEATURE] Register iocons via service container
38086f5 [TASK] Re-set version to 4.0.0-dev
7393b6a [RELEASE] Release release candidate 4.0.0-rc1
692b81d [TASK] Get rid of ext_tables.php
3961e5c [BUGFIX] Add a class alias while running phpstan
513d7a5 [BUGFIX] Do not use AsEventListener attribute yet
6b2f33f [FEATURE] Reflect support for TYPO3/PHP versions
2eb826f [BUGFIX] Use the explicit nullable type
9e47745 [TASK] Add a temporary 'cgl-php84-tmp' job for PHP 8.4
a5cee46 [BUGFIX] Use the explicit nullable type
4bde270 [TASK] Replace PHPDoc annotations with PHP attributes in unit tests
6960a7d [BUGFIX] Use mock object for YamlFileLoader
fe3a735 [TASK] Replace unsupported usage of PDO::PARAM_ constants
e5e9a30 [FEATURE] Move IconFactory overrideIconOverlay hook to PSR-14 event
a418e2a [FEATURE] Move flash messaging to notification queue
88872c1 [FEATURE] Adopt simplified ext:backend ModuleTemplate API
22ffe39 [TASK] Satisfy CGL check
a1baa9d [TASK] Declare support for TYPO3 v12.4 and v13.4
3bdfe8e [TASK] Raise version to v4.0.0-dev
c96f577 [TASK] Update workflow configs to reflect current branches
9726400 [BUGFIX] Correct php version dependency constraints
253cffb [TASK] Update configuration files to comply with CGL
8fe4edb [BUGFIX] Prevent error when tablename/uid combination leads to exception
10fbd1e [TASK] Add changelog for version 2.1.0
b42ff49 [TASK] Raise version to 3.1.1-dev
Copied!

Generated with git log 3.1.0..HEAD --oneline --no-decorate

3.1.1

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

f6aa5af [TASK] Satisfy CGL check
050c4b0 [TASK] Add CI config for version branch 3.1
c96f577 [TASK] Update workflow configs to reflect current branches
9726400 [BUGFIX] Correct php version dependency constraints
253cffb [TASK] Update configuration files to comply with CGL
8fe4edb [BUGFIX] Prevent error when tablename/uid combination leads to exception
10fbd1e [TASK] Add changelog for version 2.1.0
b42ff49 [TASK] Raise version to 3.1.1-dev
Copied!

Generated with git log 3.1.0..HEAD --oneline --no-decorate

3.1.0

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

61d1db3 [FEATURE] Add synchronization status visualization
3e062e2 [TASK] Raise version to 3.1.0-dev
0532e50 [TASK] Add rector/rector
43731b9 [TASK] Normalize composer.json with ergebnis/composer-normalize
404cbe1 [BUGFIX] Add an encryption key for phpunit runs
f8b8cfd [FEATURE] Add new project builder script
c0c70f2 [TASK] Add changelog of version 3.0.3
55f0577 [TASK] Raise version to 3.0.4-dev
Copied!

Generated with git log 3.0.3..HEAD --oneline --no-decorate

3.0.3

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

71fa3f1 [BUGFIX] Add compatibility for symfony/console v7
e1676a0 [TASK] Fix cgl issues
6b26dca [TASK] Uee GitHub CI
666f761 [BUGFIX] Automatically remove docker containers
61f5367 [TASK] Add changelog of version 2.0.2
0814153 [TASK] Fix version number in changelog title
2119492 [TASK] Raise version to 3.0.3-dev
Copied!

Generated with git log 3.0.2..HEAD --oneline --no-decorate

3.0.2

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

dc5bee9 [TASK] Add changelog of version 2.0.1
4bc011b [TASK] Raise version to 3.0.2-dev
Copied!

Generated with git log 3.0.1..HEAD --oneline --no-decorate

3.0.1

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

a7ec296 [TASK] Add phpstan for static code analysis
b3b6278 [BUGFIX] Correct wrong namespaces in tests
3f25422 [TASK] Add section "support" to composer.json
6f8107e [BUGFIX] Ignore database columns with null value
e583e0b [BUGFIX] Change extension category
12f5d91 [TASK] Update README
d45390e [TASK] Raise version to 3.0.1-dev
Copied!

Generated with git log 3.0.0..HEAD --oneline --no-decorate

3.0.0

This new release supports TYPO3 v12.4. For more information see System requirements / compatibility.

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

97e541d [TASK] Add changelog from v2.0.0 release
efbea53 [TASK] Improve documentation
e580f49 [TASK] Sort backend roles selector by label
e7e0fe7 [FEATURE] Add changelog to documentation
8bdb11d [!!!][TASK] Unify role definitions file name
50ca14a [TASK] Add more documentation
569b4ac [!!!][FEATURE] Use constructor dependency injection everywhere
f286846 [FEATURE] Add possibility to download role definitions as file
10b5b83 [FEATURE] Add YAML configuration export to the BackendModule
efd5535 [FEATURE] Add support for global configuration storage
86f2f2c [FEATURE] Add support for YAML configuration
1798b9d !!![FEATURE] Improve definition loading and handling
c736835 [FEATURE] Re-enable shortcuts in the backend module
f9966a7 [BUGFIX] Fix CGL issues
3d7a205 !!![TASK] Adopt new TYPO3 backend APIs
c0c0c25 [TASK] Move roleIdentifier selector generation to an itemsProcFunc
834c605 [TASK] Remove deprecated constants
423d2e3 [TASK] Add package branch alias "dev-2"
4df0d76 [FEATURE] Add documentation
56bd173 [TASK] Cleanup anonymous function construct
1738d0a [TASK] Make dataprovider methods static
c45813e [TASK] Apply cgl
b99adda [!!!][FEATURE] Add runTests.sh - a docker-based test runner
431625c [TASK] Re-define dev-dependencies
13b0be1 [TASK] Raise version to 3.0.0-dev
Copied!

Generated with git log 2.0.0..HEAD --oneline --no-decorate

2.1.0

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

9589c93 [FEATURE] Add synchronization status visualization
abcae2e [TASK] Add rector/rector
59234b6 [BUGFIX] Add an encryption key for phpunit runs
60d4419 [TASK] Normalize composer.json with ergebnis/composer-normalize
5dad4e6 [FEATURE] Add new project builder script
0c465cb [TASK] Raise version to 2.1.0-dev
19d2101 [TASK] Fix cgl issues
a763693 [TASK] Uee GitHub CI
7ee9e86 [BUGFIX] Automatically remove docker containers
8bc64b5 [TASK] Raise version to 2.0.3-dev
Copied!

Generated with git log 2.0.2..HEAD --oneline --no-decorate

2.0.2

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

d0fde01 [BUGFIX] Correct constructor arguments order
81ba4b5 [TASK] Raise version to 2.0.2-dev
Copied!

Generated with git log 2.0.0..HEAD --oneline --no-decorate

2.0.1

Breaking changes

No breaking changes.

All Changes

This is a list of all changes in this release:

bad4fd7 [TASK] Ignore changelogs of version 3.x
c7769b6 [TASK] Add phpstan for static code analysis
3e7eab4 [BUGFIX] Correct wrong namespaces in tests
9c12066 [TASK] Add section "support" to composer.json
69d10ed [BUGFIX] Ignore database columns with null value
0660737 [BUGFIX] Change extension category
0409281 [TASK] Update README
cd23df3 [TASK] Raise version to 2.0.1-dev
Copied!

Generated with git log 2.0.0..HEAD --oneline --no-decorate

2.0.0

This new release supports TYPO3 v11.4. For more information see System requirements / compatibility. Lots of changes and improvements have been made, enjoy the renewed backend_roles extension.

Breaking changes

Change vendor name

The vendor name of the composer package changed from aaw-team/backend_roles to christianfutterlieb/backend_roles. See commit 7085ec011039560fb94642afb5b4767d2d8a41a8.

Add runTests.sh

Testing (and other processes) are handeled by a bash script runTests.sh, as it is done in TYPO3 core. The following composer scripts have been removed:

  • php-cs-fixer
  • run-tests

See commit cb2426677fe870595a05e57988b777b0d5ccec82.

Features

Support for YAML-based configuration

Role definitions can now be stored in YAML files as well. See Role definition for more information.

In the backend module, the export of be_groups supports YAML too.

Support for global configuration

Role definitions can now be stored in the global config directory. See Role definition for more information.

Download role definitions export as file

Role definitions exports can now be downloaded as YAML or PHP file.

Deprecations

Role definitions file name

The use of the role definition file Configuration/RoleDefinitions.php is deprecated an will be removed in v3. Use Configuration/BackendRoleDefinitions.php instead, or the newly introduced possibility of global role definitions in config/BackendRoleDefinitions.yaml or config/BackendRoleDefinitions.php.

All Changes

This is a list of all changes in this release:

8095056 [TASK] Improve documentation
5aed246 [TASK] Sort backend roles selector by label
dd7a9eb [BUGFIX] No need to deprecate Configuration/RoleDefinitions.yaml
0924768 [FEATURE] Add changelog to documentation
36c1f69 [!!!][TASK] Unify role definitions file name
8033acc [TASK] Change version in the documentation
af1d3c3 [TASK] Add more documentation
16969c1 [FEATURE] Add documentation
0aac702 [FEATURE] Add possibility to download role definitions as file
7f9bfd5 [FEATURE] Add YAML configuration export to the BackendModule
7c59f5d [FEATURE] Add support for global configuration storage
2bbce66 [FEATURE] Add support for YAML configuration
e6a4f45 !!![FEATURE] Improve definition loading and handling
b0aa799 [TASK] Move roleIdentifier selector generation to an itemsProcFunc
4cd4154 [TASK] Remove deprecated constants
d90cafb [TASK] Add package branch alias "dev-2"
8906a74 [TASK] Apply cgl
cb24266 [!!!][FEATURE] Add runTests.sh - a docker-based test runner
0dbf3d6 [TASK] Re-define dev-dependencies
e48bf80 [TASK] Update dependencies
7085ec0 [!!!][TASK] Change package name
e4d1288 [BUGFIX] Fix PHP 8 problems
3fe98a8 [TASK] Remove homegrown errorcode
7714788 [TASK] Reset version to 2.0.0-dev
f8238a0 [RELEASE] Release version 2.0.0-beta1
fe98c3c [TASK] Return ResponseInterface in controller action when possible
f3592e2 [TASK] Remove usage of generic extbase domain classes
607aa1c [TASK] Adapt .gitignore
4ddb751 [TASK] Update dependency requirements
b5c9446 [TASK] Allow composer plugins
750dad6 [TASK] Remove outdated code
80a0ed8 [TASK] Update composer.json
d41dc96 [TASK] Move build directory
dc0adaf [TASK] Raise version to 2.0.0-dev
0d72159 [TASK] Add README.md
879cfe4 [TASK] Raise version to 1.1.4-dev
Copied!

Generated with git log 1.1.3..HEAD --oneline --no-decorate

1.1.3

All Changes

This is a list of all changes in this release:

59119f0 [RELEASE] Release version 1.1.3
b353e8c [TASK] Add extra.typo3/cms.extension-key to composer.json
a5a1ebf [BUGFIX] Statically called methods must be declared static
eb6a069 [TASK] Raise version to 1.1.3-dev
Copied!

Generated with git log 1.1.2..1.1.3 --oneline --no-decorate

1.1.2

All Changes

This is a list of all changes in this release:

37cd23d [RELEASE] Release version 1.1.2
75055f9 [BUGFIX] Do not ignore zeroes when filtering
a836401 [BUGFIX] Only fix our own code
4a91a23 [TASK] Raise version to 1.1.2-dev
Copied!

Generated with git log 1.1.1..1.1.2 --oneline --no-decorate

1.1.1

All Changes

This is a list of all changes in this release:

45484ac [RELEASE] Release version 1.1.1
46d0dc2 [TASK] Improve export: ignore 'empty' values
69ed0a6 [TASK] Raise version to 1.1.1-dev
Copied!

Generated with git log 1.1.0..1.1.1 --oneline --no-decorate

1.1.0

All Changes

This is a list of all changes in this release:

4aacf4b [RELEASE] Release version 1.1.0
9aada99 [TASK] Fix/add unit tests and add a description for the array ordering
0759714 [FEATURE] Sort formatted array
8dbb197 [FEATURE] Allow synchronisation of allowed_languages
384f32a [TASK] Raise version to 1.1.0-dev
e181874 [TASK] Raise version to 1.0.1-dev
Copied!

Generated with git log 1.0.0..1.1.0 --oneline --no-decorate

1.0.0

All Changes

This is a list of all changes in this release:

a6dbf64 [RELEASE] Release version 1.0.0
76939f1 [FEATURE] Add synchronization as console command
54e1bc1 [TASK] Add extension and module icon
0c662f9 [BUGFIX] Workaround PHP < v7.3 behaviour with stdClass() of var_export()
e892cd9 [BUGFIX] Prevent errors in TYPO3 Upgrade checks
ee670dd [TASK] Simplify configuration
114c206 [FEATURE] Add a simple role exporter
6a77874 [TASK] Initial code
dcb87fe [TASK] Initial commit, add .gitignore file
Copied!

Generated with git log 1.0.0 --oneline --no-decorate

Sitemap