Classes and Interfaces¶

The Name module provides a comprehensive set of classes and interfaces for working with structured name data. This document provides an overview of the key classes organized by functionality.

Plugin Classes¶

Field Type¶

NameItem¶

Namespace: Drupal\name\Plugin\Field\FieldType\NameItem
Extends: FieldItemBase
Purpose: Defines the name field type plugin

The NameItem class defines the schema, properties, and constraints for the name field type.

Key Methods:

// Get the property definitions for name components
public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition);

// Get the schema for the field storage
public static function schema(FieldStorageDefinitionInterface $field_definition);

// Get the default field settings
public static function defaultFieldSettings();

// Determine if the field is empty
public function isEmpty();

Field Properties:

Each name field has the following properties: - title - StringData - given - StringData - middle - StringData - family - StringData - generational - StringData - credentials - StringData

Usage Example:

use Drupal\field\Entity\FieldStorageConfig;
use Drupal\field\Entity\FieldConfig;

// Create a name field
$field_storage = FieldStorageConfig::create([
  'field_name' => 'field_full_name',
  'entity_type' => 'node',
  'type' => 'name',
]);
$field_storage->save();

$field = FieldConfig::create([
  'field_storage' => $field_storage,
  'bundle' => 'person',
  'label' => 'Full Name',
]);
$field->save();

NameWidget¶

Namespace: Drupal\name\Plugin\Field\FieldWidget\NameWidget
Extends: WidgetBase
Purpose: Provides the default widget for name fields

The NameWidget renders name field components as individual form elements with configurable layouts and labels.

Key Methods:

// Get default widget settings
public static function defaultSettings();

// Build the widget settings form
public function settingsForm(array $form, FormStateInterface $form_state);

// Build the field widget form elements
public function formElement(
  FieldItemListInterface $items,
  $delta,
  array $element,
  array &$form,
  FormStateInterface $form_state
);

Widget Settings:

components - Which components to display
minimum_components - Minimum required components
labels - Custom labels for components
component_layout - Layout option (default, asian, eastern, german)
show_component_required_marker - Show required markers
title_display - Title display mode
size - Field size
allow_family_or_given - Allow submission with only family OR given name

Usage in Form Display:

Configure through the UI at:
Structure > Content types > [Type] > Manage form display

Field Formatter¶

NameFormatter¶

Namespace: Drupal\name\Plugin\Field\FieldFormatter\NameFormatter
Extends: FormatterBase
Purpose: Formats name field values for display

The formatter plugin integrates with the name.formatter service to display name data.

Key Methods:

// Get default formatter settings
public static function defaultSettings();

// Build the formatter settings form
public function settingsForm(array $form, FormStateInterface $form_state);

// Format the field values for display
public function viewElements(FieldItemListInterface $items, $langcode);

Formatter Settings:

format - Name format to use (full, formal, family, given, etc.)
markup - Output markup type (none, simple, rdfa, microdata)
output - Output type (default, plain, raw)
multiple - List formatting settings
delimiter - Separator between names
and - Conjunction type (text, symbol, inherit)
delimiter_precedes_last - Delimiter behavior
el_al_min - Minimum names before "et al"
el_al_first - Number to show before "et al"

Usage Example:

// In a custom display
$items = $entity->get('field_full_name');
$formatter = \Drupal::service('plugin.manager.field.formatter')
  ->createInstance('name_formatter', [
    'field_definition' => $items->getFieldDefinition(),
    'settings' => [
      'format' => 'full',
      'markup' => 'none',
    ],
    'label' => '',
    'view_mode' => 'default',
  ]);

$render_array = $formatter->view($items);

Form Element¶

Name¶

Namespace: Drupal\name\Element\Name
Extends: FormElement
Purpose: Provides a composite name form element

The Name element can be used in any form to collect structured name data.

Element Type: #type => 'name'

Key Properties:

[
  '#type' => 'name',
  '#title' => t('Full Name'),
  '#default_value' => [
    'title' => '',
    'given' => '',
    'middle' => '',
    'family' => '',
    'generational' => '',
    'credentials' => '',
  ],
  '#components' => [  // Components to display
    'title' => 'title',
    'given' => 'given',
    'family' => 'family',
  ],
  '#minimum_components' => [  // Required components
    'given' => 'given',
  ],
  '#allow_family_or_given' => TRUE,  // Require either family OR given
  '#labels' => [  // Custom labels
    'title' => t('Title'),
    'given' => t('First Name'),
    'family' => t('Last Name'),
  ],
  '#component_layout' => 'default',  // Layout type
]

Usage Example:

$form['person_name'] = [
  '#type' => 'name',
  '#title' => $this->t('Full Name'),
  '#required' => TRUE,
  '#components' => [
    'given' => 'given',
    'middle' => 'middle',
    'family' => 'family',
  ],
  '#minimum_components' => [
    'given' => 'given',
    'family' => 'family',
  ],
  '#component_layout' => 'default',
];

Entity Classes¶

NameFormat¶

Namespace: Drupal\name\Entity\NameFormat
Extends: ConfigEntityBase
Implements: NameFormatInterface
Purpose: Configuration entity for name formats

Stores custom name format patterns.

Configuration:

id - Machine name
label - Human-readable label
pattern - Format pattern string (e.g., "t g m f s c")
locked - Whether the format is locked (system-defined)

Usage:

use Drupal\name\Entity\NameFormat;

// Load a format
$format = NameFormat::load('full');
$pattern = $format->get('pattern');

// Create a custom format
$format = NameFormat::create([
  'id' => 'custom_format',
  'label' => 'Custom Format',
  'pattern' => 't ig. f',  // "Dr. J. Smith"
]);
$format->save();

Admin UI:
/admin/structure/name

NameListFormat¶

Namespace: Drupal\name\Entity\NameListFormat
Extends: ConfigEntityBase
Implements: NameListFormatInterface
Purpose: Configuration entity for list formats

Stores settings for formatting lists of names.

Configuration:

delimiter - Separator between names (", ")
and - Conjunction type (text, symbol, inherit)
delimiter_precedes_last - Delimiter behavior (never, always, contextual)
el_al_min - Minimum for "et al" (0 = disabled)
el_al_first - Number to show before "et al"

Usage:

use Drupal\name\Entity\NameListFormat;

$list_format = NameListFormat::load('default');
$settings = $list_format->listSettings();

// Create custom list format
$list_format = NameListFormat::create([
  'id' => 'custom_list',
  'label' => 'Custom List Format',
  'delimiter' => '; ',
  'and' => 'symbol',  // Use "&"
  'delimiter_precedes_last' => 'always',
]);
$list_format->save();

Service Classes¶

See the Services Documentation for detailed information about:

NameFormatter - Format names for display
NameFormatParser - Parse format patterns
NameGenerator - Generate sample names
NameAutocomplete - Autocomplete functionality
NameOptionsProvider - Manage component options

Interfaces¶

NameFormatterInterface¶

Namespace: Drupal\name\NameFormatterInterface

Defines the interface for name formatting services.

Methods:

format(array $components, $type, $langcode) - Format a single name
formatList(array $items, $type, $list_type, $langcode) - Format a list of names
setSetting($key, $value) - Set a formatter setting
getSetting($key) - Get a formatter setting
getLastDelimiterTypes($include_examples) - Get delimiter type options
getLastDelimiterBehaviors($include_examples) - Get delimiter behavior options

NameGeneratorInterface¶

Namespace: Drupal\name\NameGeneratorInterface

Defines the interface for name generation services.

Methods:

generateSampleNames($limit, $field_definition) - Generate sample names
loadSampleValues($component, $gender) - Load sample component values

NameFormatInterface¶

Namespace: Drupal\name\NameFormatInterface

Defines the interface for NameFormat configuration entities.

Methods:

id() - Get format ID
label() - Get format label
get($property) - Get a property value
set($property, $value) - Set a property value

NameListFormatInterface¶

Namespace: Drupal\name\NameListFormatInterface

Defines the interface for NameListFormat configuration entities.

Methods:

listSettings() - Get list formatting settings array

Traits¶

NameFieldSettingsTrait¶

Namespace: Drupal\name\Traits\NameFieldSettingsTrait
Purpose: Shared field settings form elements

Provides common field settings form elements used by NameItem.

NameFormSettingsHelperTrait¶

Namespace: Drupal\name\Traits\NameFormSettingsHelperTrait
Purpose: Form settings helper methods

Provides methods for building component settings tables in field configuration forms.

Key Methods:

fieldSettingsFormPreRender($form) - Pre-render callback for settings forms

NameFormDisplaySettingsTrait¶

Namespace: Drupal\name\Traits\NameFormDisplaySettingsTrait
Purpose: Form display settings

Shared settings for widget configuration.

NameAdditionalPreferredTrait¶

Namespace: Drupal\name\Traits\NameAdditionalPreferredTrait
Purpose: Preferred/alternative name handling

Handles preferred and alternative name component references.

Controllers¶

NameAutocompleteController¶

Namespace: Drupal\name\Controller\NameAutocompleteController
Purpose: Provides autocomplete endpoints

Route: /name/autocomplete/{field_name}/{entity_type}/{bundle}/{target}

Usage:

The controller is used automatically by the NameWidget when autocomplete is enabled. It returns JSON responses with autocomplete suggestions.

Integration Plugins¶

Feeds Integration¶

Namespace: Drupal\name\Feeds\Target\NameTarget
Purpose: Feeds module integration for importing name data

Migrate Integration¶

Namespace: Drupal\name\Plugin\migrate\field\NameField
Purpose: Migrate API integration for Drupal 7 to Drupal 10+ migrations

Diff Integration¶

Namespace: Drupal\name\Plugin\diff\Field\NameFieldBuilder
Purpose: Diff module integration for comparing name field changes

Views Integration¶

Namespace: Drupal\name\Plugin\views\filter\Fulltext
Purpose: Views fulltext filter for name fields

Provides a full-text search filter that searches across all name components.

Classes and Interfaces¶

Plugin Classes¶

Field Type¶

NameItem¶

Field Widget¶

NameWidget¶

Field Formatter¶

NameFormatter¶

Form Element¶

Name¶

Entity Classes¶

NameFormat¶

NameListFormat¶

Service Classes¶

Interfaces¶

NameFormatterInterface¶

NameGeneratorInterface¶

NameFormatInterface¶

NameListFormatInterface¶

Traits¶

NameFieldSettingsTrait¶

NameFormSettingsHelperTrait¶

NameFormDisplaySettingsTrait¶

NameAdditionalPreferredTrait¶

Controllers¶

NameAutocompleteController¶

Integration Plugins¶

Feeds Integration¶

Migrate Integration¶

Diff Integration¶

Views Integration¶

See Also¶