watson/nameable

Format names of users into full, familiar and abbreviated forms

3.0.0 2024-08-21 10:32 UTC

This package is auto-updated.

Last update: 2024-10-21 11:04:24 UTC


README

Latest Version on Packagist Build Status Total Downloads

This package provides a caster and a formatter class for presenting your user's names. It can get a user's first, last or full name, their initials, and common abbreviations. Instead of separating the fields over a few database columns you can store a user's name in a single column and fetch what you need.

This package is based upon Basecamp's name_of_person package for Ruby/Rails.

Installation

You can install the package via Composer:

composer require watson/nameable

Then use the Nameable cast for any Eloquent models you want to use as a name.

use Watson\Nameable\Nameable;

class User extends Model
{
    protected $casts = [
        'name' => Nameable::class,
    ];
}

Alternatively, you can interact with the Name class directly.

use Watson\Nameable\Name;

$name = new Name('Dwight', 'Conrad Watson');

$name = Name::from('Dwight Conrad Watson');

Usage

$user = new User(['name' => 'Dwight Watson']);

$user->name->full        // Dwight Watson
$user->name->first       // Dwight
$user->name->last        // Watson
$user->name->familiar    // Dwight W. 
$user->name->abbreviated // D. Watson
$user->name->sorted      // Watson, Dwight
$user->name->initials    // DW

In addition there are possessive variants you can use which will work correctly with names that end in s.

$user = new User(['name' => 'Dwight Watson']);

$user->name->full_possessive        // Dwight Watson's
$user->name->first_possessive       // Dwight's
$user->name->last_possessive        // Watson's
$user->name->abbreviated_possessive // D. Watson's
$user->name->sorted_possessive      // Watson, Dwight's
$user->name->initials_possessive    // DW's

$user = new User(['name' => 'Angus Young']);
$user->name->full_possessive        // Angus Young's
$user->name->first_possessive       // Angus'

If a user doesn't provide a full name (for example, just a first name) the attributes will just omit the last name.

License

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