PHPackages                             hosmelq/name-of-person - 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. [Utility & Helpers](/categories/utility)
4. /
5. hosmelq/name-of-person

ActiveLibrary[Utility & Helpers](/categories/utility)

hosmelq/name-of-person
======================

Presenting names of people in full, familiar, abbreviated, and initialized forms

v0.3.0(11mo ago)11236.1k↓63.6%2[2 issues](https://github.com/hosmelq/name-of-person/issues)[2 PRs](https://github.com/hosmelq/name-of-person/pulls)MITPHPPHP ^8.2CI passing

Since Jul 1Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/hosmelq/name-of-person)[ Packagist](https://packagist.org/packages/hosmelq/name-of-person)[ RSS](/packages/hosmelq-name-of-person/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (3)Dependencies (16)Versions (6)Used By (0)

Name of Person
==============

[](#name-of-person)

> Inspired by Basecamp's [name\_of\_person](https://github.com/basecamp/name_of_person) Ruby gem, but built for modern PHP applications.

Introduction
------------

[](#introduction)

Handle person names in your PHP applications with elegant formatting options. Transform names between multiple presentation formats. This package provides a clean, type-safe way to parse, store, manipulate, and display person names consistently across your application.

**Key Features:**

- 🎯 **Multiple Format Options**: nine different ways to display names (full, familiar, abbreviated, initials, sorted, possessive, mentionable)
- 🎨 **Smart Parsing**: Intelligently handles full name strings and edge cases
- 🌍 **Unicode Support**: Full international name support with proper multibyte handling
- 🔧 **Pure PHP**: Core functionality works in any PHP project
- ⚡ **Laravel Integration**: Native Eloquent casting for seamless database integration

Requirements
------------

[](#requirements)

This package requires PHP 8.2 or higher. Laravel integration requires Laravel 11 or higher.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require hosmelq/name-of-person
```

Basic Usage
-----------

[](#basic-usage)

### Creating PersonName Objects

[](#creating-personname-objects)

The core `PersonName` class works in any PHP application:

```
use HosmelQ\NameOfPerson\PersonName;

// Direct instantiation with first and last name.
$name = new PersonName('David', 'Heinemeier Hansson');

// From full name strings.
$parsed = PersonName::fromFull('Jason Fried');

echo $parsed->first; // "Jason"
echo $parsed->last;  // "Fried"

// Handles single names.
$single = PersonName::fromFull('Cher');

echo $single->first; // "Cher"
echo $single->last;  // null
```

### Available Methods

[](#available-methods)

#### Basic Properties

[](#basic-properties)

##### `first` (readonly property)

[](#first-readonly-property)

Returns the first name as a string.

```
$name = new PersonName('David', 'Heinemeier Hansson');

echo $name->first; // "David"
```

##### `last` (readonly property)

[](#last-readonly-property)

Returns the last name as a string, or `null` if no last name was provided.

```
$name = new PersonName('David', 'Heinemeier Hansson');

echo $name->last; // "Heinemeier Hansson"

$single = PersonName::fromFull('Cher');

echo $single->last; // null
```

#### Display Methods

[](#display-methods)

```
$name = new PersonName('David', 'Heinemeier Hansson');

$single = PersonName::fromFull('Cher');
```

##### `abbreviated()`

[](#abbreviated)

Returns the first initial plus full last name: "F. Last"

```
echo $name->abbreviated();   // "D. Heinemeier Hansson"
echo $single->abbreviated(); // "Cher"
```

##### `familiar()`

[](#familiar)

Returns the first name plus last initial with a period: "First L."

```
echo $name->familiar();   // "David H."
echo $single->familiar(); // "Cher"
```

##### `full()`

[](#full)

Returns the complete name in "First Last" format.

```
echo $name->full(); // "David Heinemeier Hansson"
```

##### `initials()`

[](#initials)

Returns all initials from the name, excluding parentheses and brackets.

```
echo $name->initials(); // "DHH"

$complex = new PersonName('Mary Jane', 'Watson');

echo $complex->initials(); // "MJW"
```

##### `mentionable()`

[](#mentionable)

Returns lowercase, space-free version of the familiar name for mentions.

```
echo $name->mentionable();   // "davidh"
echo $single->mentionable(); // "cher"
```

##### `possessive()`

[](#possessive)

Returns the possessive form of the name with appropriate apostrophe placement.

```
echo $name->possessive(); // "David Heinemeier Hansson's"

$james = new PersonName('James', null);

echo $james->possessive(); // "James'"
```

You can also specify which format to make possessive:

```
echo $name->possessive('first');       // "David's"
echo $name->possessive('familiar');    // "David H.'s"
echo $name->possessive('abbreviated'); // "D. Heinemeier Hansson's"
echo $name->possessive('initials');    // "DHH's"
echo $name->possessive('sorted');      // "Heinemeier Hansson, David's"
```

##### `sorted()`

[](#sorted)

Returns the name in "Last, First" format suitable for sorting.

```
echo $name->sorted();   // "Heinemeier Hansson, David"
echo $single->sorted(); // "Cher"
```

#### Utility Methods

[](#utility-methods)

##### `equals()`

[](#equals)

Compares two PersonName objects for equality.

```
$name1 = new PersonName('David', 'Heinemeier Hansson');
$name2 = new PersonName('David', 'Heinemeier Hansson');
$name3 = new PersonName('Jason', 'Fried');

echo $name1->equals($name2); // true
echo $name1->equals($name3); // false
```

#### String and JSON Conversion

[](#string-and-json-conversion)

PersonName implements both `Stringable` and `JsonSerializable` interfaces:

```
$name = new PersonName('David', 'Heinemeier Hansson');

// String conversion returns full name
echo (string) $name; // "David Heinemeier Hansson"

// JSON serialization returns full name
echo json_encode($name); // "David Heinemeier Hansson"
```

> **Performance Note**: All computed properties (familiar, abbreviated, sorted, etc.) are cached for performance. The first call computes the value, later calls return the cached result.

### Error Handling

[](#error-handling)

The package throws `InvalidArgumentException` in these cases:

```
// Empty first name
new PersonName(''); // throws InvalidArgumentException

// Invalid possessive method
$name->possessive('invalid'); // throws InvalidArgumentException
```

### Unicode Support

[](#unicode-support)

The package fully supports international names:

```
$name = new PersonName('José', 'García');

echo $name->familiar(); // "José G."
```

Laravel Integration
-------------------

[](#laravel-integration)

When using Laravel, you can leverage the included cast for seamless Eloquent integration:

### Configuration

[](#configuration)

The package works out of the box with Laravel's casting system. By default, it expects `first_name` and `last_name` columns in your database, but you can customize this:

```
use HosmelQ\NameOfPerson\PersonNameCast;

// Default configuration - uses first_name and last_name columns
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::class,
        ];
    }
}

// Custom column names
class BlogPost extends Model
{
    protected function casts(): array
    {
        return [
            'author_name' => PersonNameCast::class.':author_first,author_last',
        ];
    }
}
```

Alternatively, you can use the fluent helper method:

```
class BlogPost extends Model
{
    protected function casts(): array
    {
        return [
            'author_name' => PersonNameCast::using('author_first', 'author_last'),
        ];
    }
}
```

#### Usage Examples

[](#usage-examples)

#### Basic Usage

[](#basic-usage-1)

```
$user = new User();

$user->name = 'David Heinemeier Hansson';

echo $user->name->familiar(); // "David H."
```

#### JSON Serialization

[](#json-serialization)

```
$user = User::find(1);

return response()->json([
    'user' => $user->name, // "David Heinemeier Hansson"
]);
```

Testing
-------

[](#testing)

```
composer test
```

Credits
-------

[](#credits)

- [Hosmel Quintana](https://github.com/hosmelq)
- Inspired by [Basecamp's name\_of\_person](https://github.com/basecamp/name_of_person) Ruby gem
- All Contributors

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance57

Moderate activity, may be stable

Popularity43

Moderate usage in the ecosystem

Community11

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

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

Every ~4 days

Total

3

Last Release

357d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/97fd048037c6d5ccfeebf11961838d5db2dca1baca14fefa373230b301389a03?d=identicon)[hosmelq](/maintainers/hosmelq)

---

Top Contributors

[![hosmelq](https://avatars.githubusercontent.com/u/1166143?v=4)](https://github.com/hosmelq "hosmelq (4 commits)")[![1ohnny](https://avatars.githubusercontent.com/u/56255026?v=4)](https://github.com/1ohnny "1ohnny (1 commits)")

---

Tags

laravelphplaravelPersonnamehosmelqname-of-person

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[grumpydictator/firefly-iii

Firefly III: a personal finances manager.

23.9k69.5k](/packages/grumpydictator-firefly-iii)[firefly-iii/data-importer

Firefly III Data Import Tool.

8035.8k](/packages/firefly-iii-data-importer)[thenextweb/passgenerator

A Laravel package to create Apple Wallet (old Passbook) compatible tickets.

302478.1k](/packages/thenextweb-passgenerator)[keepsuit/laravel-opentelemetry

OpenTelemetry integration for laravel

167558.4k1](/packages/keepsuit-laravel-opentelemetry)[hosmelq/laravel-pulse-schedule

Laravel Pulse card that list all scheduled tasks.

63519.7k](/packages/hosmelq-laravel-pulse-schedule)[byte5/laravel-passgenerator

A Laravel package to create Apple Wallet (old Passbook) compatible tickets.

9239.0k](/packages/byte5-laravel-passgenerator)

PHPackages © 2026

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