PHPackages                             beeyev/value-objects-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. beeyev/value-objects-php

AbandonedArchivedLibrary[Utility & Helpers](/categories/utility)

beeyev/value-objects-php
========================

Immutable value objects for PHP, designed for Domain-Driven Design (DDD). Enhance your applications with expressive, reliable, and maintainable code.

v2.0.1(1y ago)418[4 PRs](https://github.com/beeyev/value-objects-php/pulls)MITPHPPHP ^8.2CI passing

Since Jul 2Pushed 5mo ago2 watchersCompare

[ Source](https://github.com/beeyev/value-objects-php)[ Packagist](https://packagist.org/packages/beeyev/value-objects-php)[ Docs](https://github.com/beeyev/value-objects-php)[ RSS](/packages/beeyev-value-objects-php/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (8)Versions (6)Used By (0)

ValueObjects PHP Package 🫗
==========================

[](#valueobjects-php-package-)

[![Latest Version on Packagist](https://camo.githubusercontent.com/6e5eab90d99d548271da5d90e132953c1a23e18a0234d12b0ad78cce17eb7c5a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6265657965762f76616c75652d6f626a656374732d706870)](https://camo.githubusercontent.com/6e5eab90d99d548271da5d90e132953c1a23e18a0234d12b0ad78cce17eb7c5a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6265657965762f76616c75652d6f626a656374732d706870)[![Supported PHP Versions](https://camo.githubusercontent.com/8f97e772ab3607bc35b448aba4db39a03a52621767d4bbbb36d1094d10453f36/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6265657965762f76616c75652d6f626a656374732d7068702f7068702e737667)](https://camo.githubusercontent.com/8f97e772ab3607bc35b448aba4db39a03a52621767d4bbbb36d1094d10453f36/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6265657965762f76616c75652d6f626a656374732d7068702f7068702e737667)

ℹ️ Introduction
---------------

[](#ℹ️-introduction)

This package provides a collection of immutable value objects that you can use in your PHP applications.

Value objects are a key concept in Domain-Driven Design (DDD).
They are simple objects whose equality is based on their value rather than their identity.
Using value objects can help you write more expressive, reliable, and maintainable code.

🧾 Benefits of using value objects
---------------------------------

[](#-benefits-of-using-value-objects)

- **Immutability**: Ensures objects remain consistent throughout their lifecycle.
- **Expressiveness**: Represents domain concepts naturally.
- **Validation**: Encapsulates validation logic, reducing errors.
- **Reusability**: Promotes DRY principles.
- **Ease of Testing**: Self-contained and simple to test.

📎 Why use value objects over primitives
---------------------------------------

[](#-why-use-value-objects-over-primitives)

- **Validation**: ❗ Guarantees valid data.
- **Self-Documenting Code**: Enhances readability.
- **Encapsulation**: Contains logic related to the value.
- **Consistency**: Ensures uniform handling of data.
- **Ease of Refactoring**: Centralizes changes to logic or validation rules.

📦 Installation
--------------

[](#-installation)

Use Composer to install this package. Run the following command:

```
composer require beeyev/value-objects-php
```

▶️ Usage
--------

[](#️-usage)

Here are examples of how to use the value objects provided by this package:

### Email

[](#email)

```
use Beeyev\ValueObject\Email;

$email = new Email('abc@gmail.com');
echo $email->value;    // Output: 'abc@gmail.com'
echo $email->username; // Output: 'abc'
echo $email->domain;   // Output: 'gmail.com'
```

### URL

[](#url)

```
use Beeyev\ValueObject\Url;

$url = new Url('https://example.com');
echo $url->value;   // Output: 'https://example.com'

// Every value object can be cast to a string
echo (string) $url; // Output: 'https://example.com'
```

### UUID

[](#uuid)

```
use Beeyev\ValueObject\Uuid;

$uuid = new Uuid('550e8400-e29b-41d4-a716-446655440000');
echo $uuid->value; // Output: '550e8400-e29b-41d4-a716-446655440000'
```

### IPv4 Address

[](#ipv4-address)

```
use Beeyev\ValueObject\IPv4;

$ip = new IPv4('172.20.13.13');
echo $ip->value; // Output: '172.20.13.13'
```

### IPv6 Address

[](#ipv6-address)

```
use Beeyev\ValueObject\IPv6;

$ip = new IPv6('2606:4700:4700::1111');
echo $ip->value; // Output: '2606:4700:4700::1111'
```

### Coordinates

[](#coordinates)

Represents a geographic coordinate (latitude and longitude).

```
use Beeyev\ValueObject\Coordinate;

$coordinate = new Coordinate(37.7749, -122.4194);
echo $coordinate->latitude;  // Output: 37.7749
echo $coordinate->longitude; // Output: -122.4194
$coordinate->toArray();      // Array: [37.7749, -122.4194]

// Coordinate object can be created from a string
// Supported formats: '37.7749,-122.4194', '37.7749, -122.4194', '37.7749 122.4194', '37.7749/122.4194'
$coordinate = Coordinate::fromString('37.7749,-122.4194');

echo $coordinate->toString();  // Output: '37.7749, -122.4194'
// Or cast to a string
echo (string) $coordinate;     // Output: '37.7749, -122.4194'
```

### Json

[](#json)

Represents a JSON string.

```
use Beeyev\ValueObject\Json;

$json = new Json('{"name": "John", "age": 30}');
echo $json->value;      // Output: '{"name": "John", "age": 30}'
echo $json->toArray();  // Output: ['name' => 'John', 'age' => 30]
```

### Percentage

[](#percentage)

Represents a percentage integer value from 0 to 100.

```
use Beeyev\ValueObject\Percentage;

$percentage = new Percentage(50);
echo $percentage->value; // Output: 50
```

### RangeInteger

[](#rangeinteger)

Represents a range of integer values.

```
use Beeyev\ValueObject\RangeInteger;

$range = new RangeInteger(-5, 10);
echo $range->start;   // Output: -5
echo $range->end;     // Output: 10
$range->toArray();    // Array: [-5, 10]
echo (string) $range; // Output: '-5 - 10'

// Range object can be created from a string
$range = RangeInteger::fromString('-5 - 10');

// If you try to create a range object with the start value greater than the end value, an exception will be thrown
try {
    $range = new RangeInteger(10, -5);
} catch (ValueObjectInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: 'Start value cannot be greater than the end value.'
}
```

### Resolution

[](#resolution)

Represents resolution (width and height).

```
use Beeyev\ValueObject\Resolution;

// Only positive integers are allowed
$resolution = new Resolution(1920, 1080);
echo $resolution->width;   // Output: 1920
echo $resolution->height;  // Output: 1080
$resolution->toArray();    // Array: [1920, 1080]
echo (string) $resolution; // Output: '1920x1080'
```

### Semantic Version

[](#semantic-version)

Represents a semantic version number (SemVer).

```
use Beeyev\ValueObject\SemVer;

$version = new SemVer('1.0.3');
echo $version->value; // Output: '1.0.3'
echo $version->major; // Output: 1
echo $version->minor; // Output: 0
echo $version->patch; // Output: 3

// Is supports semver with pre-release and build metadata
$version = new SemVer('1.0.3-beta+exp.sha.5114f85');
echo $version->value;          // Output: '1.0.3-beta+exp.sha.5114f85'
echo $version->releaseVersion; // Output: '1.0.3'
echo $version->build;          // Output: 'exp.sha.5114f85'
echo $version->preRelease;     // Output: 'beta'

// SemVer value objects can be compared
$version1 = new SemVer('1.0.5');
$version2 = new SemVer('1.0.1-alpha+001');

$version1->greaterThan($version2); // true
$version1->lowerThan($version2);   // false

$version1->equalTo($version2);     // false
$version1->notEqualTo($version2);  // true

$version1->greaterThanOrEqualTo($version2); // true
$version1->lowerThanOrEqualTo($version2);   // false
```

### Timestamp

[](#timestamp)

Represents a unix timestamp.

```
use Beeyev\ValueObject\Timestamp;

$timestamp = new Timestamp(1631535600);
echo $timestamp->value;   // Output: 1631535600
echo $timestamp->dateTime // Returns DateTimeImmutable object
```

### Class string

[](#class-string)

Represents a PHP class string.

```
use Beeyev\ValueObject\ClassString;

$classString = new ClassString('App\Models\User');
// Same as
$classString = new ClassString(User::class);

echo $classString->value; // Output: 'App\Models\User'

// Returns true if the class exists
$classString->isClassExist(); // true

// Returns true if the object is an instance of this class string.
$classString->isInstanceOf($user); // true

// It is possible to instantiate an object from the class string
$classString = new ClassString(\DateTimeImmutable::class);
$instance = $classString->instantiate();
assert($instance instanceof \DateTimeImmutable);

// It is possible to instantiate an object from the class string with arguments
$classString = new ClassString(\DateTimeImmutable::class);
$instance = $classString->instantiateWith('2021-01-01 00:00:00', new \DateTimeZone('UTC'));
assert($instance instanceof \DateTimeImmutable);
echo $instance->format('Y-m-d H:i:s'); // Output: '2021-01-01 00:00:00'

// It is possible to check if the interface exists
$classString = new ClassString(\DateTimeInterface::class);
$classString->isInterfaceExist(); // true
```

🐒 Primitive Value Objects
-------------------------

[](#-primitive-value-objects)

### Text

[](#text)

Represents a non-empty text string.

```
use Beeyev\ValueObject\Text;
use Beeyev\ValueObject\Exceptions\ValueObjectInvalidArgumentException;

$text = new Text('Hello, World!');
echo $text->value;    // Output: 'Hello, World!'
echo (string) $text;  // Output: 'Hello, World!'
echo $text->length(); // Output: 13

// If you try to create an empty text object, an exception will be thrown
try {
    $text = new Text('');
} catch (ValueObjectInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: 'Text value cannot be empty.'
}
```

### Boolean

[](#boolean)

```
use Beeyev\ValueObject\Boolean;

$boolean = new Boolean(true);
// It is also possible to create a boolean object from non-boolean values
// Supported values: 'true', 'false', '1', '0', 'yes', 'no', 'on', 'off'
// $boolean = new Boolean('on');

echo $boolean->value;      // Output: true
echo $boolean->toString(); // Output: 'true'
echo (string) $boolean;    // Output: 'true'
```

### Integer

[](#integer)

```
use Beeyev\ValueObject\Integer;

$integer = new Integer(42);
// It is also possible to create an integer object from a string
// $integer = new Integer('42');

echo $integer->value; // Output: 42
```

### Positive Integer

[](#positive-integer)

Represents a positive integer greater than zero. Useful for storing values that must always be positive. For example, a database row ID.

```
use Beeyev\ValueObject\PositiveInteger;
use Beeyev\ValueObject\Exceptions\ValueObjectInvalidArgumentException;

$positiveInteger = new PositiveInteger(42);
echo $positiveInteger->value; // Output: 42

// If you try to create a positive integer object from a negative value or equal to zero, an exception will be thrown
try {
    $positiveInteger = new PositiveInteger(0);
} catch (ValueObjectInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: 'Provided number is not a positive integer. Given value: `0`.'
}
```

### Non-Negative Integer

[](#non-negative-integer)

Represents a non-negative integer, greater than or equal to zero.

```
use Beeyev\ValueObject\NonNegativeInteger;
use Beeyev\ValueObject\Exceptions\ValueObjectInvalidArgumentException;

$positiveInteger = new NonNegativeInteger(96);
echo $positiveInteger->value; // Output: 96
```

### Double (float)

[](#double-float)

Represents a double-precision floating-point number.

```
use Beeyev\ValueObject\Double;

$double = new Double(3.14);
// It is also possible to create a double object from a string
// $double = new Double('3.14');

echo $double->value;      // Output: 3.14
echo $double->toString(); // Output: '3.14'
echo (string) $double;    // Output: '3.14'
```

Common functionality
--------------------

[](#common-functionality)

Every value object has the following functionality:

```
// Every value object can be cast to a string and supports \Stringable interface
$vo->toString(); // Returns the value of the object as a string
(string) $vo;    // Returns the value of the object as a string

// Value objects can be compared
$vo1->sameAs($vo2);    // Returns true if the values are equal
$vo1->notSameAs($vo2); // Returns true if the values are not equal
```

🏗 Creating your own value objects
---------------------------------

[](#-creating-your-own-value-objects)

It is possible to create your own value objects by extending the `AbstractValueObject` class.

📚 Extending functionality
-------------------------

[](#-extending-functionality)

Feel free to extend the functionality of the value objects by creating your own classes that inherit from the provided value objects.

🐛 Contributions
---------------

[](#-contributions)

If you have suggestions for improvements or wish to create your own custom value object to be included as a built-in feature, please submit a Pull Request.
Additionally, bug reports and feature requests can be submitted via the [GitHub Issue Tracker](https://github.com/beeyev/value-objects-php/issues).

© License
---------

[](#-license)

The MIT License (MIT). Please see [License File](https://github.com/beeyev/value-objects-php/blob/master/LICENSE.md) for more information.

---

If you love this project, please consider giving me a ⭐

[![](https://camo.githubusercontent.com/900654ea907c8a2b6f17dfd61f9bb49b27d80d8f463d36431ee48916a5a4db88/68747470733a2f2f76697369746f722d62616467652e6c616f62692e6963752f62616467653f706167655f69643d6265657965762e76616c75652d6f626a656374732d706870)](https://camo.githubusercontent.com/900654ea907c8a2b6f17dfd61f9bb49b27d80d8f463d36431ee48916a5a4db88/68747470733a2f2f76697369746f722d62616467652e6c616f62692e6963752f62616467653f706167655f69643d6265657965762e76616c75652d6f626a656374732d706870)

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance55

Moderate activity, may be stable

Popularity14

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 62.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

685d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9a2af70fa3b532c62e33f119701c2ed176b0444a67d3ef60d887e3eedc45dbcc?d=identicon)[beeyev](/maintainers/beeyev)

---

Top Contributors

[![beeyev](https://avatars.githubusercontent.com/u/326840?v=4)](https://github.com/beeyev "beeyev (5 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![alexander-tebiev](https://avatars.githubusercontent.com/u/120428878?v=4)](https://github.com/alexander-tebiev "alexander-tebiev (1 commits)")

---

Tags

value objectsdddValueObject

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/beeyev-value-objects-php/health.svg)

```
[![Health](https://phpackages.com/badges/beeyev-value-objects-php/health.svg)](https://phpackages.com/packages/beeyev-value-objects-php)
```

###  Alternatives

[prooph/service-bus

PHP Enterprise Service Bus Implementation supporting CQRS and DDD

4421.4M32](/packages/prooph-service-bus)[ecotone/ecotone

Supporting you in building DDD, CQRS, Event Sourcing applications with ease.

558549.8k17](/packages/ecotone-ecotone)[prooph/event-sourcing

PHP EventSourcing library

267808.5k18](/packages/prooph-event-sourcing)[phpmentors/domain-kata

Kata for domain models

73426.9k9](/packages/phpmentors-domain-kata)[aura/payload

A Domain Payload implementation.

56370.4k9](/packages/aura-payload)[serendipity_hq/component-value-objects

A set of value objects to manage simple and composite values

20558.6k4](/packages/serendipity-hq-component-value-objects)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)