### Install Name of Person Package

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Install the package using Composer. Ensure you are using PHP 8.2 or higher.

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

--------------------------------

### Default Setup for Name Columns

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Use this setup to create default `first_name` and `last_name` columns in your database migration and configure the model to use the PersonNameCast.

```php
// Migration
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('first_name');
    $table->string('last_name')->nullable();
    $table->timestamps();
});

// Model
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::class,
        ];
    }
}
```

--------------------------------

### Custom Setup for Name Columns

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Use this setup when you need to use custom column names for first and last names in your database migration and configure the model to use the PersonNameCast with specific column mappings.

```php
// Migration
Schema::create('blog_posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('author_first');
    $table->string('author_last')->nullable();
    $table->string('editor_first');
    $table->string('editor_last')->nullable();
    $table->timestamps();
});

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

--------------------------------

### Instantiate and Use PersonName

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Demonstrates how to create a new PersonName instance and access its properties. Includes an example of type narrowing for the last name.

```php
use HosmelQ\NameOfPerson\PersonName;

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

// Access properties
echo $name->first; // "David"
echo $name->last;  // "Heinemeier Hansson"

// Type narrowing
if ($name->last !== null) {
    // Confirmed to have last name
    $sorted = $name->sorted(); // "Heinemeier Hansson, David"
}
```

--------------------------------

### PersonName Class Usage Examples

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Demonstrates various ways to instantiate the PersonName class, including handling of whitespace and single names.

```php
use HosmelQ\NameOfPerson\PersonName;

// Normal usage
$name = new PersonName('David', 'Heinemeier Hansson');

// Whitespace is trimmed
$name = new PersonName('  David  ', '  Hansson  ');
echo $name->first; // "David" (trimmed)
echo $name->last;  // "Hansson" (trimmed)

// Whitespace-only last name becomes null
$name = new PersonName('Cher', '   ');
echo $name->last; // null

// Single name (no last name)
$name = new PersonName('Madonna');
echo $name->last; // null
```

--------------------------------

### Define Application-Level Configuration

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Define constants or configuration files for application-level settings. This example shows how to set default first and last name columns for casting.

```php
// config/names.php
return [
    'cast_default_first_column' => 'first_name',
    'cast_default_last_column' => 'last_name',
];
```

```php
// Usage in model
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::using(
                config('names.cast_default_first_column'),
                config('names.cast_default_last_column')
            ),
        ];
    }
}
```

--------------------------------

### Default PersonNameCast Configuration

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Use this configuration when your first and last name columns match the default 'first_name' and 'last_name'. No additional setup is required.

```php
protected function casts(): array
{
    return [
        'name' => PersonNameCast::class, // Uses first_name and last_name columns
    ];
}
```

--------------------------------

### Laravel Integration Example

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Demonstrates the seamless integration with Laravel's Eloquent ORM. It shows automatic casting between database columns and PersonName objects for both retrieval and storage.

```php
$user = User::find(1);
echo $user->name->familiar(); // Automatic object conversion

$user->name = 'New Name'; // Automatic string parsing and storage
```

--------------------------------

### Unicode Support Example

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Demonstrates the library's support for international names using Unicode characters. It shows creating PersonName instances with non-ASCII characters and formatting them.

```php
$spanish = new PersonName('José', 'García');
echo $spanish->familiar(); // "José G."

$chinese = new PersonName('李明', '王');
echo $chinese->full(); // "李明 王"
```

--------------------------------

### Get Sorted Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Get the name formatted for alphabetical sorting as 'Last, First'. If no last name exists, only the first name is returned. The result is cached.

```php
public function sorted(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->sorted(); // "Heinemeier Hansson, David"
```

```php
$single = PersonName::fromFull('Cher');
echo $single->sorted(); // "Cher"
```

--------------------------------

### Get Mentionable PersonName Format in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Generate a lowercase, space-free version of the familiar name, suitable for use in mentions.

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

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

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

--------------------------------

### Get Abbreviated Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Get the name in 'F. Last' format, using the first initial and the full last name. If no last name exists, only the first name is returned. The result is cached.

```php
public function abbreviated(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->abbreviated(); // "D. Heinemeier Hansson"
```

```php
$single = PersonName::fromFull('Cher');
echo $single->abbreviated(); // "Cher"
```

--------------------------------

### Cached Performance Example

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Illustrates the performance optimization where computed name formats are cached after their first use. Subsequent calls to the same format method retrieve the cached value.

```php
$name->familiar(); // Computed and cached
$name->familiar(); // Returns cached value
```

--------------------------------

### Get Full PersonName Format in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Retrieve the complete name formatted as 'First Last'.

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

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

--------------------------------

### Get Sorted PersonName Format in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Format the name as 'Last, First', which is suitable for sorting purposes. Single names are returned as is.

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

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

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

--------------------------------

### Get Familiar PersonName Format in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Format the name as 'First L.', suitable for familiar address. Single names are returned as is.

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

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

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

--------------------------------

### Get Initials

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Extract and concatenate all initials from the name. Text within parentheses and brackets is excluded before extraction. The result is cached.

```php
public function initials(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->initials(); // "DHH"
```

```php
$complex = PersonName::fromFull('Mary Jane Watson');
echo $complex->initials(); // "MJW"
```

```php
// Brackets and parentheses are excluded
$withBrackets = PersonName::fromFull('Conor Muirhead [Basecamp]');
echo $withBrackets->initials(); // "CM"
```

--------------------------------

### Get Mentionable Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Generate a lowercase, space-free version of the familiar name, suitable for mentions or handles. The period from the familiar format is removed. The result is cached.

```php
public function mentionable(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->mentionable(); // "davidh"
```

```php
$single = PersonName::fromFull('Cher');
echo $single->mentionable(); // "cher"
```

--------------------------------

### Get PersonName Initials in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Extract all initials from the name, excluding characters within parentheses and brackets. Works for complex names.

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

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

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

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

--------------------------------

### Get Full Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Retrieve the complete name in 'First Last' format. If no last name is provided, only the first name is returned. The result is cached after the first call.

```php
public function full(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->full(); // "David Heinemeier Hansson"
```

```php
$single = PersonName::fromFull('Cher');
echo $single->full(); // "Cher"
```

--------------------------------

### Get Possessive PersonName Format in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Generate the possessive form of the name. Allows specifying which format (e.g., 'first', 'familiar', 'sorted') to make possessive.

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

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

--------------------------------

### Get Familiar Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Retrieve the name in 'First L.' format, using the first name and the last initial. If no last name exists, only the first name is returned. Supports Unicode characters. The result is cached.

```php
public function familiar(): string
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->familiar(); // "David H."
```

```php
$single = PersonName::fromFull('Cher');
echo $single->familiar(); // "Cher"
```

```php
// Unicode support
$spanish = new PersonName('José', 'García');
echo $spanish->familiar(); // "José G."
```

--------------------------------

### Get Abbreviated PersonName in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Obtain an abbreviated version of the name, consisting of the first initial and the full last name. Handles single names by returning the full name.

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

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

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

--------------------------------

### Instantiate and Format PersonName in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Demonstrates creating a PersonName object and using its various display and utility methods. Requires importing the PersonName class.

```php
use HosmelQ\NameOfPerson\PersonName;

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

// Properties
echo $name->first;  // "David"
echo $name->last;   // "Heinemeier Hansson"

// Display methods
echo $name->full();         // "David Heinemeier Hansson"
echo $name->familiar();     // "David H."
echo $name->abbreviated();  // "D. Heinemeier Hansson"
echo $name->sorted();       // "Heinemeier Hansson, David"
echo $name->initials();     // "DHH"
echo $name->mentionable();  // "davidh"
echo $name->possessive();   // "David Heinemeier Hansson's"

// Utility methods
$name->equals(otherName);   // boolean
```

--------------------------------

### Run Tests

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Execute the project's test suite using Composer.

```bash
composer test
```

--------------------------------

### CastsAttributes Interface

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

A generic interface for attribute casting in Laravel, defining methods for getting and setting attribute values.

```APIDOC
## Interface CastsAttributes<TGet = mixed, TSet = mixed>

### Description
This is a Laravel interface that defines the contract for attribute casting. `PersonNameCast` implements this interface, typically through an anonymous class returned by `castUsing()`.

### Generic Parameters

- **`TGet`** (`mixed`, defaults to `null|PersonName`): The return type of the `get()` method.
- **`TSet`** (`mixed`, defaults to `null|PersonName|string`): The input type of the `set()` method.

### Methods

- **`get(Model $model, string $key, mixed $value, array $attributes): null|PersonName`**: Retrieves and casts the attribute value from the model.
- **`set(Model $model, string $key, mixed $value, array $attributes): non-empty-array<string, null|string>`**: Sets and casts the attribute value before saving to the model.
```

--------------------------------

### Create PersonName Instance

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Instantiate PersonName with a first name and an optional last name. Whitespace-only last names are treated as null. Throws an exception if the first name is empty or whitespace-only.

```php
use HosmelQ\NameOfPerson\PersonName;

$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->first;  // "David"
echo $name->last;   // "Heinemeier Hansson"

$singleName = new PersonName('Cher');
echo $singleName->first; // "Cher"
echo $singleName->last;  // null
```

--------------------------------

### using Method

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Creates a cast configuration string for use in Eloquent model casts. This is a convenience method that generates the properly formatted cast string.

```APIDOC
## using(string $firstNameColumn, string $lastNameColumn): string

### Description
Creates a cast configuration string for use in Eloquent model casts. This is a convenience method that generates the properly formatted cast string.

### Parameters
#### Path Parameters
- **$firstNameColumn** (string) - Required - Name of the database column storing the first name
- **$lastNameColumn** (string) - Required - Name of the database column storing the last name

### Returns
- **string** — Cast definition string in the format `"PersonNameCast:column1,column2"`.

### Example
```php
use HosmelQ\NameOfPerson\PersonNameCast;

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

// Or use the string directly
class Article extends Model
{
    protected function casts(): array
    {
        return [
            'author_name' => PersonNameCast::class . ':author_first,author_last',
        ];
    }
}
```
```

--------------------------------

### Basic Name Formatting

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Demonstrates setting a full name on a model attribute cast with PersonNameCast and retrieving a familiar format.

```php
$user = new User();

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

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

--------------------------------

### PersonName Constructor

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Initializes a new PersonName instance with a first name and an optional last name. The first name is mandatory and cannot be empty or whitespace. The last name is optional and will be treated as null if empty or whitespace.

```APIDOC
## `__construct(string $firstName, null|string $lastName = null)`

### Description
Creates a new PersonName instance with first and optional last name.

### Parameters
#### Path Parameters
- **`$firstName`** (string) - Required - The person's first name. Cannot be empty or whitespace-only.
- **`$lastName`** (string|null) - Optional - The person's last name. Empty or whitespace-only strings are treated as null.

### Example
```php
use HosmelQ\NameOfPerson\PersonName;

$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->first;  // "David"
echo $name->last;   // "Heinemeier Hansson"

$singleName = new PersonName('Cher');
echo $singleName->first; // "Cher"
echo $singleName->last;  // null
```
```

--------------------------------

### Instantiate PersonName

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Create a new PersonName object with a first and last name. The first name is required, while the last name is optional.

```php
public readonly string $first;
public readonly null|string $last;
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->first; // "David"
```

```php
$name = new PersonName('David', 'Heinemeier Hansson');
echo $name->last; // "Heinemeier Hansson"
```

```php
$single = PersonName::fromFull('Cher');
echo $single->last; // null
```

--------------------------------

### Get Possessive Form of Name

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Returns the possessive form of a name. Handles names ending in 's' by using an apostrophe only. Accepts various name formats.

```php
public function possessive(string $method = 'full'): string
```

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

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

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

// Names ending in 's' use apostrophe only
$james = new PersonName('James', 'Davis');
echo $james->possessive(); // "James Davis'"
```

--------------------------------

### PersonName Constructor & Factories

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Methods for creating and initializing PersonName objects.

```APIDOC
## `new PersonName(string, string|null)`

### Description
Create instance with first and optional last name.

### Method
`new`

### Parameters
#### Path Parameters
- **firstName** (string) - Required - The first name.
- **lastName** (string|null) - Optional - The last name.

## `PersonName::fromFull(string)`

### Description
Parse full name string into first and last name.

### Method
`static`

### Parameters
#### Path Parameters
- **fullName** (string) - Required - The full name string to parse.

### Returns
- `null|PersonName` - A PersonName instance or null if parsing fails.
```

--------------------------------

### Import Paths for NameOfPerson Classes

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Provides the necessary import statements for using PersonName and PersonNameCast classes. These classes are discoverable via PSR-4 autoloading.

```php
use HosmelQ\NameOfPerson\PersonName;
use HosmelQ\NameOfPerson\PersonNameCast;
```

--------------------------------

### CastsAttributes Interface Definition

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Defines the generic CastsAttributes interface used for custom attribute casting in Laravel. Specifies the generic types for get and set methods.

```php
interface CastsAttributes<TGet = mixed, TSet = mixed>
{
    public function get(Model $model, string $key, mixed $value, array $attributes): TGet;
    public function set(Model $model, string $key, mixed $value, array $attributes): array;
}
```

--------------------------------

### Custom PersonNameCast Configuration (Helper Method)

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Configure custom first and last name columns using the fluent `using()` helper method for a more readable syntax. This method returns the cast definition string.

```php
use HosmelQ\NameOfPerson\PersonNameCast;

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

```php
class BlogPost extends Model
{
    protected function casts(): array
    {
        return [
            'author_name' => PersonNameCast::using('author_first', 'author_last'),
            'editor_name' => PersonNameCast::using('editor_first', 'editor_last'),
            'reviewer_name' => PersonNameCast::using('reviewer_first', 'reviewer_last'),
        ];
    }
}

// Usage
$post = BlogPost::find(1);
echo $post->author_name->full();    // "David Heinemeier Hansson"
echo $post->editor_name->familiar(); // "Jason F."
echo $post->reviewer_name->sorted(); // "Fried, Will"
```

--------------------------------

### Create PersonName Objects in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Instantiate PersonName objects directly with first and last names, or parse them from full name strings. Handles single names gracefully.

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

--------------------------------

### PersonName Instance Methods

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Instance methods available on the PersonName class for formatting and retrieving name variations.

```APIDOC
## Instance Methods

### `full(): string`

Returns the complete name in "First Last" format. If no last name exists, returns just the first name.

```php
public function full(): string
```

**Returns:** `string` — The full name as "First Last" or just "First" if no last name.

### `abbreviated(): string`

Returns the first initial plus full last name in the format "F. Last". If no last name exists, returns just the first name.

```php
public function abbreviated(): string
```

**Returns:** `string` — Abbreviated form as "F. Last" or just "First".

### `familiar(): string`

Returns first name plus last initial with a period in the format "First L." If no last name exists, returns just the first name.

```php
public function familiar(): string
```

**Returns:** `string` — Familiar form as "First L." or just "First".

### `sorted(): string`

Returns the name in "Last, First" format suitable for alphabetical sorting. If no last name exists, returns just the first name.

```php
public function sorted(): string
```

**Returns:** `string` — Sorted form as "Last, First" or just "First".

### `initials(): string`

Returns all initials from the name, extracted from word boundaries. Removes text in parentheses and brackets before extracting initials.

```php
public function initials(): string
```

**Returns:** `string` — Uppercase initials concatenated together.

### `mentionable(): string`

Returns a lowercase, space-free version of the familiar name suitable for use in mentions or handles. Removes the period from the familiar format.

```php
public function mentionable(): string
```

**Returns:** `string` — Lowercased familiar format without spaces or periods.
```

--------------------------------

### Display Methods

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Methods for formatting and retrieving different representations of the full name. All methods return a string and cache results.

```APIDOC
## `full()`

### Description
Returns the full name in "First Last" format.

### Returns
- `string` - The full name.

## `familiar()`

### Description
Returns the name in "First L." format.

### Returns
- `string` - The familiar name format.

## `abbreviated()`

### Description
Returns the name in "F. Last" format.

### Returns
- `string` - The abbreviated name format.

## `sorted()`

### Description
Returns the name in "Last, First" format.

### Returns
- `string` - The sorted name format.

## `initials()`

### Description
Returns the initials of the name.

### Returns
- `string` - The initials.

## `mentionable()`

### Description
Returns the name in a lowercase, no-spaces format suitable for mentions.

### Returns
- `string` - The mentionable name format.

## `possessive(string?)`

### Description
Returns the possessive form of the name.

### Parameters
#### Path Parameters
- **suffix** (string) - Optional - A custom possessive suffix.

### Returns
- `string` - The possessive name format.
```

--------------------------------

### set(Model $model, string $key, mixed $value, array $attributes): non-empty-array<string, null|string>

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Prepares a PersonName instance or string value for database storage by extracting first and last name components. It handles null, PersonName objects, and strings, converting them into an array suitable for database columns.

```APIDOC
## set(Model $model, string $key, mixed $value, array $attributes): non-empty-array<string, null|string>

### Description
Prepares a `PersonName` instance or string value for database storage by extracting first and last name components. It handles null, PersonName objects, and strings, converting them into an array suitable for database columns.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```php
public function set(Model $model, string $key, mixed $value, array $attributes): non-empty-array<string, null|string>
```

### Parameters
#### Method Parameters
- **$model** (`Model`) - The Eloquent model instance
- **$key** (`string`) - The attribute name in the model
- **$value** (`mixed`) - The value being set (PersonName, string, or null)
- **$attributes** (`array`) - The model's attributes array (for context)

### Returns
`array` — A key-value array mapping the configured column names to their string values or `null`.

### Behavior
- Handles `null` values: returns array with both columns set to `null`
- Handles `PersonName` instances: extracts `first` and `last` properties
- Handles strings: parses via `PersonName::fromFull()` to extract first and last names
- Invalid types (int, object, etc.) throw `InvalidArgumentException`
- Empty strings are treated as `null` names

### Throws
`InvalidArgumentException` if `$value` is not `null`, `string`, or `PersonName` instance.

### Example
```php
use HosmelQ\NameOfPerson\PersonName;

// In Eloquent model
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::class,
        ];
    }
}

// Setting with a string
$user = new User();
$user->name = 'David Heinemeier Hansson';
// Database columns updated: first_name='David', last_name='Heinemeier Hansson'

// Setting with a PersonName instance
$user->name = new PersonName('Jason', 'Fried');
// Database columns updated: first_name='Jason', last_name='Fried'

// Setting with null
$user->name = null;
// Database columns set to: first_name=null, last_name=null

// Setting with empty string
$user->name = '';
// Database columns set to: first_name=null, last_name=null
```
```

--------------------------------

### Create Caster Instance - PersonNameCast

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Use castUsing to create a caster instance for Laravel's casting system. It defaults to 'first_name' and 'last_name' if no arguments are provided.

```php
public static function castUsing(array $arguments): CastsAttributes
```

```php
use HosmelQ\NameOfPerson\PersonNameCast;

// Direct usage (rarely needed - Laravel handles this automatically)
$caster = PersonNameCast::castUsing([]);
$caster = PersonNameCast::castUsing(['given_name', 'family_name']);
```

--------------------------------

### Validate Input Before PersonName Construction

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/errors.md

Handle empty names gracefully by returning null instead of throwing an exception when creating a PersonName instance.

```php
use HosmelQ\NameOfPerson\PersonName;

function createPersonName(string $firstName, ?string $lastName): ?PersonName
{
    if (trim($firstName) === '') {
        return null; // Handle empty names gracefully
    }
    
    return new PersonName($firstName, $lastName);
}

$name = createPersonName('', null); // Returns null instead of throwing
```

--------------------------------

### PersonName::fromFull Static Method

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Creates a PersonName instance from a single string representing a full name. The method splits the string by whitespace, assigning the first word to the first name and the rest to the last name. It returns null for empty or whitespace-only input.

```APIDOC
## `fromFull(string $fullName)`

### Description
Creates a PersonName instance from a full name string by splitting on whitespace. The first word becomes the first name, and all remaining words form the last name.

### Parameters
#### Path Parameters
- **`$fullName`** (string) - Required - A full name string, e.g., "Jason Fried" or "Will St. Clair"

### Returns
`PersonName|null` - New PersonName instance, or `null` if the input is empty or whitespace-only.

### Example
```php
use HosmelQ\NameOfPerson\PersonName;

$parsed = PersonName::fromFull('Jason Fried');
echo $parsed->first;  // "Jason"
echo $parsed->last;   // "Fried"

// Handles compound last names
$compound = PersonName::fromFull('Will St. Clair');
echo $compound->last; // "St. Clair"

// Returns null for empty input
$empty = PersonName::fromFull('');
// $empty is null

// Normalizes whitespace
$normalized = PersonName::fromFull('  Will   St. Clair  ');
echo $normalized->full(); // "Will St. Clair"
```
```

--------------------------------

### get(Model $model, string $key, mixed $value, array $attributes): null|PersonName

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Casts database attributes to a PersonName instance when retrieving from the database. It looks for first and last name columns in the model's attributes and returns a PersonName object or null if the first name is missing or empty.

```APIDOC
## get(Model $model, string $key, mixed $value, array $attributes): null|PersonName

### Description
Casts database attributes to a `PersonName` instance when retrieving from the database. It looks for first and last name columns in the model's attributes and returns a PersonName object or null if the first name is missing or empty.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```php
public function get(Model $model, string $key, mixed $value, array $attributes): null|PersonName
```

### Parameters
#### Method Parameters
- **$model** (`Model`) - The Eloquent model instance
- **$key** (`string`) - The attribute name in the model
- **$value** (`mixed`) - The raw value from the cast call (not used)
- **$attributes** (`array`) - The model's attributes array containing the database columns

### Returns
`PersonName|null` — A new PersonName instance created from the first and last name columns, or `null` if the first name column is missing or empty.

### Behavior
- Looks for column values in `$attributes` using the configured column names
- Returns `null` if the first name column is not present or contains only whitespace
- Creates and returns a new PersonName instance with the retrieved names
- Last name can be `null` without affecting the result (PersonName allows single names)

### Example
```php
// In Eloquent model definition
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::class,
        ];
    }
}

// Usage - automatic conversion
$user = User::find(1); // Database has: first_name='David', last_name='Heinemeier Hansson'
$name = $user->name; // Returns PersonName instance
echo $name->full(); // "David Heinemeier Hansson"
```
```

--------------------------------

### Create PersonName from Full Name String

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Create a PersonName instance by parsing a full name string. The first word is used as the first name, and the rest as the last name. Returns null for empty or whitespace-only input and normalizes whitespace.

```php
use HosmelQ\NameOfPerson\PersonName;

$parsed = PersonName::fromFull('Jason Fried');
echo $parsed->first;  // "Jason"
echo $parsed->last;   // "Fried"

// Handles compound last names
$compound = PersonName::fromFull('Will St. Clair');
echo $compound->last; // "St. Clair"

// Returns null for empty input
$empty = PersonName::fromFull('');
// $empty is null

// Normalizes whitespace
$normalized = PersonName::fromFull('  Will   St. Clair  ');
echo $normalized->full(); // "Will St. Clair"
```

--------------------------------

### Custom PersonNameCast Configuration (String-Based)

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Specify custom database column names for first and last names by appending them as a colon-separated string to the cast class.

```php
protected function casts(): array
{
    return [
        'author_name' => PersonNameCast::class . ':author_first,author_last',
    ];
}
```

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

--------------------------------

### Compare PersonName Objects for Equality in PHP

Source: https://github.com/hosmelq/name-of-person/blob/main/README.md

Use the 'equals()' method to compare two PersonName objects for exact equality.

```php
$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
```

--------------------------------

### JSON Serialization of PersonName

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Demonstrates how PersonNameCast automatically serializes to a full name string when included in JSON responses.

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

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

--------------------------------

### Setting PersonNameCast with Different Values

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Demonstrates how to set the 'name' attribute using various input types: a full name string, a PersonName object, null, or an empty string. The cast handles the conversion to database column values.

```php
use HosmelQ\NameOfPerson\PersonName;

// In Eloquent model
class User extends Model
{
    protected function casts(): array
    {
        return [
            'name' => PersonNameCast::class,
        ];
    }
}

// Setting with a string
$user = new User();
$user->name = 'David Heinemeier Hansson';
// Database columns updated: first_name='David', last_name='Heinemeier Hansson'

// Setting with a PersonName instance
$user->name = new PersonName('Jason', 'Fried');
// Database columns updated: first_name='Jason', last_name='Fried'

// Setting with null
$user->name = null;
// Database columns set to: first_name=null, last_name=null

// Setting with empty string
$user->name = '';
// Database columns set to: first_name=null, last_name=null
```

--------------------------------

### Import Paths

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Specifies the import paths for the public types within the NameOfPerson package.

```APIDOC
## Import Paths

### Description
All public types provided by the `HosmelQ
NameOfPerson` package are located within this namespace. These classes are automatically discoverable via PSR-4 autoloading as defined in the `composer.json` file.

### Usage

```php
use HosmelQ\NameOfPerson\PersonName;
use HosmelQ\NameOfPerson\PersonNameCast;
```
```

--------------------------------

### Utility Methods

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

General utility methods for the PersonName class.

```APIDOC
## `equals(PersonName)`

### Description
Compare two PersonName instances for equality.

### Parameters
#### Path Parameters
- **otherPersonName** (PersonName) - Required - The other PersonName instance to compare against.

### Returns
- `bool` - True if the instances are equal, false otherwise.

## `__toString()`

### Description
Casts the PersonName instance to a string, returning the full name.

### Returns
- `string` - The full name.

## `jsonSerialize()`

### Description
Serializes the PersonName instance to a JSON string, returning the full name.

### Returns
- `string` - The full name in JSON serializable format.
```

--------------------------------

### PersonName Constructor Signature

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Defines the signature for the PersonName constructor, specifying first and last name parameters.

```php
public function __construct(string $firstName, null|string $lastName = null)
```

--------------------------------

### Compare PersonName Objects for Equality

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonName.md

Compares two PersonName objects to check if their first and last names are identical. Returns true if they match, false otherwise.

```php
public function equals(PersonName $other): bool
```

```php
$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
```

--------------------------------

### Pure PHP Usage of PersonName

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Instantiate and format names using the PersonName class in plain PHP. Useful for general string manipulation of names.

```php
use HosmelQ\NameOfPerson\PersonName;

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

// Display in different formats
echo $name->full();      // "David Heinemeier Hansson"
echo $name->familiar();  // "David H."
echo $name->sorted();    // "Heinemeier Hansson, David"

// Format with possessive
$greeting = sprintf("%s's team", $name->first);
echo $greeting; // "David's team"
```

--------------------------------

### Eloquent Model Casts Array Configuration

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Demonstrates how to configure attribute casting for Eloquent models using PersonNameCast.

```APIDOC
## Eloquent Model Casts Array Configuration

### Description
This section illustrates how to define attribute casts within a Laravel Eloquent model using the `PersonNameCast` class. It covers default column names, custom column names, and using a helper method for configuration.

### Default Columns (first_name, last_name)

```php
protected function casts(): array
{
    return [
        'name' => PersonNameCast::class,
    ];
}
```

### Custom Columns (using class constant with string)

```php
protected function casts(): array
{
    return [
        'author_name' => PersonNameCast::class . ':author_first,author_last',
    ];
}
```

### Custom Columns (using helper method)

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

### Return Type

- `array<string, string|class-string>`: The `casts()` method should return an array where keys are attribute names and values are the cast class names or configurations.
```

--------------------------------

### Safe Parsing with PersonName::fromFull()

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/errors.md

Use `fromFull()` for parsing full names from strings, as it returns `null` for empty or invalid input, allowing for graceful error handling.

```php
use HosmelQ\NameOfPerson\PersonName;

$fullName = getUserInput();

$name = PersonName::fromFull($fullName);

if ($name === null) {
    // Handle empty or invalid input
    echo "Please provide a valid name";
} else {
    // Use the name
    echo $name->full();
}
```

--------------------------------

### Default Database Schema for PersonNameCast

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Defines the default database table structure required for the PersonNameCast, including 'first_name' and 'last_name' columns. Both should support null values.

```php
// Default column setup
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('first_name');
    $table->string('last_name')->nullable();
    $table->timestamps();
});

// Custom column setup
Schema::create('blog_posts', function (Blueprint $table) {
    $table->id();
    $table->string('author_first');
    $table->string('author_last')->nullable();
    $table->timestamps();
});
```

--------------------------------

### Generate Cast String - PersonNameCast::using

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/api-reference/PersonNameCast.md

Use the static using method to generate a cast configuration string for Eloquent models. This simplifies defining custom column names in your model's casts array.

```php
public static function using(string $firstNameColumn, string $lastNameColumn): string
```

```php
use HosmelQ\NameOfPerson\PersonNameCast;

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

// Or use the string directly
class Article extends Model
{
    protected function casts(): array
    {
        return [
            'author_name' => PersonNameCast::class . ':author_first,author_last',
        ];
    }
}
```

--------------------------------

### Laravel Migration for Contact Names

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/configuration.md

Defines a database migration for a 'contacts' table, including columns for both primary and alternative names using string types.

```php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('contacts', function (Blueprint $table) {
            $table->id();
            
            // Primary contact name (required)
            $table->string('first_name');
            $table->string('last_name')->nullable();
            
            // Alternative contact name (optional)
            $table->string('alt_first')->nullable();
            $table->string('alt_last')->nullable();
            
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('contacts');
    }
};
```

--------------------------------

### Define PersonName Class

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/types.md

Defines the PersonName class with first and last name properties. Implements JsonSerializable and Stringable interfaces.

```php
class PersonName implements JsonSerializable, Stringable
{
    public readonly string $first;
    public readonly null|string $last;
}
```

--------------------------------

### PersonNameCast Class

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Laravel Eloquent casting implementation for seamless database integration of PersonName objects.

```APIDOC
## Class: PersonNameCast

### Description
Provides Laravel Eloquent casting for the PersonName class, allowing seamless database integration.

### Location
`src/PersonNameCast.php`

### Implements
`Castable` (Laravel interface)

### Requires
Laravel 11+

### Usage Example
```php
use Illuminate\Database\Eloquent\Model;
use HosmelQ\NameOfPerson\PersonNameCast;

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

### Methods
- **`castAttribute(Model $model, string $key, mixed $value, array $attributes): PersonName`**: Casts the attribute to a PersonName object.
- **`get(Model $model, string $key, mixed $value, array $attributes): PersonName`**: Retrieves the attribute value as a PersonName object.
- **`set(Model $model, string $key, mixed $value, array $attributes): array`**: Sets the attribute value, preparing it for storage.
- **`using(string $firstKey, string $lastKey): static`**: Specifies custom keys for first and last names when casting.
```

--------------------------------

### Configure PersonNameCast for Laravel Eloquent

Source: https://github.com/hosmelq/name-of-person/blob/main/_autodocs/README.md

Shows how to use the PersonNameCast for Eloquent models to handle person names stored in the database. Supports default first and last name fields or custom field names.

```php
use HosmelQ\NameOfPerson\PersonNameCast;

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