README.md

Value objects with batteries included

Installation

You can install the package via composer:

composer require spatie/value-object

The goal

• Passing data within your code base in a structured manner.
• Provide type validation for this data.
• Support static analysis for eg. auto completion.

Usage

Value objects are defined like so:

class DummyData extends ValueObject
{
    /** @var string */
    public $name;

    /** @var \Spatie\ValueObject\Dummy */
    public $relation;

    public $everythingAllowed;

    /** @var null|string */
    public $nullable;

    /** @var mixed */
    public $mixed;
}

And created like so:

$dummyData = new DummyData([
    'name' => 'Spatie',
    'relation' => new Dummy(),
    'everythingAllowed' => 'abc'
    'mixed' => 123,
    // 'nullable' => 'deliberately left out',
]);

In practice, you'll almost always will provide static constructors:

class DummyData
{
    public static function fromRequest(Request $request): DummyData
    {
        return new self([
            // …
        ]);
    }

    public static function fromJson(string $json): DummyData
    {
        return new self([
            // …
        ]);
    }
}

PHP's type system

PHP 7.4 will introduce typed class properties. We're making this package as closely as possible to the typed properties implementation, so that when 7.4 comes this package will seamlessly work with typed properties, and not just doc blocks.

A note on immutability

Value objects are meant to be only constructed once, and not changed thereafter. You should never write data to the properties once the value object is created.

Helper functions

Once a value object is constructed, you can read its properties like you'd normally do:

$dummyData->name;

$dummyData->relation;

Because the properties are public, you'll have autocompletion out of the box.

There are also some helper functions provided for working with multiple properties at once.

$dummyData->all();

$dummyData
    ->only('name', 'relation')
    ->toArray();

$dummyData
    ->except('relation')
    ->toArray();

You can also chain these methods:

$dummyData
    ->except('relation')
    ->except('name')
    ->toArray();

It's important to note that except and only are immutable, they won't change the original value object.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

We publish all received postcards on our company website.

Credits

• Brent Roose
• All Contributors

Our Arr class contains functions copied from Laravels Arr helper.

Support us

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.

License

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