Value types/value objects - use clearly defined types for anything that would otherwise be a scalar or composition of scalars

[Ocramius]

This patch introduces value objects into the mix.

What we did is isolating these concepts into these specific well-defined data structures, which would otherwise be strings, and therefore prone to a lot of errors:

• ClearTextPassword - a password type, designed specifically to never be cast back to string in order to avoid obvious security issues
• PasswordHash
• EmailAddress (which is also the concept of "identityfor ourUser` object)

[themark147]

For these value objects instead creating of own method toString it's not much better to use magic method __toString ?

[Ocramius]

@themark147 good question: I prefer to use ->toString() to enforce its explicit usage in the code. I used to write ->__toString() a lot, but then realised that it's supposed to be used in rare technical scenarios (much like Object.toString() is supposed to be used in Java as well).

Here's an example of code that is perfectly valid:

function foo() : string {
    $someVar = SomeValueType::fromSomeInput(...);

    return (string) $someVar;
}

So far, so good, but then over time the code is changed:

function foo() : string {
    $someVar = SomeValueType::fromSomeInput(...);

    if (condition()) {
        $someVar = null;
    }

    return (string) $someVar;
}

Is the second example still valid? Maybe, but the implicit cast obfuscated it, and prevented static analysis from picking up the null pointer exception.

To recap: I avoid language casts as a way to downcast value types, and instead suggest having the cast as an explicit non-magic method on the value type.

EDIT: for the sake of clarity, I'm adding another equivalent example, showing that this has to do with long-term stability, rather than bugs in a single block of code.

Consider following someValue() function.

function someValue() : SomeValueType
{
    return SomeValueType::fromSomeInput(...);
}

We can have two consumers foo() and bar():

function foo() : string
{
    return (string) someValue();
}


function bar() : string
{
    return someValue()->toString();
}

Should someValue() change to following logic due to change in requirements:

function someValue() : ?SomeValueType
{
    if (condition()) {
        return null;
    }

    return SomeValueType::fromSomeInput(...);
}

Now we have bar() crashing (expected), and foo() returning an empty string (incorrect/bug).

By using ->toString() explicitly, in combination with a static analysis checker, this sort of issues can be prevented, and also make the author of someValue() aware of what is going to break in consumers downstream.

[Serhii-DV]

@Ocramius, and why do you prefer to use static method for creating object instead of using __construct in value objects?

[Ocramius]

I go with named constructors for anything that represents data, because you can only have one __construct (that's what the PHP language imposes), but you will very likely have more and more ways to instantiate the structure.

For example:

• Username::fromUserInput(...) - applies strict validation
• Username::fromPersisted(...) - more lax requirements, allowing for past usernames to still be accepted
• Username::forAccount(...) - infers a username from an existing account

I also make __construct private to prevent misuse that would later on lead to BC breaks in all consumers if the logic or parameters in it change.

[kaystrobach]

Mhmm i’d go with factories for that.

[Ocramius]

A static method that produces an instance is a factory function. Moving it to a separate class has no technical advantage, and reduces discoverability.

[igorpan]

@kaystrobach @Ocramius and forces __construct to be public