Skip to main content

Usage

Creating value objects​

There are three ways to create a value object. They differ only in how they handle invalid values.

use valobj\string\Email;

// 1. Constructor — throws a checked IllegalValueException
$email = new Email('info@n2n.rocks');

// 2. from() — throws an unchecked IllegalStateException, accepts null
$email = Email::from('info@n2n.rocks');
$email = Email::from(null); // null

// 3. checkedFrom() — like from(), but throws a checked IllegalValueException
$email = Email::checkedFrom('info@n2n.rocks');
MethodInvalid valuenull input
new Email($v)IllegalValueExceptionnot allowed
Email::from($v)IllegalStateExceptionreturns null
Email::checkedFrom($v)IllegalValueExceptionreturns null

Use from() for values you trust (constants, values from your own code). Use checkedFrom() or the constructor if you want to handle invalid input yourself:

use n2n\spec\valobj\err\IllegalValueException;

try {
$email = Email::checkedFrom($input);
} catch (IllegalValueException $e) {
// show error message
}

For user input, prefer n2n Bind — you get validation error messages instead of exceptions.

Lenient mode​

from() and checkedFrom() of string value objects accept a second parameter $lenient. In lenient mode the value is normalized before it is validated, and an empty string results in null.

Email::from(' Info@N2N.rocks '); // IllegalStateException: Illegal e-mail value
Email::from(' Info@N2N.rocks ', true); // "info@n2n.rocks"

Name::from(" Hans \t Muster ", true); // "Hans Muster"
Phone::from('0041 (0)79 123 45 67', true); // "+41 (0)79 123 45 67"

Email::from('', true); // null
Email::from(''); // IllegalStateException: Empty string not allowed.

Truncating​

CleanString and DirtyString types can cut a value that is too long:

Name::from(str_repeat('a', 100)); // IllegalStateException: Value too long
Name::fromTruncate(str_repeat('a', 100)); // "aaaa…aaa..." (80 chars, Name::MAX_LENGTH)

Reading the value​

$email = Email::from('info@n2n.rocks');

$email->toScalar(); // "info@n2n.rocks"
(string) $email; // "info@n2n.rocks"
echo $email; // info@n2n.rocks

NbId::from(42)->toScalar(); // 42 (int)
TypicalTwoDigitDecimal::from(19.95)->toScalar(); // 19.95 (float)

Comparing​

$email = Email::from('info@n2n.rocks');

$email->equals('info@n2n.rocks'); // true
$email->equals(Email::from('info@n2n.rocks')); // true
$email->equals(null); // false

$email == Email::from('info@n2n.rocks'); // true
$email === Email::from('info@n2n.rocks'); // false — different instances

JSON​

Value objects and value object arrays implement JsonSerializable:

echo json_encode([
'email' => Email::from('info@n2n.rocks'),
'id' => NbId::from(3),
'price' => TypicalTwoDigitDecimal::from(9.9),
'ids' => new NbIdArray([NbId::from(1), NbId::from(2)]),
]);

Output:

{"email":"info@n2n.rocks","id":3,"price":9.9,"ids":[1,2]}

Type hints​

Since a value object can only exist if its value is valid, use them as parameter and property types:

class NewsletterService {

function subscribe(Email $email, ?Name $name = null): void {
// no validation needed here
}
}

$newsletterService->subscribe(Email::from('info@n2n.rocks'), Name::from('Hans Muster'));