slpxxv/value-object

A set of value objects

1.0.0 2025-09-06 20:26 UTC

Requires

• php: ~8.3.0 || ~8.4.0
• ramsey/uuid: 5.x-dev

Requires (Dev)

• friendsofphp/php-cs-fixer: dev-master
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.3.x-dev
• vimeo/psalm: ^7.0@dev

MIT

• Dominik Szamburski

• Value Object
• vo
• basalt

Published on Packagist.org on 2026-08-12 20:10 UTC

README

Small, strictly typed value objects for PHP applications. The package provides immutable wrappers for common scalar, identifier, date/time, and person-domain values, with validation close to the data it protects.

Requirements

• PHP 8.3 or 8.4
• ext-mbstring
• Composer 2

Installation

composer require slpxxv/value-object

Usage

All value objects are immutable, implement Stringable, and expose their native value through value(). Invalid input throws Slpxxv\ValueObject\Exception\ValueObjectException or one of its subclasses.

Scalar values

use Slpxxv\ValueObject\Boolean;
use Slpxxv\ValueObject\Double;
use Slpxxv\ValueObject\NonNegativeInteger;
use Slpxxv\ValueObject\PositiveInteger;
use Slpxxv\ValueObject\StringLiteral;

$enabled = Boolean::fromString('yes');
$ratio = Double::fromFloat(1.5);
$offset = NonNegativeInteger::fromInt(0);
$page = PositiveInteger::fromInt(1);
$label = StringLiteral::fromString('Slpxxv');

$enabled->value(); // true
(string) $page;    // "1"
$label->length();  // 6

Boolean accepts 1, true, yes, y, and on, plus their false equivalents (0, false, no, n, off). String input is case-insensitive and surrounding whitespace is ignored. Double rejects NAN and infinite values.

UUID

use Slpxxv\ValueObject\Identifier\Uuid;

$id = Uuid::generate();
$sameId = Uuid::fromString($id->value());
$binary = $id->toBytes();

$id->equals($sameId);       // true
Uuid::fromBytes($binary);   // equivalent UUID

UUID strings are validated and normalized to their canonical lowercase representation.

Date and time

use Slpxxv\ValueObject\DateTime\DateTime;

$createdAt = DateTime::fromString('2026-08-12T12:00:00+00:00');
$expiresAt = $createdAt->modify('+30 days');

$createdAt->lessThan($expiresAt); // true
$createdAt->format();             // DateTimeInterface::ATOM by default

The wrapped value is a DateTimeImmutable; modifying it always creates a new value object.

Person values

use Slpxxv\ValueObject\Person\Age;
use Slpxxv\ValueObject\Person\Female;
use Slpxxv\ValueObject\Person\Firstname;
use Slpxxv\ValueObject\Person\Lastname;
use Slpxxv\ValueObject\Person\Name;

$name = new Name(
    Firstname::fromString('Ada'),
    Lastname::fromString('Lovelace'),
);

$age = Age::fromInt(36); // accepted range: 0..150
$gender = Female::create();

(string) $name; // "Ada Lovelace"

First names support up to 50 characters and last names up to 100 characters. Available gender values are created with Female::create(), Male::create(), and Unspecified::create().

Development

Install dependencies and run the complete quality suite:

composer install
composer check

Individual commands are also available:

composer test      # PHPUnit
composer analyse   # PHPStan and Psalm
composer cs-check  # coding-style check
composer cs-fix    # apply coding-style fixes

License

Released under the MIT License.