michael-rubel/laravel-value-objects

Laravel Value Objects

A bunch of general-purpose value objects you can use in your Laravel application.

The package requires PHP 8.1 or higher and Laravel 10 or higher.

#StandWithUkraine

Installation

Install the package using composer:

composer require michael-rubel/laravel-value-objects

Built-in value objects

• Boolean
• ClassString
• Email
• FullName
• Name
• Number
• Phone
• TaxNumber
• Text
• Url
• Uuid

Artisan command

You can generate custom value objects with Artisan command:

php artisan make:value-object YourNameValueObject

Usage

Boolean

$bool = new Boolean('1');
$bool = Boolean::make('1');
$bool = Boolean::from('1');

$bool->value();   // true
(string) $bool;   // 'true'
$bool->toArray(); // ['true']

Number

$number = new Number('10.20999', scale: 2);
$number = Number::make('10.20999', scale: 2);
$number = Number::from('10.20999', scale: 2);

$number->value();   // '10.20'
(string) $number;   // '10.20'
$number->toArray(); // ['10.20']

// Starting from version `3.5.0` also
// accepts locale-formatted numbers:
$number = new Number('1.230,00');
$number->value(); // '1230.00'
$number = new Number('1,230.00');
$number->value(); // '1230.00'
$number = new Number('1 230,00');
$number->value(); // '1230.00'
$number = new Number('1 230.00');
$number->value(); // '1230.00'

Text

$text = new Text('Lorem Ipsum is simply dummy text.');
$text = Text::make('Lorem Ipsum is simply dummy text.');
$text = Text::from('Lorem Ipsum is simply dummy text.');

$text->value();   // 'Lorem Ipsum is simply dummy text.'
(string) $text;   // 'Lorem Ipsum is simply dummy text.'
$text->toArray(); // ['Lorem Ipsum is simply dummy text.']

ClassString

$classString = new ClassString('\Exception');
$classString = ClassString::make('\Exception');
$classString = ClassString::from('\Exception');

$classString->value();   // '\Exception'
(string) $classString;   // '\Exception'
$classString->toArray(); // ['\Exception']

$classString->classExists();     // true
$classString->interfaceExists(); // false
$classString->instantiate();     // Exception { ... }
$classString->instantiateWith(['message' => 'My message.']); // Exception { #message: "test" ... }

Email

$email = new Email('michael@laravel.software');
$email = Email::make('michael@laravel.software');
$email = Email::from('michael@laravel.software');

$email->value();   // 'michael@laravel.software'
(string) $email;   // 'michael@laravel.software'
$email->toArray(); // ['email' => 'michael@laravel.software', 'username' => 'michael', 'domain' => 'laravel.software']

FullName

$name = new FullName(' Taylor   Otwell ');
$name = FullName::make(' Taylor   Otwell ');
$name = FullName::from(' Taylor   Otwell ');

$name->value();   // 'Taylor Otwell'
(string) $name;   // 'Taylor Otwell'

$name->fullName();  // 'Taylor Otwell'
$name->firstName(); // 'Taylor'
$name->lastName();  // 'Otwell'

$name = 'Richard Le Poidevin';

$fullName = new FullName($name, limit: 2);

$fullName->toArray();

// array:3 [
//  "fullName" => "Richard Le Poidevin"
//  "firstName" => "Richard"
//  "lastName" => "Le Poidevin"
// ]

Name

$name = new Name(' Company name! ');
$name = Name::make(' Company name! ');
$name = Name::from(' Company name! ');

$name->value();   // 'Company name!'
(string) $name;   // 'Company name!'
$name->toArray(); // ['Company name!']

Phone

$phone = new Phone(' +38 000 000 00 00 ');
$phone = Phone::make(' +38 000 000 00 00 ');
$phone = Phone::from(' +38 000 000 00 00 ');

$phone->value();   // '+38 000 000 00 00'
(string) $phone;   // '+38 000 000 00 00'
$phone->toArray(); // ['+38 000 000 00 00']

$phone->sanitized(); // '+380000000000'

TaxNumber

$taxNumber = new TaxNumber('0123456789', 'PL');
$taxNumber = TaxNumber::make('0123456789', 'PL');
$taxNumber = TaxNumber::from('0123456789', 'PL');

$taxNumber->value();   // 'PL0123456789'
(string) $taxNumber;   // 'PL0123456789'
$taxNumber->toArray(); // ['fullTaxNumber' => 'PL0123456789', 'taxNumber' => '0123456789', 'prefix' => 'PL']

$taxNumber->fullTaxNumber(); // 'PL0123456789'
$taxNumber->taxNumber();     // '0123456789'
$taxNumber->prefix();        // 'PL'

Url

$uuid = new Url('my-blog-page');
$uuid = Url::make('my-blog-page');
$uuid = Url::from('my-blog-page');

$uuid->value();   // 'https://example.com/my-blog-page'
(string) $uuid;   // 'https://example.com/my-blog-page'
$uuid->toArray(); // ['https://example.com/my-blog-page']

Uuid

$uuid = new Uuid('8547d10c-7a37-492a-8d33-be0e5ae6119b', 'Optional name');
$uuid = Uuid::make('8547d10c-7a37-492a-8d33-be0e5ae6119b', 'Optional name');
$uuid = Uuid::from('8547d10c-7a37-492a-8d33-be0e5ae6119b', 'Optional name');

$uuid->value();   // '8547d10c-7a37-492a-8d33-be0e5ae6119b'
(string) $uuid;   // '8547d10c-7a37-492a-8d33-be0e5ae6119b'
$uuid->toArray(); // ['name' => 'Optional name', 'value' => '8547d10c-7a37-492a-8d33-be0e5ae6119b']

$uuid->uuid(); // '8547d10c-7a37-492a-8d33-be0e5ae6119b'
$uuid->name(); // 'Optional name'

Handle failed validation

If you want to avoid try/catching your value object when the validation fails, you can use makeOrNull method:

$bool = Boolean::makeOrNull('bad input'); // null

$bool?->value(); // null

Extending functionality

All value objects are Macroable. This way you can add new methods dynamically. If you need to extend existing methods, you can create a value object locally with make:value-object command and use inheritance.

For example:

ValueObject::macro('str', function () {
    return str($this->value());
});

$name = new Text('Lorem ipsum');

$name->str()->is('Lorem ipsum'); // true

Conditionable

Value objects utilize a Conditionable trait. You can use when and unless methods.

TaxNumber::from('PL0123456789')->when(function ($number) {
    return $number->prefix() !== null;
})->prefix();

Contributing

If you see any way we can improve the package, or maybe you want to make your own custom value object as built-in, PRs are welcome.

Testing

composer test

License

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