README

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.