lakm/person-name

Format personal names in various styles-full, abbreviated, familiar, etc. based on country specific conventions

dev-main 2025-09-03 05:43 UTC

Requires

• php: ^8.3

Requires (Dev)

• larapack/dd: ^1.1
• laravel/pint: ^1.24
• pestphp/pest: ^3.8
• phpstan/phpstan: ^2.1
• rector/rector: ^2.1

MIT

• Lakshan Madushanka

README

Overview | Insight | Motive | Features | Usage | API | Abbreviator | Changelog | Testing | Security | License

This package globally handle person names in various formats.

Overview

This package maps names from various countries to a standard format [prefix + first + middle + last + suffix] and provides multiple country|ethnicity specific formats and features.

Insight

Problem

• A company decided to automate their business by developing a website. The database has a users table with normalized name fields (first_name, middle_name, last_name).

  However, legacy Excel sheets contain a single column with users' full names. This wasn’t a problem for the legacy system, as everything was handled manually and humans are generally good with full names.

  Now, the company wants to import the legacy data into the new system. They need to split full names into first, middle, and last names.

  If this sounds like an easy task, take a moment and think about it seriously. One solution is to hire someone to do it manually but the accuracy cannot be fully guaranteed. Another option is to automate the task using AI or custom logic but that will cost time and money and still may not be perfectly accurate.

  You’ll agree that neither method is smooth or reliable, especially when the client list contains names from different countries.

  This is where this package comes in handy. With this package, all you need to do is the following:

  $n = PersonName::fromFullName($fullName, $country);
  
  $firstName = $n->first();
  $middleName = $n->middle();
  $lastName = $n->last();

• Your database has a users table with a full_name field. This is not an ideal database design, but it exists. Now you need to extract the individual name parts.

• The front-end requires names in different formats: the UI needs short names, forms need names in a standard format, and security related features may require redacted names. Similarly, names may be needed in abbreviated, sorted, or other variations. This package handles all these cases as comprehensively as possible.

Motive

I've faced the problems described above and always needed a solid solution, which I still couldn't find. Recently, I came across this package and thought, this is what I’ve been waiting for so long. But when I dug into it, I realized it couldn’t fulfill my expectations. It handles simple cases but not complex scenarios.

So, I decided to stop waiting and develop a solution myself. I must give credit to this package, as it ignited the spark.

Features

• 🏁 Handle Country specific names
• 🛠️ Build names from full names
• 🛠️ Build names from parts (constructor)
• ⚙️ Handle particles, prefixes, suffixes (western)
• 🛡️ Universal - Multibyte safe
• 🤖 Auto sanitize names
• ✅ Validity check
• ●●● Name Abbreviations
  • FirstInitial_LastName**
  • FirstInitial_MiddleInitial_LastName
  • FirstName_LastInitial
  • FirstName_MiddleInitial_LastName
  • Initials
• 📝 Various Format options
  • Sorted
  • Possessive
  • Redated
  • Family|sur|last
  • etc
• 🧩 Country|Ethnicity specific features
• 📔 Comprehensive test cases with >85% coverage
• 💡 Elegant architecture
• 🦢 Pure PHP - can use anywhere frameworks, lib etc.

Supported Countries|Ethnicities

Note

See Countries and Ethnicities

Name	Code	Status
Western - Default (This is used when the country field null)	-	✅
SRI_LANKA	LK	✅
CHINA	CN	✅
RUSSIA	RU	✅
Arab	-	✅

Usage

Build from full name

\Lakm\PersonName\PersonName::fromFullName(
    string $fullName, 
    Country|Ethnicity|null $country = null, 
    bool $shouldSanitize = true, 
    bool $checkValidity = false
    )

Build from constructor

\Lakm\PersonName\PersonName::build(
    string $firstName,
    ?string $middleName = null,
    ?string $lastName = null,
    ?string $suffix = null,
    ?string $prefix = null,
    Country|Ethnicity|null $country = null,
    bool $shouldSanitize = true,
    bool $checkValidity = false
)

Abbreviator

The package provides smart abbreviation formats with multiple options. This feature is also integrated into PersonName Object.

\Lakm\PersonName\Abbreviator\Abbreviator::execute(
    string $firstName,
    ?string $middleName = null,
    ?string $lastName = null,
    ?string $prefix = null,
    ?string $suffix = null,
    bool    $withDot = true,
    bool    $strict = false,
    bool    $removeParticles = false,
    Abbreviate $format = Abbreviate::FirstInitial_LastName,
)

Available format ($format) options

All supported Abbreviate enum cases are available in Abbreviate enum class

• \Lakm\PersonName\Enums\Abbreviate::FirstInitial_LastName
• \Lakm\PersonName\Enums\Abbreviate::FirstInitial_MiddleInitial_LastName
• \Lakm\PersonName\Enums\Abbreviate::FirstName_LastInitial
• \Lakm\PersonName\Enums\Abbreviate::FirstName_MiddleInitial_LastName
• \Lakm\PersonName\Enums\Abbreviate::Initials

Common API

Important

The Package provides a range of methods and following documentation only contins most common ones. See NameBuilderContract for all the available options.

Basic

static checkValidity(string $name)

Check the validity of a name

use \Lakm\PersonName\PersonName;

PersonName::checkValidity('John Doe'); // true
PersonName::checkValidity('John123'); // false
PersonName::checkValidity('John#'); // false

first(): string

Returns the first name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->first() // Maria

middle(): string

Returns the middle name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->middle() // Anna

last(): string

Returns the last name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->last() // de la Vega

sorted(): ?string

Returns sorted name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->sorted() // de la Vega, Maria Anna

possessive(?string $name = null): string

Returns the possessive name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->possessive() // Maria's

prefix(): ?string

Returns the prefixes

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->prefix() // Prof. Dr.

suffix(): ?string

Returns the suffixes

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->suffix() // III PhD

honours(): string[]

Returns the honours

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->honours() // ['Dr.', 'Prof.', 'PhD']

redated(int $length = 8, int $keep = 3, string $mask = '*'): string

Returns securely redated first name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->redated() // Mar*****

mentionable(): string

Returns the mentionable name

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->mentionable() // @maria

nick(int $length = 4): string

Returns the nickname

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->nick() // mary

Abbreviations

Refer here for separate usage.

abbreviated(bool $includePrefix = false,bool $includeSuffix = false, bool $withDot = true, bool $strict = false, bool $removeParticles = false, Abbreviate $format = Abbreviate::Initials): string

Refer here for available formats ($format)

use \Lakm\PersonName\PersonName;

PersonName::fromFullName('Prof. Dr. Maria Anna de la Vega III PhD')->abbreviated() // M. A. d. l. V.

Country specific functions

The package offers country specific methods, available in the classes(each named using the country code) under NameBuilders.

Arab

• fatherName(): ?string
• grandfatherName(): ?string
• kunya(): ?string
• ism(): ?string
• nasab(): ?string
• laqab(): ?string
• nisbah(): ?string

Testing

./vendor/bin/pest

Changelog

Please see CHANGELOG for more information what has changed recently.

Security

Please see here for our security policy.

License

The MIT License (MIT). Please see License File for more information.

Credits

• Name of Person