Name Format Parser Service¶

Overview¶

The Name Format Parser service (name.format_parser) converts name component arrays into formatted strings based on format patterns. This service is used internally by the Name Formatter service and should rarely be called directly.

Service ID: name.format_parser
Class: Drupal\name\NameFormatParser

Note

For most use cases, use the Name Formatter Service instead, which provides a higher-level API.

Basic Usage¶

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

$name_components = [
  'title' => 'Dr.',
  'given' => 'Jane',
  'middle' => 'Marie',
  'family' => 'Smith',
  'credentials' => 'PhD',
];

// Parse with a format string
$settings = [
  'sep1' => ' ',
  'sep2' => ', ',
  'markup' => 'none',
];

$formatted = $parser->parse($name_components, 't g m f c', $settings);
// Result: "Dr. Jane Marie Smith PhD"

Method Reference¶

parse()¶

Parses a name component array into the given format.

public function parse(
  array $name_components, 
  $format = '', 
  array $settings = []
);

Parameters:

$name_components (array) - Keyed array of name components
$format (string) - Format pattern string using component tokens
$settings (array) - Parser settings:
sep1 (string) - First separator (default: space)
sep2 (string) - Second separator (default: comma-space)
sep3 (string) - Third separator (default: empty)
markup (string) - Markup type:
- 'none' - Plain text with HTML escaping
- 'simple' - Simple HTML markup
- 'rdfa' - RDFa markup
- 'microdata' - Microdata markup
- 'raw' - No escaping

Returns: string - Formatted name

Format Pattern Syntax¶

Component Tokens¶

Token	Component	Description
`t`	title	Title/honorific
`g`	given	Given/first name
`m`	middle	Middle name(s)
`f`	family	Family/last name
`c`	credentials	Credentials
`s`	generational	Generational suffix

Modifiers¶

Modifiers can be applied to tokens to change their behavior:

Modifier	Effect	Example
`L`	Lowercase	`Lg` = "jane"
`U`	Uppercase	`Ug` = "JANE"
`F`	Uppercase first letter	`Fg` = "Jane"
`T`	Uppercase first letter of each word	`Tm` = "Marie Ann"
`S`	Uppercase first letter, lowercase rest	`Sg` = "Jane"
`i`	Initial only	`ig` = "J"
`+`	Preferred name	`g+` uses preferred if available
`=`	Alternative name	`g=` uses alternative if available

Separator Control¶

Three separator types control spacing:

Separator 1 (sep1) - Default: space (" ")
Used between adjacent components
Separator 2 (sep2) - Default: comma-space (", ")
Used with certain format combinations
Separator 3 (sep3) - Default: empty ("")
Additional separator control

Conditional Separators¶

Separators only appear when both adjacent components have values:

// Format: "t g f"
// Input: ['given' => 'Jane', 'family' => 'Smith']
// Output: "Jane Smith" (no extra space for missing title)

// Input: ['title' => 'Dr.', 'given' => 'Jane', 'family' => 'Smith']
// Output: "Dr. Jane Smith"

Format Examples¶

Standard Formats¶

// Full name
$parser->parse($name, 't g m f s c', $settings);
// "Dr. Jane Marie Smith Jr. PhD"

// Formal (family, given)
$parser->parse($name, 'f, g m, s, c', $settings);
// "Smith, Jane Marie, Jr., PhD"

// Family name only
$parser->parse($name, 'f', $settings);
// "Smith"

// Given name only
$parser->parse($name, 'g', $settings);
// "Jane"

// Short full (with initials)
$parser->parse($name, 't ig. im. f', $settings);
// "Dr. J. M. Smith"

With Modifiers¶

// Uppercase family name
$parser->parse($name, 't g Uf', $settings);
// "Dr. Jane SMITH"

// Lowercase given name
$parser->parse($name, 't Lg f', $settings);
// "Dr. jane Smith"

// Initial of given name
$parser->parse($name, 't ig. f', $settings);
// "Dr. J. Smith"

Markup Types¶

Plain Text ('none')¶

$settings = ['markup' => 'none'];
$result = $parser->parse($name, 't g f', $settings);
// HTML entities are escaped

Simple HTML ('simple')¶

$settings = ['markup' => 'simple'];
$result = $parser->parse($name, 't g f', $settings);
// Components wrapped in <span> elements

RDFa ('rdfa')¶

$settings = ['markup' => 'rdfa'];
$result = $parser->parse($name, 't g f', $settings);
// RDFa attributes added for semantic markup

Microdata ('microdata')¶

$settings = ['markup' => 'microdata'];
$result = $parser->parse($name, 't g f', $settings);
// Microdata attributes added for structured data

Internal Use¶

The parser is primarily used internally by the Name Formatter service:

// NameFormatter::format() internally calls:
$format_string = $this->getNameFormatString($type);
$name = $this->parser->parse($components, $format_string, $this->settings);