---

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

---

This package globally extract and handle person names in various formats.

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.

• 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.

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.

• 🏁 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.

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

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

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

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

Check the validity of a name

use \Lakm\PersonName\PersonName;

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

Returns the first name

use \Lakm\PersonName\PersonName;

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

Returns the middle name

use \Lakm\PersonName\PersonName;

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

Returns the last name

use \Lakm\PersonName\PersonName;

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

Returns sorted name

use \Lakm\PersonName\PersonName;

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

Returns the possessive name

use \Lakm\PersonName\PersonName;

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

Returns the prefixes

use \Lakm\PersonName\PersonName;

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

Returns the suffixes

use \Lakm\PersonName\PersonName;

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

Returns the honours

use \Lakm\PersonName\PersonName;

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

Returns securely redated first name

use \Lakm\PersonName\PersonName;

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

Returns the mentionable name

use \Lakm\PersonName\PersonName;

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

Returns the nickname

use \Lakm\PersonName\PersonName;

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

Refer here for separate usage.

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.

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

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

./vendor/bin/pest

Please see CHANGELOG for more information what has changed recently.

Please see here for our security policy.

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

• Name of Person