Skip to content

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

License

Notifications You must be signed in to change notification settings

michael-rubel/laravel-value-objects

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Value Objects for Laravel

Laravel Value Objects

Latest Version on Packagist Tests Code Quality Code Coverage Infection Larastan

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

SWUbanner

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

$email = new Email('[email protected]');
$email = Email::make('[email protected]');
$email = Email::from('[email protected]');

$email->value();   // '[email protected]'
(string) $email;   // '[email protected]'
$email->toArray(); // ['email' => '[email protected]', '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.