Download the PHP package kodooy/name-value-object without Composer

Laravel Name Value Object Package

A Laravel package for handling name value objects and database casting.

Requirements

• PHP 8.2 or higher
• Laravel 10.0, 11.0, or 12.0

Installation

Usage

Database Casting

Your database table should have first_name and last_name columns:

Add the cast to your Eloquent model:

Usage:

In controller:

The name is automatically cast when retrieved:

API Reference

Name Value Object

The Name value object provides the following methods:

Constructor

Creates a new Name instance. Both parameters are required and cannot be empty.

• Parameters:
  • $firstName: The first name (will be trimmed and capitalized)
  • $lastName: The last name (will be trimmed and capitalized)
• Throws: InvalidArgumentException if either name is empty

Basic Access Methods

Returns the first name.

Returns the last name.

Returns the full name (first name + space + last name).

Formatting Methods

Returns the initials with optional separator.

• Examples: initials() → "JD", initials('.') → "J.D.", initials('-') → "J-D"

Returns the monogram format with periods.

• Example: "J.D."

Returns the name in formal format (Last, First).

• Example: "Doe, John"

Returns the casual format (First + Last initial).

• Example: "John D."

Returns the abbreviated format (First initial + Last name).

• Example: "J. Doe"

Returns the reversed format (Last + First).

• Example: "Doe John"

Variation Methods

Returns the name with a prefix.

• Examples: withPrefix('Dr.') → "Dr. John Doe", withPrefix('Mr.') → "Mr. John Doe"

Returns the name with a suffix.

• Examples: withSuffix('Jr.') → "John Doe Jr.", withSuffix('III') → "John Doe III"

Privacy Methods

Returns a masked version of the name.

• Parameters:
  • $visibleChars: Number of visible characters from the start (default: 1)
  • $maskChar: Character to use for masking (default: '*')
• Example: masked() → "J D", masked(2, '#') → "Jo## Do#"

Returns a SHA256 hash of the full name for privacy.

• Example: "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"

Comparison Methods

Checks if this name is equal to another Name instance.

• Performs case-sensitive comparison of both first and last names

Data Conversion Methods

Returns an array representation containing:

• first_name: The first name
• last_name: The last name
• full_name: The full name
• initials: The initials

Returns the full name. Allows the object to be used as a string.

• Example: echo $name; // "John Doe"

Static Factory Methods

Creates a Name instance from an array.

• Accepted keys: first_name/firstname and last_name/lastname
• Throws: InvalidArgumentException if required keys are missing

Creates a Name instance from a full name string.

• Parameter: $fullName - Must contain exactly two words separated by space
• Throws: InvalidArgumentException if format is invalid
• Example: fromFullName('John Doe') → Name('John', 'Doe')

Creates a Name instance from an email address.

• Parameter: $email - Must be in format "[email protected]"
• Throws: InvalidArgumentException if email format is invalid
• Example: fromEmail('[email protected]') → Name('John', 'Doe')

Generates a random Name instance from predefined lists.

• Returns a Name with randomly selected first and last names

Usage Examples

Error Handling

Invalid Data Handling

The Name value object validates input and throws exceptions for invalid data:

Controller Validation

Proper validation in your controller prevents exceptions:

Cast Error Handling

When using the cast with invalid data types:

Testing

License

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