Ready-to-use types
Overview
| Class | Scalar | Rules |
|---|---|---|
valobj\string\Email | string | valid email address, lowercase only |
valobj\string\Phone | string | valid phone number |
valobj\string\Name | string | clean string, 1–80 chars, no line breaks |
valobj\string\Label | string | clean string, 1–255 chars, no line breaks |
valobj\string\Text | string | clean string, 1–5500 chars, line breaks allowed |
valobj\string\ColorHex | string | #rrggbb, lowercase only |
valobj\string\LatinString | string | clean string, 1–63 chars, Latin characters only |
valobj\string\crypt\PasswordHash | string | password hash, see below |
valobj\string\crypt\EnvEncryptedSecret | string | encrypted secret, see below |
valobj\int\PositiveInt | int | > 0 |
valobj\int\NbId | int | > 0, meant for ids |
valobj\float\TypicalTwoDigitDecimal | float | max. 2 decimal places, between -100000 and 100000 |
valobj\int\NbIdArray | array | array of NbId |
valobj\int\PositiveIntArray | array | array of PositiveInt |
valobj\calendar\DateArray | array | array of n2n\util\calendar\Date |
ShortLabel, MediumLabel and LongLabel are deprecated. Use Label or a custom type instead.
Email
Email::from('info@n2n.rocks'); // ok
Email::from('Info@N2N.rocks'); // IllegalStateException: Illegal e-mail value
Email::from(' Info@N2N.rocks ', true); // "info@n2n.rocks"
Phone
$phone = Phone::from('0041 (0)79 123 45 67', true);
echo $phone; // +41 (0)79 123 45 67
echo $phone->toTel(); // +41791234567
<a href="tel:<?= $phone->toTel() ?>"><?= $phone ?></a>
Name, Label and Text
Name::from('Hans Muster'); // ok
Name::from(str_repeat('a', 81)); // IllegalStateException: Value too long
Label::from('Spring Sale'); // ok
Label::from("Line 1\nLine 2"); // IllegalStateException: Value not clean
Text::from("Line 1\nLine 2"); // ok — Text allows line breaks
ColorHex
ColorHex::from('#ff00aa'); // ok
ColorHex::from('#FF00AA'); // IllegalStateException: Illegal Hex color value
LatinString
LatinString::from('Zürich'); // ok
LatinString::from('Привет'); // IllegalStateException: Value not UTF8, or not inside Basic Latin, …
PositiveInt and NbId
NbId::from(42); // ok
NbId::from(0); // IllegalStateException: Value too small: 0
PositiveInt::from(-3); // IllegalStateException: Value too small: -3
TypicalTwoDigitDecimal
TypicalTwoDigitDecimal::from(19.95); // ok
TypicalTwoDigitDecimal::from(19.955); // IllegalStateException: Value contains more than 2 decimal places
Usually you extend it, e.g. final class Price extends TypicalTwoDigitDecimal {}. See Custom value objects.
PasswordHash
Holds a password hash, never the plain password.
use valobj\string\crypt\PasswordHash;
$hash = PasswordHash::fromPassword('s3cret!');
echo $hash; // $2y$12$…
$hash->verify('s3cret!'); // true
$hash->verify('wrong'); // false
When unmarshalled with n2n Bind, the input is treated as a plain password and gets hashed.
EnvEncryptedSecret
Holds a secret (e.g. an API key) encrypted with a key from the environment variable SECRET_ENCRYPTION_KEY. Only the encrypted form is stored.
use valobj\string\crypt\EnvEncryptedSecret;
$secret = EnvEncryptedSecret::fromUnencrypted('api-key-123');
echo $secret; // {"nonce":"tIthT8v/…", …} — store this
$secret->toPlainSecret(); // PlainSecret — use this to call the API
Use another environment variable by extending the class:
class PaymentApiKey extends EnvEncryptedSecret {
const KEY_ENVIRONMENT_VARIABLE_NAME = 'PAYMENT_SECRET_KEY';
}
Arrays
$ids = new NbIdArray([NbId::from(1), NbId::from(2)]);
foreach ($ids as $id) {
echo $id->toScalar();
}
new NbIdArray([1, 2]); // error — only NbId instances are allowed