README

Replaces the username Drupal shows for an account with the contents of one or more fields on the user entity. You pick which user fields to use and in what order, and the module concatenates their values, separated by single spaces, to build the name. It hooks hook_user_format_name_alter(), so the replacement applies everywhere core asks an account for its display name, and it also overrides the title callback on the user page so /user/{uid} gets the same treatment. Accounts with none of the configured fields filled in keep their normal username.

Each field you assign is stored as a namefield config entity, so the configuration is exportable like any other config.

Requirements

Drupal 10.3 or later, or Drupal 11. No contrib dependencies.

The module assumes the user entity already has at least one text field to read from. A stock Drupal site does not have one. Out of the box the only field storage on the user entity is user_picture, which is an image field, so without adding your own field there is nothing usable to configure. Add a plain text field to the user account at /admin/config/people/accounts/fields before configuring this module.

Two permissions are involved, and you need both. See Usage.

Installation

Install as usual at /admin/extend, or drush en custom_display_name.

Nothing fails at install time if you have no user text fields, but the configuration form is unusable until you add one, because the field selector is required and would have nothing valid to offer.

Usage

Configure at /admin/config/people/display-name, also linked from the People section of the configuration page.
Add one entry per user field you want included, at /admin/config/people/display-name/add. Give it a label, a machine name, the user field to read, and a weight.
Weight runs from -9 to 9 and sets the order the field values are joined in. Lower weights come first.
Values are joined with a single space. Leading, trailing and repeated whitespace is collapsed.
If every configured field is empty on an account, the account keeps its regular username.
Permissions: administer display name fields (the machine name is administer namefields) grants access to the listing only. Adding, editing and deleting entries are checked against the entity's admin permission, which is core's administer users. A role with only the first permission can see the list and nothing else, so grant both.

Development

The repository ships a DDEV setup. The module itself is the repository root and is symlinked into web/modules/custom/custom_display_name inside the container. web/ and vendor/ are generated and git ignored.

ddev start runs the bootstrap in .ddev/post-start.sh: it runs poser to build the Drupal codebase, installs the site on an empty database, symlinks the module into place, enables devel and this module, and prints a one time login link. The admin account password is 1.

Tooling:

ddev phpcs runs the Drupal and DrupalPractice sniffs. Currently clean.
ddev phpcbf fixes what it can. The drupal-contrib-extras add-on patches it to skip .ddev/.
ddev phpstan --level=6 -c ../../../../phpstan.neon runs static analysis. Currently clean. Both arguments are needed: the level, because the wrapper otherwise analyses at level 0, and the config path, because the add-on symlinks phpstan.neon into the module directory with a relative path that does not resolve, so plain ddev phpstan runs without the repository config. The path is relative to web/modules/custom/custom_display_name, which is where the wrapper changes to.

Add-ons in use: ddev-drupal-contrib, drupal-contrib-extras, pimp-my-shell and ddev-drupal.

Known issues and notes

The field selector offers every field storage on the user entity, not only text fields, despite what the code comment says. Image fields such as user_picture show up and can be selected, but produce nothing, because the module reads the value property and an image field does not have one.
Save messages are logged to the contact channel rather than this module's own. It looks like a leftover from the core Contact module this code was modelled on. Changing it would move existing log entries, so it has been left alone.
The links paths in the Namefield entity annotation use display_name with an underscore, while the routes in custom_display_name.routing.yml use display-name with a hyphen. The routes win, so URLs are correct, and the annotation strings are dead. They are misleading if you read them expecting them to be the real paths.
The Namefield entity declares revision_metadata_keys, which config entities do not use. It has no effect.
Toward Drupal 12: the Namefield entity still uses the @ConfigEntityType doc block annotation rather than a PHP attribute. Nothing else in the module uses plugin annotations.
The procedural hook in custom_display_name.module is a thin #[LegacyHook] stub kept only so the module still works on Drupal 10, which has no attribute hooks. Once the supported floor is Drupal 11.1 the stub and the services.yml entry for the hook class can both be dropped, and src/Hook/CustomDisplayNameHooks.php becomes the only implementation.

faithcatholic / custom_display_name

Package info

Security

Statistics