tamtamchik / namecase

3.1.0 2026-07-05 23:53 UTC

Requires

• php: >=7.3
• ext-mbstring: *

Requires (Dev)

• phpunit/phpunit: ^9
• scrutinizer/ocular: ^1

MIT

• Yuri Tkachenko

• strings
• tamtamchik
• namecase
• properly
• cased

Published on Packagist.org on 2026-07-05 23:54 UTC

README

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 [e-mail].

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.

• Perl version: copyright Mark Summerfield 1998–2014 and Barbie 2014–2019.
• Ruby version: copyright Aaron Patterson 2006.
• PHP version: Yuri Tkachenko and all contributors.

Support

License

MIT.