namecase

Personal name capitalization for PHP.

Quick Start · Usage · Options · Development Setup · Documentation · Support

NameCase converts names stored in UPPERCASE or lowercase into conventional capitalization where possible. It handles full names, apostrophes, hyphens, particles such as van and de, Irish Mc and Mac prefixes, Roman numerals, and post-nominal letters such as PhD.

Quick Start

Requires PHP 7.3 or later and the mbstring extension.

Install with Composer:

composer require tamtamchik/namecase

Format a name:

require 'vendor/autoload.php';

use Tamtamchik\NameCase\Formatter;

echo Formatter::nameCase("O'CALLAGHAN");
// O'Callaghan

This README covers version 3.x. For PHP 5, use version 1.0.x and its README.

Usage

Static Calls

use Tamtamchik\NameCase\Formatter;

Formatter::nameCase('KEITH');              // Keith
Formatter::nameCase('LEIGH-WILLIAMS');     // Leigh-Williams
Formatter::nameCase('MCCARTHY');           // McCarthy
Formatter::nameCase("O'CALLAGHAN");        // O'Callaghan
Formatter::nameCase('ST. JOHN');           // St. John
Formatter::nameCase('VON STREIT');         // von Streit
Formatter::nameCase('AP LLWYD DAFYDD');     // ap Llwyd Dafydd
Formatter::nameCase('HENRY VIII');         // Henry VIII
Formatter::nameCase('VAN DYKE');            // van Dyke

Instances and Function Calls

The same formatter is available through an instance or a namespaced function:

use Tamtamchik\NameCase\Formatter;
use function Tamtamchik\NameCase\str_name_case;

$formatter = new Formatter();
$formatter->nameCase('LOUIS XIV'); // Louis XIV

str_name_case('JJ ABRAMS'); // JJ Abrams

Mixed Case

The lazy option defaults to true: names recognized as mixed case are kept as supplied. Set it to false to reformat them:

Formatter::nameCase('Dougal MACDonald');                    // Dougal MACDonald
Formatter::nameCase('Dougal MACDonald', ['lazy' => false]); // Dougal MacDonald
Formatter::setOptions(['lazy' => true]);                    // Restore the default.

Options

Option	Default	Behavior when enabled
`lazy`	`true`	Keep names recognized as mixed case unchanged.
`irish`	`true`	Apply `Mc` and `Mac` capitalization rules and exceptions.
`spanish`	`false`	Keep `El` and `La` capitalized and lowercase the conjunctions `y`, `e`, and `i`.
`roman`	`true`	Uppercase recognized Roman numerals, such as `VIII` and `XIV`.
`hebrew`	`true`	Lowercase `ben` and `bat` between name components.
`postnominal`	`true`	Restore recognized post-nominal letters, such as `PhD` and `CBE`.

Set options through Formatter::setOptions(), the constructor, or the second argument of nameCase() and str_name_case():

Formatter::setOptions(['spanish' => true]);
Formatter::nameCase('RUIZ Y PICASSO'); // Ruiz y Picasso

$formatter = new Formatter(['spanish' => false]);
$formatter->nameCase('EL GRECCO'); // el Grecco

str_name_case('EL PASO', ['spanish' => true]); // El Paso
Formatter::setOptions(['spanish' => false]);

Options are shared static state. Changes through any of these APIs affect subsequent calls and all instances; omitted options retain their current values. An instance does not hold an independent configuration.

Exclude Post-Nominals

Exclude a recognized post-nominal when it is part of a name instead of a title:

Formatter::excludePostNominals('MOst');
Formatter::nameCase('ČERNÝ MOST'); // Černý Most

Pass a string or an array of exact post-nominal spellings. Exclusions accumulate and apply to subsequent calls across all instances.

Development Setup

Install dependencies and run the checks used in CI:

composer install
composer validate --strict
composer tests

CI tests PHP 7.3, 7.4, and 8.0 through 8.5 with mbstring enabled. Run the command-line examples with:

composer demo

Documentation

Website: documentation on GitHub Pages.
Packagist: published versions and installation details.
Formatter: capitalization rules, options, and post-nominal exclusions.
Function: the str_name_case() wrapper.
Tests: names, options, HTML entities, and post-nominals.
Changelog: release history.
CI: Composer validation and test results.

Limitations

Capitalization rules are heuristics. Personal preferences and naming conventions vary, so preserve a person’s supplied spelling when it is known. Options can resolve some ambiguities: for example, disable roman to avoid treating Li as a Roman numeral.

Security

Report vulnerabilities by emailing yuri.tam.tkachenko@gmail.com.

Contributing

See Contributing and the Code of Conduct for guidelines.

Acknowledgements

This library is a port of the Perl library Lingua::EN::NameCase by Mark Summerfield and Barbie. Some solutions come from Aaron Patterson’s Ruby version. Any bugs in the PHP port are my fault.

PHP version: Yuri Tkachenko and all contributors.

Support

License

MIT.