feat: allow abstract value to parse value before it is accepted

Author: lindyhopchris

CHANGELOG.md

@@ -9,7 +9,11 @@ All notable changes to this project will be documented in this file. This projec
 
 - Minimum PHP version is now 8.2.
 - Added generics to the value interface, abstract class and trait. This will be breaking if you are running PHPStan.
-- **BREAKING**: The abstract value and value trait are now both readonly. This is because value objects should always be immutable.
+- **BREAKING**: The abstract value and value trait are now both readonly. This is because value objects should always be
+  immutable.
+- **BREAKING**: The abstract value constructor is now final. If you need to parse the provided value before it is
+  accepted, overload the `parse()` method in your class. Alternatively, don't extend the `AbstractValue` and use the
+  `ValueTrait` instead.
 
 ## [2.2.0] - 2022-03-04
 
@@ -51,10 +55,10 @@ This package now requires PHP 7.1 or above.
 ## Added
 
 - The following methods have been added to value objects:
-  - `toString` for fluently casting the object to a string.
-  - `isAny` to check if the value is one of any number of provided values.
-  - `isEmpty` to check if the value is empty.
-  - `isNotEmpty` to check if the value is not empty.
+    - `toString` for fluently casting the object to a string.
+    - `isAny` to check if the value is one of any number of provided values.
+    - `isEmpty` to check if the value is empty.
+    - `isNotEmpty` to check if the value is not empty.
 
 ## Deprecated
 
@@ -65,8 +69,8 @@ This package now requires PHP 7.1 or above.
 ### Added
 
 - The following static methods have been added to both abstract classes:
-  - `create` which is a fluent constructor.
-  - `cast` which ensures the provided value is an instance of `static`.
+    - `create` which is a fluent constructor.
+    - `cast` which ensures the provided value is an instance of `static`.
 
 ## [1.0.0] - 2017-01-30
 

src/AbstractValue.php

@@ -108,13 +108,26 @@ public static function nullable(mixed $value): ?static
      */
     final public function __construct(mixed $value)
     {
+        $value = $this->parse($value);
+
         if ($this->notAcceptable($value)) {
             throw new ValueException('Expecting a valid value.');
         }
 
         $this->value = $value;
     }
 
+    /**
+     * Allow the value to be parsed before it is accepted.
+     *
+     * @param mixed $value
+     * @return mixed
+     */
+    protected function parse(mixed $value): mixed
+    {
+        return $value;
+    }
+
     /**
      * Is the value not acceptable?
      *

tests/IntegerMultiplierValue.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * Copyright 2025 Cloud Creativity Limited
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://opensource.org/licenses/MIT.
+ */
+
+declare(strict_types=1);
+
+namespace CloudCreativity\Utils\Value\Tests;
+
+use CloudCreativity\Utils\Value\AbstractValue;
+
+/**
+ * @extends AbstractValue<int>
+ */
+final readonly class IntegerMultiplierValue extends AbstractValue
+{
+    protected function parse(mixed $value): mixed
+    {
+        return is_int($value) ? $value * 10 : $value;
+    }
+
+    protected function accept(mixed $value): bool
+    {
+        return is_int($value);
+    }
+}

tests/Unit/ValueTest.php

@@ -12,6 +12,7 @@
 
 namespace CloudCreativity\Utils\Value\Tests\Unit;
 
+use CloudCreativity\Utils\Value\Tests\IntegerMultiplierValue;
 use CloudCreativity\Utils\Value\Tests\IntegerValue;
 use CloudCreativity\Utils\Value\Tests\StringValue;
 use CloudCreativity\Utils\Value\ValueException;
@@ -114,4 +115,11 @@ public function testNotEmpty(): void
         $this->assertTrue($value->isNotEmpty());
         $this->assertFalse($value->isEmpty());
     }
+
+    public function testItCanSetParser(): void
+    {
+        $value = new IntegerMultiplierValue(2);
+
+        $this->assertSame(20, $value->get());
+    }
 }