Localized formatting of personal names, addresses and telephone numbers.

v1.1.0 2018-08-31 13:36 UTC

This package is auto-updated.

Last update: 2020-08-06 12:27:54 UTC


Localized formatting of personal names, addresses and telephone numbers.

Build Status Coverage Status

Note: At the moment, only a NameFormatter is available. Address and telephone formatters will follow.


Install the latest version with Composer.

composer require jsor/string-formatter

Check the Packagist page for all available versions.


The NameFormatter formats the appropriate representation of a person’s name for a locale by the given name parts.

use Jsor\NameFormatter;

$nameParts = array(
    'given_name' => 'John',
    'family_name' => 'Doe',
    'salutation' => 2 // name_mr

$enUsFormatter = new NameFormatter('en_US');
echo $enUsFormatter->format($nameParts)."\n";

$deDeFormatter = new NameFormatter('de_DE');
echo $deDeFormatter->format($nameParts)."\n";

$zhCnFormatter = new NameFormatter('zh_CN');
echo $zhCnFormatter->format($nameParts)."\n";

The above example will output:

Mr. John Doe
Herr John Doe
Doe John 先生

A custom pattern can be passed as the second argument to the constructor.

use Jsor\NameFormatter;

$formatter = new NameFormatter('en_US', '%d%t%g%t%m%t%f');
echo $formatter->format(array(
    'given_name' => 'John',
    'family_name' => 'Doe',
    'salutation' => 'Mr.',

The above example will output:

Mr. John Doe


The pattern argument can contain any combination of characters and field descriptors.

The following field descriptor are supported.

  • %f Family names.
  • %F Family names in uppercase.
  • %g First given name.
  • %G First given initial.
  • %l First given name with latin letters. In some cultures, eg on Taiwan it is customary to also have a first name written with Latin letters, although the rest of the name is written in another script.
  • %o Other shorter name, eg. "Bill".
  • %m Additional given names.
  • %M Initials for additional given names.
  • %p Profession.
  • %d Salutation, supporting the FDCC-sets conventions, with 1 for name_gen, 2 for name_mr, 3 for name_mrs, 4 for name_miss, 5 for name_ms.
  • %s Full Salutation, such as "Doctor".
  • %S Abbreviated salutation, such as "Mr." or "Dr."
  • %t If the preceding field descriptor resulted in an empty string, then the empty string, else a space.


The array argument passed to format() can define a value for each field descriptor. The keys can be either the descriptor character or a named key.

The following keys are supported.

  • family_name, family_names or f (for %f)
  • family_name_in_uppercase, family_names_in_uppercase or F (for %F)
  • given_name, given_names or g (for %g)
  • given_initial, given_initials or G (for %G)
  • given_name_with_latin_letters, given_names_with_latin_letters or l (for %l)
  • other_shorter_name, other_shorter_names or o (for %o)
  • additional_given_name, additional_given_names or m (for %m)
  • initials_for_additional_given_name, initials_for_additional_given_names or M (for %M)
  • profession, professions or p (for %p)
  • salutation, salutations or d (for %d)
  • full_salutation, full_salutations or s (for %s)
  • abbreviated_salutation, abbreviated_salutations or S (for %S)


Copyright (c) 2015-2019 Jan Sorgalla. Released under the MIT license.