Awesome
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
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 = 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.