PHPackages                             lakm/person-name - 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. lakm/person-name

ActiveLibrary

lakm/person-name
================

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

1.0.0(8mo ago)27559—0%MITPHPPHP ^8.3CI failing

Since Sep 8Pushed 8mo agoCompare

[ Source](https://github.com/Lak-M/person-name)[ Packagist](https://packagist.org/packages/lakm/person-name)[ GitHub Sponsors](https://github.com/Lakshan-Madushanka)[ RSS](/packages/lakm-person-name/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (0)

[![Image](https://private-user-images.githubusercontent.com/47297673/483471700-6371ad23-cdb2-4a7b-9975-e0c5525f8953.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzNzExMTUsIm5iZiI6MTc3NTM3MDgxNSwicGF0aCI6Ii80NzI5NzY3My80ODM0NzE3MDAtNjM3MWFkMjMtY2RiMi00YTdiLTk5NzUtZTBjNTUyNWY4OTUzLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA1VDA2MzMzNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWYzMmRiMjVmY2VlMjg4NDYwNDRjYzRiZDMyMmJjZjgzMWU0YjJkN2NlOTg3MzVkZGM4YTZhZDY4ZDliMjY2NDUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.cIjhcVGMj-vPBKuoqkDZ1fsivjXOlUUiSLdYMymSYKU)](https://private-user-images.githubusercontent.com/47297673/483471700-6371ad23-cdb2-4a7b-9975-e0c5525f8953.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzNzExMTUsIm5iZiI6MTc3NTM3MDgxNSwicGF0aCI6Ii80NzI5NzY3My80ODM0NzE3MDAtNjM3MWFkMjMtY2RiMi00YTdiLTk5NzUtZTBjNTUyNWY4OTUzLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA1VDA2MzMzNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWYzMmRiMjVmY2VlMjg4NDYwNDRjYzRiZDMyMmJjZjgzMWU0YjJkN2NlOTg3MzVkZGM4YTZhZDY4ZDliMjY2NDUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.cIjhcVGMj-vPBKuoqkDZ1fsivjXOlUUiSLdYMymSYKU)---

**[Overview](#overview)** | **[Insight](#insight)** | **[Motive](#motive)** | **Live** | **[Features](#features)** | **[Usage](#usage)** | **[API](#common-api)** | **[Abbreviator](#abbreviator)** | **[Changelog](#changelog)** | **[Testing](#testing)** | **[Security](#security)** | **[License](#license)**

---

[![Image](https://private-user-images.githubusercontent.com/47297673/483465821-ef6088e7-4de5-45c2-b804-0c46b27c918e.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzNzExMTUsIm5iZiI6MTc3NTM3MDgxNSwicGF0aCI6Ii80NzI5NzY3My80ODM0NjU4MjEtZWY2MDg4ZTctNGRlNS00NWMyLWI4MDQtMGM0NmIyN2M5MThlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA1VDA2MzMzNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTBjMWY5NDJlODcwMzllZWVhYjI1MzRkMzhlY2Q0NGRlNDk5ZjJhMmQ3MGQ2N2E2Y2E4ZmIwMmI5ZWViOGFmNzQmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.HRNFq5UVnrnvjZAc6r8q97EiglPxri77LnkBZnA8DDA)](https://private-user-images.githubusercontent.com/47297673/483465821-ef6088e7-4de5-45c2-b804-0c46b27c918e.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUzNzExMTUsIm5iZiI6MTc3NTM3MDgxNSwicGF0aCI6Ii80NzI5NzY3My80ODM0NjU4MjEtZWY2MDg4ZTctNGRlNS00NWMyLWI4MDQtMGM0NmIyN2M5MThlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA0MDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNDA1VDA2MzMzNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTBjMWY5NDJlODcwMzllZWVhYjI1MzRkMzhlY2Q0NGRlNDk5ZjJhMmQ3MGQ2N2E2Y2E4ZmIwMmI5ZWViOGFmNzQmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.HRNFq5UVnrnvjZAc6r8q97EiglPxri77LnkBZnA8DDA)### ***This package globally extract and handle person names in various formats.***

[](#this-package-globally-extract-and-handle-person-names-in-various-formats)

[![PHP](https://camo.githubusercontent.com/c40fef253e131664594f05771d0afd1758f72ed5d40d8df2c6f0030fc49ba5ac/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253230253545382e332d626c7565)](https://php.net)[![GitHub Actions Workflow Status](https://camo.githubusercontent.com/43435748b14ad84f8205a687845a506c523e9c21adcb55f760a66278919c5a42/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4c616b2d4d2f706572736f6e2d6e616d652f72756e2d74657374732e796d6c3f6c6162656c3d54657374)](https://github.com/Lak-M/person-name/actions?query=workflow%3ATests+branch%3Amain)[![Packagist Version](https://camo.githubusercontent.com/1771347c2c2a79f7592134780ad74c6158c0d79b576e41c28a107e995e6a8b96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c616b6d2f706572736f6e2d6e616d65)](https://packagist.org/packages/lakm/person-name)[![Downloads](https://camo.githubusercontent.com/ba07398de6d5a5ba722e754c44c8cbdf6930af49facdc4bb98cc079646d95a57/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c616b6d2f706572736f6e2d6e616d65)](https://packagist.org/packages/lakm/person-name)[![GitHub License](https://camo.githubusercontent.com/448dbb7b0a33b3e47cb388e3b263dc7f6ec29e83b9f486f5d1a196cb53004048/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4c616b2d4d2f706572736f6e2d6e616d65)](https://github.com/Lak-M/person-name/blob/main/LICENSE.md)

Overview
--------

[](#overview)

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

Important

I' am not claiming this is the best solution though I did my best. Practically it is quite impossible to cover all the cases but we can cover whatever the possible use cases. With your feedback and support we can make this better. You can try it in .

Insight
-------

[](#insight)

### Problem

[](#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
------

[](#motive)

I've faced the problems described [above](#problem) and always needed a solid solution, which I still couldn't find. Recently, I came across this [package](https://github.com/hosmelq/name-of-person) 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
--------

[](#features)

- 🏁 Handle **Country|Ethnicity 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
-------------------------------

[](#supported-countriesethnicities)

Note

See [Countries](https://github.com/Lak-M/person-name/blob/main/src/Enums/Country.php) and [Ethnicities](https://github.com/Lak-M/person-name/blob/main/src/Enums/Ethnicity.php)

NameCodeStatusWestern - Default (This is used when the country field null)-✅SRI\_LANKALK✅CHINACN✅RUSSIARU✅Arab-✅Usage
-----

[](#usage)

### Build from full name

[](#build-from-full-name)

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

### Build from constructor

[](#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

[](#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

[](#available-format-format-options)

All supported `Abbreviate` enum cases are available in [Abbreviate enum class](https://github.com/Lak-M/person-name/blob/main/src/Enums/Abbreviate.php)

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

[](#common-api)

Important

The Package provides a range of methods and following documentation only contins most common ones. See [NameBuilderContract](https://github.com/Lak-M/person-name/blob/main/src/Contracts/NameBuilderContract.php) for all the available options.

#### Basic

[](#basic)

##### static checkValidity(string $name)

[](#static-checkvaliditystring-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

[](#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

[](#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

[](#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

[](#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

[](#possessivestring-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

[](#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

[](#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\[\]

[](#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

[](#redatedint-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

[](#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

[](#nickint-length--4-string)

Returns the nickname

```
use \Lakm\PersonName\PersonName;

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

#### Abbreviations

[](#abbreviations)

Refer [here](#abbreviator) for separate usage.

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

[](#abbreviatedbool-includeprefix--falsebool-includesuffix--false-bool-withdot--true-bool-strict--false-bool-removeparticles--false-abbreviate-format--abbreviateinitials-string)

Refer [here](#available-format-format-options) 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

[](#country-specific-functions)

The package offers country specific methods, available in the classes(each named using the country code) under [`NameBuilders`](https://github.com/Lak-M/person-name/tree/main/src/NameBuilders).

##### Arab

[](#arab)

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

Testing
-------

[](#testing)

```
./vendor/bin/pest
```

Changelog
---------

[](#changelog)

Please see CHANGELOG for more information what has changed recently.

Security
--------

[](#security)

Please see [here](https://github.com/Lak-M/person-name/blob/main/SECURITY.md) for our security policy.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](https://github.com/Lak-M/person-name/blob/main/LICENSE.md) for more information.

Credits
-------

[](#credits)

- [Name of Person](https://github.com/hosmelq/name-of-person)

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance60

Regular maintenance activity

Popularity27

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

252d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/88cfad5d6377be18e9544dc9796e4dd2979faeff1984ad105f83bc979ac25c0f?d=identicon)[Lakshan-Madushanka](/maintainers/Lakshan-Madushanka)

---

Top Contributors

[![Lakshan-Madushanka](https://avatars.githubusercontent.com/u/47297673?v=4)](https://github.com/Lakshan-Madushanka "Lakshan-Madushanka (77 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lakm-person-name/health.svg)

```
[![Health](https://phpackages.com/badges/lakm-person-name/health.svg)](https://phpackages.com/packages/lakm-person-name)
```

PHPackages © 2026

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