Skip to main content

Ready-to-use types

Overview​

ClassScalarRules
valobj\string\Emailstringvalid email address, lowercase only
valobj\string\Phonestringvalid phone number
valobj\string\Namestringclean string, 1–80 chars, no line breaks
valobj\string\Labelstringclean string, 1–255 chars, no line breaks
valobj\string\Textstringclean string, 1–5500 chars, line breaks allowed
valobj\string\ColorHexstring#rrggbb, lowercase only
valobj\string\LatinStringstringclean string, 1–63 chars, Latin characters only
valobj\string\crypt\PasswordHashstringpassword hash, see below
valobj\string\crypt\EnvEncryptedSecretstringencrypted secret, see below
valobj\int\PositiveIntint> 0
valobj\int\NbIdint> 0, meant for ids
valobj\float\TypicalTwoDigitDecimalfloatmax. 2 decimal places, between -100000 and 100000
valobj\int\NbIdArrayarrayarray of NbId
valobj\int\PositiveIntArrayarrayarray of PositiveInt
valobj\calendar\DateArrayarrayarray 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