PHPackages                             jsor/string-formatter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. jsor/string-formatter

ActiveLibrary[Localization & i18n](/categories/localization)

jsor/string-formatter
=====================

Localized formatting of personal names, addresses and telephone numbers.

v2.0.0(3y ago)418.7k↓31.3%1MITPHPPHP ^8.0

Since Sep 10Pushed 3y ago1 watchersCompare

[ Source](https://github.com/jsor/string-formatter)[ Packagist](https://packagist.org/packages/jsor/string-formatter)[ RSS](/packages/jsor-string-formatter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (4)Versions (5)Used By (0)

StringFormatter
===============

[](#stringformatter)

Localized formatting of personal names, addresses and telephone numbers.

[![Build Status](https://github.com/jsor/string-formatter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jsor/string-formatter/actions/workflows/ci.yml)[![Coverage Status](https://camo.githubusercontent.com/6d890b495b5833e8435ab3aab34f8628d529d874849a310d60e0438cdf498852/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6a736f722f737472696e672d666f726d61747465722f62616467652e7376673f6272616e63683d6d61696e26736572766963653d676974687562)](https://coveralls.io/github/jsor/string-formatter?branch=main)

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

Installation
------------

[](#installation)

Install the latest version with [Composer](https://getcomposer.org).

```
composer require jsor/string-formatter
```

Check the [Packagist page](https://packagist.org/packages/jsor/string-formatter)for all available versions.

NameFormatter
-------------

[](#nameformatter)

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

```
use Jsor\NameFormatter;

$nameParts = [
    '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([
    'given_name' => 'John',
    'family_name' => 'Doe',
    'salutation' => 'Mr.',
]);
```

The above example will output:

```
Mr. John Doe

```

### Pattern

[](#pattern)

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.

### Values

[](#values)

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`)

License
-------

[](#license)

Copyright (c) 2015-2022 Jan Sorgalla. Released under the [MIT](LICENSE) license.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 98% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~864 days

Total

4

Last Release

1310d ago

Major Versions

v1.1.0 → v2.0.02022-10-17

PHP version history (2 changes)v1.0.0PHP >=5.3.9

v2.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/5de14776bbddf901c6e24d35829fe66fe997c303d53aca83cc7d1a90bb0b7110?d=identicon)[jsor](/maintainers/jsor)

---

Top Contributors

[![jsor](https://avatars.githubusercontent.com/u/55574?v=4)](https://github.com/jsor "jsor (48 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")

---

Tags

intladdresspostali18nstringphoneformatlocaleformattingnamenumbertelephonelocalized

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jsor-string-formatter/health.svg)

```
[![Health](https://phpackages.com/badges/jsor-string-formatter/health.svg)](https://phpackages.com/packages/jsor-string-formatter)
```

###  Alternatives

[symfony/string

Provides an object-oriented API to strings and deals with bytes, UTF-8 code points and grapheme clusters in a unified way

1.8k724.1M827](/packages/symfony-string)[symfony/intl

Provides access to the localization data of the ICU library

2.6k199.8M1.1k](/packages/symfony-intl)[jackocnr/intl-tel-input

A JavaScript plugin for entering and validating international telephone numbers

8.2k243.6k2](/packages/jackocnr-intl-tel-input)[fightbulc/moment

Parse, validate, manipulate, and display dates in PHP w/ i18n support. Inspired by moment.js

9693.2M10](/packages/fightbulc-moment)[skillshare/formatphp

Internationalize PHP apps. This library provides an API to format dates, numbers, and strings, including pluralization and handling translations.

8029.6k](/packages/skillshare-formatphp)[commerceguys/addressing

Addressing library powered by CLDR and Google's address data.

95630.2M43](/packages/commerceguys-addressing)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)