Download the PHP package psb/user-deployment without Composer

PSBits ACL Deployment

Optimized import from (or export to) JSON of TYPO3 users and user groups

The file format used here offers better readability and maintainability than simple database dumps. You can split user data into multiple files (e.g. one for backend and one for fronent) and define default values as well es variables for often used configurations to keep the files small and easy to read.

• What does it do?
• Why should you use it?
• How it works
  • Export
  • Default values
  • Variables
  • Page tree access (be_groups only!)
  • File imports
  • Deployment

What does it do?

This package is an extension for TYPO3 CMS that provides a way to manage user configuration on a file basis instead of using the database as the primary system. You can edit the JSON files directly or use the TYPO3 backend to edit the users and groups as usual. The data can be exported to JSON via the command line.

Tables supported:

• be_groups
• be_users
• fe_groups
• fe_users
• pages (perms_groupid only)
• sys_filemounts

IMPORTANT!
No sensitive data (passwords, mfa configuration, etc.) will be exported.

Why should you use it?

This package was created to

• deploy user configuration to different environments (e.g. staging, production) in a consistent and reliable way
• apply the benefits of version control to non-sensitive user data

How it works

Export

It's a good idea to first export the current user configuration.

Shortened example output (comments are not part of the JSON, of course, but are added here for helpful explanations):

As can be seen in the example, no UIDs are used in the configuration!
The commands will resolve the UIDs of the groups, users and filemounts automatically. This is done by looking up the title and replacing it with the UID (and vice versa). This way, you don't have to worry about keeping the UIDs in sync and searching the JSON file for references is easier.

Default values

The ExortCommand defines sets of default values for each table. These defaults are written to "_default" in the JSON file. Only the values that are different from that need to be specified in the single records.

Variables

The "_variables" section is used to define variables that can be used in the configuration. This is useful for values that are used multiple times in the configuration, for example, if you have a set of groups or a description that is used for multiple users. Variables are referenced by their name, e.g. @myVariable. The value of a variable is used, when the value of a field matches it exactly.

Example:

You do not have to use the "@" sign, but it is recommended to keep to a naming convention to avoid confusion with other values.

Page tree access (be_groups only!)

The "_pageTreeAccess" property is used to define access to the page tree. The value is the UID of the page that the group should have access to. This will set the perms_groupid field of the page. The value can be a single UID, an array or a comma-separated list of UIDs. The perms_groupid will be inherited by all child pages, unless they have a different value set. If a child page has a different value set, all pages above it in the tree will receive visibility for everybody, so that the users can see the rootline of the page.

Important:
The deploy command will update the TSconfig field of page records and synchronize the property TCEMAIN.permissions.groupid with the values of _pageTreeAccess. This is necessary to ensure that newly created pages will inherit the correct permissions from the parent page. If a page has no _pageTreeAccess value set, the TCEMAIN.permissions.groupid will be removed from the TSconfig field if it was set before!

File imports

There is a special property named "files" on the first level that can be used to split the configuration into multiple files. This might be useful when dealing with a lot of records. The files will be imported in the given order and merged into one configuration. If a field value of a record is defined in multiple files, the last definition will be used.

Example:

Deployment

The configuration can be deployed to the database via the command line:

Steps:

1. Check if "files" is defined. If so, load the additional files and merge them into one configuration.
2. Iterate over the given tables and records.
3. Get the default values for the table and merge them with the record values. If a field is not defined in the record, the default value will be used.
4. Look for variable references and replace them with the actual values.
5. Resolve group references and replace them with the actual UIDs.
6. Check if the record already exists in the database.
   1. If it does, update the record with the new values.
   2. If it does not, create a new record with the given values.
7. If the --remove option is set, remove all records that are not in the configuration file. This will only soft delete the records, so they can be restored later if needed.