Skip to content

User integration

Name integrates with Drupal core User so a configured Name field can provide the account display name.

This updates the account Display Name (for example getDisplayName() and labels shown in UI), not the account login name (name).

Requirements

  • Name module.
  • Drupal core User module.
  • A Name field on the user bundle.

What Name provides

Hook API (Drupal\name\Hook\UserHooks)

  • hook_user_format_name_alter() — replaces the formatted name with $account->realname when set. Calls name.user_realname_preload when the account object lacks realname.
  • hook_user_load() — builds and caches realname on loaded users from the configured preferred Name field (name.settings:user_preferred), using name.formatter and name.additional_component for preferred/alternative field references.

Procedural shims name_user_format_name_alter() and name_user_load() in name.module delegate to UserHooks on supported cores.

Procedural-only hook

  • name_user_save() — clears the per-request name_user_realname_cache static when a user entity is saved (not implemented on UserHooks).

Field config (Drupal\name\Hook\FieldConfigHooks)

  • hook_field_config_create() and hook_field_config_delete() keep name.settings:user_preferred in sync when user Name fields are created or removed.

Formatting uses name.formatter and the field's override_format setting. See Field storage settings.

Services involved

Service ID Role
name.user_realname_preload Loads full user entity when realname is needed during user_format_name_alter.
name.additional_component Resolves preferred/alternative references on the name field before formatting.
name.formatter Formats the component array into display text.

Site builder usage

  1. Add a Name field to users (/admin/config/people/accounts/fields).
  2. In that field's settings, enable: Use this field to override the user's login name?
  3. Choose the User name override format to use (override_format).
  4. Save settings and clear caches if needed.

After this, user display names come from that Name field formatting.

Behavior notes

  • The login username remains unchanged ($account->getAccountName()).
  • The display label comes from Name ($account->getDisplayName()).
  • Anonymous users are not altered.

See also