https://github.com/mle86/php-value
PHP Immutable Value Object base class
https://github.com/mle86/php-value
base-class immutable-objects immutable-values php php-library php7
Last synced: 11 months ago
JSON representation
PHP Immutable Value Object base class
- Host: GitHub
- URL: https://github.com/mle86/php-value
- Owner: mle86
- License: mit
- Created: 2015-08-25T13:12:29.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-12-21T09:04:28.000Z (about 4 years ago)
- Last Synced: 2025-02-16T19:02:34.719Z (11 months ago)
- Topics: base-class, immutable-objects, immutable-values, php, php-library, php7
- Language: PHP
- Size: 88.9 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# php-value
[](https://travis-ci.org/mle86/php-value)
[](https://coveralls.io/github/mle86/php-value?branch=master)
[](https://packagist.org/packages/mle86/value)
[](https://php.net/)
[](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:
```php
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:
Via Composer: `composer require mle86/value`
Or insert this into your project's `composer.json` file:
```json
"require": {
"mle86/value": "^2"
}
```
# Minimum PHP version:
PHP 7.0
# Classes and interfaces:
1. [Value](#value) (interface)
1. [AbstractValue](#abstractvalue) (abstract class)
1. [AbstractSerializableValue](#abstractserializablevalue) (abstract class)
1. [InvalidArgumentException](#invalidargumentexception) (exception)
1. [NotImplementedException](#notimplementedexception) (exception)
## Value
This interface specifies that all Value classes should have
* a constructor which takes exactly one argument,
* a value() method without arguments.
## 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
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
An empty extension of PHP's `InvalidArgumentException`.