PHPackages                             mle86/value - 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. mle86/value

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

mle86/value
===========

A base class for immutable single-value-wrapper classes

v2.3.0(7mo ago)110.1k↓66.7%1MITPHPPHP >=7.0.0CI failing

Since May 24Pushed 7mo ago1 watchersCompare

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

READMEChangelog (10)Dependencies (2)Versions (22)Used By (1)

php-value
=========

[](#php-value)

[![Build Status](https://camo.githubusercontent.com/1ff42cb803ec4a1b58aa8f297e419b30c245d13389851bb2782eb9b954856d79/68747470733a2f2f7472617669732d63692e6f72672f6d6c6538362f7068702d76616c75652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/mle86/php-value)[![Coverage Status](https://camo.githubusercontent.com/ebe48dfc057f09a9d28bf086dd727f5253234830c27903f6cfb945cf0084c5db/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6d6c6538362f7068702d76616c75652f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/mle86/php-value?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/46c2b2d5435e63cbac046a6265bf97780e5f0d960e6950d380b01e142605eaae/68747470733a2f2f706f7365722e707567782e6f72672f6d6c6538362f76616c75652f76657273696f6e)](https://packagist.org/packages/mle86/value)[![PHP 7.0](https://camo.githubusercontent.com/35a19db13582e18c272716b5707e1f6ad89f0af2fd1b490941ed83416794e19a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e302d3838393242462e7376673f7374796c653d666c6174)](https://php.net/)[![License](https://camo.githubusercontent.com/366295a90a5d7ccd2a74b39504e3913a97db24c114b729e317b21eb59a174c70/68747470733a2f2f706f7365722e707567782e6f72672f6d6c6538362f76616c75652f6c6963656e7365)](https://packagist.org/packages/mle86/value)

This PHP library provides a simple base class for Immutable Value Objects. Those are objects which wrap exactly one value, cannot be changed in any way, have no additional state, and carry some validation logic in the constructor.

It is released under the [MIT License](http://opensource.org/licenses/MIT).

Simple use case:
================

[](#simple-use-case)

```
class OddNumber extends \mle86\Value\AbstractValue
{

    // The base class requires this boolean test method:
    public static function isValid($input): bool
    {
        return (is_int($input) && ($input % 2) === 1);
    }

    // Nothing else is needed.
}

function myFunction(OddNumber $oddArgument)
{
    /* No further validation of $oddArgument is necessary in this function,
     * it's guaranteed to contain an odd number. */
    print "Got an odd number here: " . $oddArgument->value();
}

$odd1 = new OddNumber(61);       // works as expected, $odd1->value() will return 61
$odd2 = new OddNumber(40);       // throws an InvalidArgumentException
$odd3 = new OddNumber("string"); // throws an InvalidArgumentException
$odd4 = new OddNumber(null);     // throws an InvalidArgumentException

$odd5   = OddNumber::optional(33);   // works as expected, $odd5->value() will return 33
$nonodd = OddNumber::optional(null); // $nonodd is now null
$odd6   = OddNumber::optional(40);   // throws an InvalidArgumentException
```

Installation:
=============

[](#installation)

Via Composer: `composer require mle86/value`

Or insert this into your project's `composer.json` file:

```
"require": {
    "mle86/value": "^2"
}
```

Minimum PHP version:
====================

[](#minimum-php-version)

PHP 7.0

Classes and interfaces:
=======================

[](#classes-and-interfaces)

1. [Value](#value) (interface)
2. [AbstractValue](#abstractvalue) (abstract class)
3. [AbstractSerializableValue](#abstractserializablevalue) (abstract class)
4. [InvalidArgumentException](#invalidargumentexception) (exception)
5. [NotImplementedException](#notimplementedexception) (exception)

Value
-----

[](#value)

This interface specifies that all Value classes should have

- a constructor which takes exactly one argument,
- a value() method without arguments.

AbstractValue
-------------

[](#abstractvalue)

This immutable class wraps a single value per instance. The constructor enforces validity checks on the input value. Therefore, every class instance's wrapped value can be considered valid.

The validity checks are located in the isValid class method which all subclasses must implement. It is a class method to allow validity checks of external values without wrapping them in an instance.

- `public function __construct($rawValue)`

    The constructor uses the `isValid` class method to test its input argument. Valid values are stored in the new instance, invalid values cause an `InvalidArgumentException` to be thrown. Other instances of the same class are always considered valid (*re-wrapping*).
- `public static function optional($rawValue): ?static`

    Same as the default constructor, but also accepts `null` values (which will be returned unchanged).
- `abstract public static function isValid($testValue): bool`

    Checks the validity of a raw value. If it returns true, a new object can be instantiated with that value. Implement this in every subclass!
- `final public function value(): mixed`

    Returns the object's wrapped initializer value.
- `final public function equals($testValue): bool`

    Equality test. This method performs an equality check on other instances or raw values. Objects are considered equal if and only if they are instances of the same subclass and carry the same `value()`. All other values are considered equal if and only if they are identical (`===`) to the current objects's `value()`.
- `final public static function wrap(&$value)`

    Replaces a value (by-reference) with instance wrapping that value. This means of course that the call will fail with an `InvalidArgumentException` if the input value fails the subclass' `isValid` check. If the value already is an instance, it won't be replaced.
- `final public static function wrapOptional(&$value)`

    Like `wrap()`, but won't change `null` values.
- `final public static function wrapArray(array &$array): array`

    Will replace all values in an array with instances. The array will only be altered (by-reference) if all its values are valid. Array keys will be preserved.
- `final public static function wrapOptionalsArray(array &$array): array`

    Will replace all non-`null` values in an array with instances. The array will only be changed (by-reference) if all its values are valid (or `null`). Array keys will be preserved.

AbstractSerializableValue
-------------------------

[](#abstractserializablevalue)

This extension of `AbstractValue` provides easy serializability for the Value objects. It implements the [JsonSerializable](https://php.net/manual/class.jsonserializable.php) interface.

Standard PHP serialization via [serialize](https://secure.php.net/serialize)/[unserialize](https://secure.php.net/unserialize)is always supported. This class contains an extra `__wakeup()` implementation to make sure that unserialized instances always contain a valid value.

- `public function __toString(): string`

    Returns the wrapped value like `value()`, but with an explicit `string` typecast. This allows string concatenation of Value objects.
- `public function jsonSerialize(): mixed`

    Returns the wrapped value – like `value()`. This enables [json\_encode()](https://secure.php.net/json_encode) to encode the object.

InvalidArgumentException
------------------------

[](#invalidargumentexception)

An empty extension of PHP's `InvalidArgumentException`.

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance63

Regular maintenance activity

Popularity25

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 100% 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

Every ~180 days

Recently: every ~480 days

Total

20

Last Release

223d ago

Major Versions

v1.1.2 → v2.0.02019-10-23

v1.2.0 → v2.2.02019-11-28

v1.x-dev → v2.2.12020-07-05

v2.2.2 → v3.x-dev2021-12-21

PHP version history (2 changes)v1.0PHP >=5.4.0

v2.0.0PHP >=7.0.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/13321706?v=4)[mle86](/maintainers/mle86)[@mle86](https://github.com/mle86)

---

Top Contributors

[![mle86](https://avatars.githubusercontent.com/u/13321706?v=4)](https://github.com/mle86 "mle86 (76 commits)")

---

Tags

base-classimmutable-objectsimmutable-valuesphpphp-libraryphp7

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/mle86-value/health.svg)

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

PHPackages © 2026

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