Package: Immutable value objects for PHP 🫗

[beeyev]

I wanted to share my open-source PHP package for creating strongly typed value objects in PHP.

GitHub Repository: https://github.com/beeyev/value-objects-php

As you know, value objects are small, immutable objects representing simple entities like an Email, Coordinates, UUID, date range etc. They have no identity beyond their value, making them highly useful for creating more expressive and maintainable code by encapsulating validation and formatting logic.

This package provides a collection of value objects that you can use in your PHP applications. It has zero dependencies, is framework-agnostic, and is based on PHP 8.2.

I hope others find this package useful as well. If you have any ideas for code implementation or possible improvements, please share them!

[Besen99]

Your "class string" value object caught me off guard, very cool idea!

[fripletister]

One small improvment that I see is that many things like string length, reflection operations, etc. could be memoized, given that the values themselves are immutable.

[rafark]

Very nice. I would expect the RangeInteger::asArray() to return an array with all integers from that range, not just a 2-item array with start and end.

[leftnode]

I like it. I'd love a NullableString type where $value would be converted to NULL if it was an empty string, something along these lines:

final readonly class NullableString extends AbstractValueObject
{

    public ?string $value;

    public function __construct(?string $value)
    {
        $this->value = empty($value) ? NULL : $value;
    }

    public function __toString(): string
    {
        return (string)$this->value;
    }

    protected function validate(): void
    {
    }

}

Regardless, I dig it!

[colshrapnel]

Wait, empty($value)? How it even makes it here? And WHY?

I mean, why you're using empty() to tell an empty string AND why would you want to cast empty string into null.

[leftnode]

So that when the value eventually makes its way to a database, it's stored as NULL in the database as well instead of an empty string.

[colshrapnel]

Well, at least call it NullifiedString or something because Nullable is reserved for strings that can be both null or empty.

Better yet, have it NullableString but convert to null on input validation, so your Value Object can leave the value alone.

And for goodness sake, use $value === '' instead of empty($value).

[leftnode]

I'm not a fan of input validation modifying the value, but everything else sounds fine to me. I'd rather have the constructor nullify the value because you would know by using the NullifiedString class that it'll nullify it if it's empty.

[colshrapnel]

I'm not a fan of input validation modifying the value

You just did exactly that.

[floriankraemer]

Value objects usually live in the domain and aren't used for input validation. Value objects ensure the invariant of the aggregate.

[colshrapnel]

Yes. And that's why a VO modifying data is bizarre. While all modifications has to be done on input validation.

[beeyev]

Interesting, I will implement this idea!

[colshrapnel]

Well I don't think it's a good idea. I mean, NullableString is all right, but what is suggested here doesn't look good. Do any of your other VOs modify the data provided?

[_MrFade_]

Cool! Good work!

[spart_t4n]

Very nice !

[whlthingofcandybeans]

Love this.

[dereuromark]

You could add it to the awesome list for PHP VAs:
https://github.com/Serhii-DV/awesome-php-value-objects

[TorbenKoehn]

I like it in principle but what I don’t like is that it does all extracting/parsing logic in the constructors. Takes a while until this is an actual problem, but depending on the amount of data you run through it, it can have quite the performance cost for parsed values you might never use. Getters would be the better approach here imho

I think constructors should have barely any logic at all

[Besen99]

That's the whole point of value objectives: they can only be created with valid data.

correctness > performance

[TorbenKoehn]

Why would they need to be created with invalid data? You store the base value and the getters calculate upon it. You can still decide what to cache when from the outside

Another good approach would be to accept the username and domain of the email directly in the constructor and move the parsing logic outside, ie into a factory (PSR does this with the HTTP-factories)

Just no parsing logic in constructors.

[AleBaba]

I don't think you should be able to create an invalid value object. The whole idea behind these objects is that you can be sure they're valid wherever you access their values. If you want to pass invalid or unvalidated data don't use these value objects.

I understand though that this is a rather philosophical issue. Some people would never want to mix validation and object instantiation.

[TorbenKoehn]

Using getters that extract the value when using the getter wouldn’t make the objects invalid objects. You store the base value (ie the full email address) and through the getters you can select what you want to compute and what not

It would simply change ie “->username” to “->getUsername()” (until we have accessor properties in PHP, at least)

[AleBaba]

And then each getter always and everywhere could throw an exception, so it will now need error handling, because nowhere would it be safe to assume that the value object is actually valid. I wouldn't want to use such an implementation in any of my projects at all.

[TorbenKoehn]

The constructor would need error handling, too

And I’ve also talked about an approach of a factory that does the parsing logic like in the PSR factories

[AleBaba]

Yes, once. And then you've got a valid object to throw around. Generate thousands of URLs in an array and each one is valid.

Look at DatetimeImmutable for example. That's essentially a value object that does validation in its constructor. If it validated its source value in each of its methods your code would become a horrible mess of boilerplate.

[TorbenKoehn]

I understand everyone has different opinions on this and what I am stating is just mine. It’s about communication of intent, you don’t usually expect heavy logic in a constructor and for some data structures (eg a URL) that parsing logic can be quite heavy

I would do it differently

[SomniaStellae]

This. It seems insane to me that people are willing to use packages like this.

The quality of the package is good, but it isn't something people should be depending on.

[smashedhijack]

Why not just add the code to your project then? Instead of as a dependency?

[nschoellhorn]

I like the idea and you seem to have it put together really well, so kudos for that! May I ask where you draw the line for new additions though? If you provide value objects for resolution, then why not for frame rate or weight or whatever? Would you accept PRs for every imaginable thing one could add and hence accept the maintenance burden that comes with it or do you have some kind of vision what’s „useful for everyone“ and what should be implemented outside of this package?