Skip to content

Name Formatter Service

Overview

The Name Formatter service (name.formatter) is the primary service for formatting name component arrays into display strings. It should be used for all name formatting requests.

Service ID: name.formatter Class: Drupal\name\NameFormatter Interface: Drupal\name\NameFormatterInterface

Basic Usage

Formatting a Single Name

// Get the service
$formatter = \Drupal::service('name.formatter');

// Name components array
$name = [
  'title' => 'Dr.',
  'given' => 'Jane',
  'middle' => 'Marie',
  'family' => 'Smith',
  'generational' => 'Jr.',
  'credentials' => 'PhD',
];

// Format using default format
$formatted = $formatter->format($name);
// Result: "Dr. Jane Marie Smith Jr. PhD"

// Format using a specific format
$formatted = $formatter->format($name, 'family');
// Result: "Smith"

$formatted = $formatter->format($name, 'given');
// Result: "Jane"

$formatted = $formatter->format($name, 'formal');
// Result: "Dr. Smith, Jane Marie, Jr., PhD"

Formatting a List of Names

$formatter = \Drupal::service('name.formatter');

$names = [
  ['given' => 'John', 'family' => 'Doe'],
  ['given' => 'Jane', 'family' => 'Smith'],
  ['given' => 'Bob', 'family' => 'Johnson'],
];

// Format as a list
$formatted = $formatter->formatList($names);
// Result: "John Doe, Jane Smith and Bob Johnson"

// With many names, "et al." is used
$many_names = [
  ['given' => 'John', 'family' => 'Doe'],
  ['given' => 'Jane', 'family' => 'Smith'],
  ['given' => 'Bob', 'family' => 'Johnson'],
  ['given' => 'Alice', 'family' => 'Williams'],
  ['given' => 'Charlie', 'family' => 'Brown'],
];

$formatted = $formatter->formatList($many_names);
// Result: "John Doe, Jane Smith, Bob Johnson, et al"

Method Reference

format()

Formats an array of name components into a display string.

public function format(
  array $components,
  $type = 'default',
  $langcode = NULL
);

Parameters:

  • $components (array) - Name component array with keys:
  • title - Title/honorific (Mr., Dr., etc.)
  • given - Given/first name
  • middle - Middle name(s)
  • family - Family/last name
  • generational - Generational suffix (Jr., Sr., III)
  • credentials - Professional credentials (PhD, MD)
  • preferred - Preferred name (optional)

  • alternative - Alternative name (optional)

  • $type (string) - Name format ID to use. Common formats:

  • 'default' - Default format (configurable)
  • 'full' - Full name with all components
  • 'formal' - Formal format (family, given)
  • 'family' - Family name only
  • 'given' - Given name only

  • 'short_full' - Abbreviated format

  • $langcode (string|null) - Language code for translation

Returns: \Drupal\Component\Render\MarkupInterface - Formatted name

formatList()

Formats multiple name arrays into a grammatically correct list.

public function formatList(
  array $items,
  $type = 'default',
  $list_type = 'default',
  $langcode = NULL
);

Parameters:

  • $items (array) - Array of name component arrays
  • $type (string) - Name format ID for individual names
  • $list_type (string) - List format ID:
  • 'default' - Default list format
  • Custom list formats defined in configuration
  • $langcode (string|null) - Language code for translation

Returns: \Drupal\Component\Render\MarkupInterface - Formatted list

List Formatting Features:

  • Handles 0, 1, or multiple names appropriately
  • Uses commas and conjunctions ("and" or "&")
  • Supports "et al." for long lists
  • Configurable delimiter behavior

setSetting()

Sets a formatter setting value.

public function setSetting($key, $value);

Parameters:

  • $key (string) - Setting name:
  • 'sep1' - Primary separator (default: space)
  • 'sep2' - Secondary separator (default: comma-space)
  • 'sep3' - Tertiary separator
  • 'markup' - Markup type ('none', 'span', etc.)
  • $value (mixed) - Setting value

Returns: NameFormatterInterface - The formatter instance (for chaining)

Example:

$formatter = \Drupal::service('name.formatter');
$formatter->setSetting('sep1', '-')
          ->setSetting('markup', 'span');

$formatted = $formatter->format($name);
// Components are now separated by hyphens instead of spaces

getSetting()

Gets a formatter setting value.

public function getSetting($key);

Parameters:

  • $key (string) - Setting name

Returns: mixed - Setting value or NULL if not found

getLastDelimiterTypes()

Gets available delimiter types for list formatting.

public function getLastDelimiterTypes($include_examples = TRUE);

Returns: array - Delimiter type options: - 'text' - Textual ("and") - 'symbol' - Ampersand ("&") - 'inherit' - Inherit from delimiter

getLastDelimiterBehaviors()

Gets available delimiter behavior options.

public function getLastDelimiterBehaviors($include_examples = TRUE);

Returns: array - Delimiter behavior options: - 'never' - Never use delimiter before conjunction - 'always' - Always use delimiter before conjunction - 'contextual' - Use delimiter based on name count

Name Formats

Available Formats

The module provides several predefined formats:

  • default - Configurable default format
  • full - t g m f s c - All components with spaces
  • formal - f, g m, s, c - Formal format (family, given)
  • family - f - Family name only
  • given - g - Given name only
  • short_full - Abbreviated format

Custom Formats

Custom formats can be defined through the admin UI at: /admin/structure/name

Format tokens: - t - Title - g - Given name - m - Middle name - f - Family name - s - Generational suffix - c - Credentials

Modifiers: - L - Lowercase - F - Formal (family, given order) - + - Preferred name - = - Alternative name

Example: t g m f s c produces "Dr. Jane Marie Smith Jr. PhD"

Dependency Injection

To use the formatter in a service or controller:

namespace Drupal\my_module\Controller;

use Drupal\Core\Controller\ControllerBase;
use Drupal\name\NameFormatterInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

class MyController extends ControllerBase {

  protected $nameFormatter;

  public function __construct(NameFormatterInterface $name_formatter) {
    $this->nameFormatter = $name_formatter;
  }

  public static function create(ContainerInterface $container) {
    return new static(
      $container->get('name.formatter')
    );
  }

  public function displayName($name_data) {
    $formatted = $this->nameFormatter->format($name_data, 'full');
    return ['#markup' => $formatted];
  }
}

See Also