marvin255/value-object

Set of value objects for PHP.

v0.3.2 2026-04-06 15:41 UTC

Requires

• php: >=8.4
• psr/http-message: ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• infection/infection: ^0.32
• phpunit/phpunit: ^12.0|^13.0
• vimeo/psalm: ^6.0

MIT

• php
• value-object

README

A collection of type-safe value objects for PHP 8.3+ with built-in validation. Includes email, URI, integer, string, and file info objects designed for domain-driven development.

Installation

Install the package via Composer:

composer require marvin255/value-object

Usage

String Value Objects

Create type-safe string values with optional constraints:

use Marvin255\ValueObject\StringValueObject;
use Marvin255\ValueObject\StringNonEmptyValueObject;

// Basic string value object
$name = new StringValueObject('John Doe');
echo $name->value(); // "John Doe"

// String that cannot be empty
$title = new StringNonEmptyValueObject('Developer');
echo $title->value(); // "Developer"

Integer Value Objects

Work with integers using type-safe value objects:

use Marvin255\ValueObject\IntValueObject;
use Marvin255\ValueObject\IntPositiveValueObject;
use Marvin255\ValueObject\IntNonNegativeValueObject;
use Marvin255\ValueObject\IntNegativeValueObject;
use Marvin255\ValueObject\IntNonPositiveValueObject;

// Any integer
$count = new IntValueObject(-5);
echo $count->value(); // -5

// Positive integer only (> 0)
$age = new IntPositiveValueObject(25);
echo $age->value(); // 25

// Non-negative integer (>= 0)
$score = new IntNonNegativeValueObject(0);
echo $score->value(); // 0

// Negative integer only (< 0)
$debt = new IntNegativeValueObject(-100);
echo $debt->value(); // -100

// Non-positive integer (<= 0)
$offset = new IntNonPositiveValueObject(-5);
echo $offset->value(); // -5

Float Value Objects

Work with floating-point numbers safely:

use Marvin255\ValueObject\FloatValueObject;

// Any float value
$price = new FloatValueObject(19.99);
echo $price->value(); // 19.99

BCMath Value Object

Arbitrary-precision decimal numbers using BcMath:

use Marvin255\ValueObject\BcMathNumberValueObject;

$file = new BcMathNumberValueObject('123.123123');
echo $empty->value(); // "123.123123"

Percentage Value Object

Work with percentage values (0-100) safely:

use Marvin255\ValueObject\PercentageValueObject;

// Percentage between 0 and 100
$progress = new PercentageValueObject(75.5);
echo $progress->value(); // 75.5

$complete = new PercentageValueObject(100);
echo $complete->value(); // 100

$empty = new PercentageValueObject(0.0);
echo $empty->value(); // 0

// Decimal precision supported
$accuracy = new PercentageValueObject(99.99);
echo $accuracy->value(); // 99.99

// This will throw an exception
// new PercentageValueObject(101); // throws InvalidArgumentException

Email Value Object

Validate and use email addresses:

use Marvin255\ValueObject\EmailValueObject;

$email = new EmailValueObject('[e-mail]');
echo $email->value(); // "[e-mail]"

URI Value Object

Create validated URI objects:

use Marvin255\ValueObject\UriValueObject;

$uri = new UriValueObject('https://example.com/path?query=value');
echo $uri->value(); // "https://example.com/path?query=value"

File Info Value Object

Work with file information safely:

use Marvin255\ValueObject\FileInfoValueObject;

$file = new FileInfoValueObject('/path/to/file.txt');
echo $file->value()->getPathname(); // "/path/to/file.txt"
echo $file->getMimeType();          // "text/plain"