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');
| Method | Invalid value | null input |
|---|---|---|
new Email($v) | IllegalValueException | not allowed |
Email::from($v) | IllegalStateException | returns null |
Email::checkedFrom($v) | IllegalValueException | returns 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'));