API Overview

Architecture summary

The Name module combines three API layers:

1. Field API plugins for storage, form input, and display.
2. Container services for formatting, parsing, generation, autocomplete, and option resolution.
3. Extension points such as hook_name_widget_layouts() and integration plugins for other modules.

Core data model

Name values are keyed arrays with these component keys:

• title
• given
• middle
• family
• generational
• credentials

Optional extra keys, such as preferred/alternative variants, may be handled by formatting rules depending on field and formatter settings.

Plugin layer

• Field type: Drupal\name\Plugin\Field\FieldType\NameItem
• Widget: Drupal\name\Plugin\Field\FieldWidget\NameWidget
• Formatter plugin: Drupal\name\Plugin\Field\FieldFormatter\NameFormatter
• Form element: Drupal\name\Element\Name

The formatter plugin delegates formatting logic to the formatter service.

Service layer

Primary service IDs:

• name.formatter
• name.format_parser
• name.generator
• name.autocomplete
• name.options_provider

See Services Overview for exact class/interface mappings.

Recommended usage pattern

For reusable class-based code, inject interfaces from Drupal\name\Service.

use Drupal\name\Service\NameFormatterInterface;

final class ExampleConsumer {

  public function __construct(
    private readonly NameFormatterInterface $formatter,
  ) {}
}

Direct \Drupal::service() calls are acceptable for procedural or one-off code, but avoid them in classes you control.

Configuration entities

• Drupal\name\Entity\NameFormat for component display patterns.
• Drupal\name\Entity\NameListFormat for list conjunction/delimiter behavior.

Format parsing architecture

The name.format_parser service delegates its rendering pipeline to a set of stateless utility classes under Drupal\name\Utility:

• NameFormatTokens::build() — converts a name component array into a token map.
• NameFormatLexer::tokenize() — walks the format string and resolves tokens.
• NameFormatModifiers — applies casing, initials, and conditional modifiers.
• NameFormatAssembler::assemble() — joins resolved pieces into a plain string.
• NameFormatParser — static facade over the three steps above.
• NameFormatOutput::wrap() — wraps the plain string in the requested markup render array.
• NameFormatHelp — provides translated token labels shared by the format edit form and the name.formats help topic.

The NameFormatParserService class retains its full public/protected API for backwards compatibility with subclasses and existing service consumers. See Parser Service for usage. See Help integration for the token reference UI.

Hook API (Drupal 11.1+)

Object-oriented hook implementations live under Drupal\name\Hook\ and are registered as autowired services in name.services.yml:

• HelpHooks — hook_help()
• TokenHooks — hook_token_info_alter(), hook_tokens(), hook_tokens_alter()
• UserHooks — hook_user_format_name_alter(), hook_user_load() (uses name.user_realname_preload and name.additional_component)
• FieldConfigHooks — hook_field_config_create(), hook_field_config_delete()
• FieldHooks — hook_field_views_data(), hook_field_type_category_info_alter()
• WidgetLayoutHooks — hook_name_widget_layouts()
• ThemeHooks — hook_theme()

On Drupal 10.3–11.0, procedural shims in name.module (for example name_token_info_alter(), name_help()) delegate to these classes. New contributor work should target the Hook API classes, not duplicate logic in name.module.

hook_user_save() remains a procedural implementation in name.module only (it clears the per-request realname static cache when a user is saved).

Internal utility pipelines

Several subsystems delegate to @internal utility classes under Drupal\name\Utility\. Interact with these areas through services and plugins, not by calling utilities directly from custom modules.

Area	Key utilities
Format parsing	NameFormatTokens, NameFormatLexer, NameFormatModifiers, NameFormatAssembler, NameFormatParser, NameFormatOutput, NameFormatHelp, UnicodeExtras
Token replacement	FormattedNameTokenInfoRegistrar, FormattedNameTokenParser, FormattedNameTokenReplacement, TokenFieldSubTypeResolver
Autocomplete	AutocompletePlanBuilder, AutocompleteMatcher, AutocompleteFieldValueLookup
Formatter plugin	Link Target, Formatter Summary
Form element / validation	ComponentBuilder, NameComponents, NameOptionValidator

See Classes and Interfaces for the full class list.

Field storage settings

Field storage keys (components, autocomplete, options, preferred/alternative references, user override_format) are documented on Field storage settings.

Extension points

• Hook: hook_name_widget_layouts()

Integration with other modules

• Devel
• User
• Taxonomy
• Views
• Help
• Token
• Feeds
• Diff
• Migrate

Legacy procedural helpers

Legacy helper functions in name.module are retained mainly for compatibility. New code should use the service layer and Hook API classes instead.

Hook shims (delegate to Hook API classes)

Procedural function	Delegates to
name_help()	HelpHooks
name_token_info_alter()	TokenHooks
name_tokens()	TokenHooks
name_tokens_alter()	TokenHooks
name_user_format_name_alter()	UserHooks
name_user_load()	UserHooks
name_field_config_create()	FieldConfigHooks
name_field_config_delete()	FieldConfigHooks
name_field_views_data()	FieldHooks
name_field_type_category_info_alter()	FieldHooks
name_theme()	ThemeHooks
name_name_widget_layouts()	WidgetLayoutHooks

Procedural-only hooks

Function	Role
name_user_save()	Clears name_user_realname_cache static when a user is saved.

Deprecated service wrappers (name:8.x-1.3, removed in name:2.0.0)

Function	Use instead
name_get_additional_component()	name.additional_component → getAdditionalComponent()
name_get_custom_format_options()	name.format_options → getCustomFormatOptions()
name_get_custom_list_format_options()	name.format_options → getCustomListFormatOptions()
name_get_format_by_machine_name()	name.format_options → getFormatPatternByMachineName()
name_widget_layouts()	name.widget_layouts → getLayouts()
name_user_format_name_alter_preload()	name.user_realname_preload → preload()

Element callbacks such as name_element_validate() delegate to Drupal\name\Element\Name and name.element_validator. Prefer the element class and validator service in new code.