Refactor integer types and namespaces; migrate to custom Assert and TypeException classes

- Renamed and reorganized namespaces for consistency, removing redundant prefixes.
- Replaced usage of `Webmozart\Assert` with a custom `Assert` class for tailored integer validations.
- Introduced and standardized the `TypeException` class across all integer types.
- Refactored `PositiveInt`, `NonNegativeInt`, and `WeekDayInt` to improve validation strictness and handling.
- Enhanced test cases with additional scenarios and updated exception expectations.
- Updated documentation (`README.md`, `INSTALL.md`, `USAGE.md`) to align with the new structure and behavior.
- Adjusted `composer.json` and `composer.lock` to reflect dependency changes.
- Improved autoloading and refined the `psalm.xml` configuration for better static analysis.

Author: georgedeploy

README.md

@@ -9,6 +9,7 @@ Typed value objects for common PHP data types. Make primitives explicit, safe, a
 
 Quick links:
 - Install: docs/INSTALL.md
+- Usage: docs/USAGE.md
 - Development: docs/DEVELOP.md
 
 Install
@@ -26,22 +27,32 @@ Usage
 Create and use typed integers with validation built in.
 
 ```php
-use GeorgiiWeb\\PhpTypedValues\\Types\\Integer\\PositiveInt;
-use GeorgiiWeb\\PhpTypedValues\\Types\\Integer\\NonNegativeInt;
-use GeorgiiWeb\\PhpTypedValues\\Types\\Integer\\Nullable\\PositiveIntOrNull;
+use PhpTypedValues\\Integer\\PositiveInt;
+use PhpTypedValues\\Integer\\NonNegativeInt;
+use PhpTypedValues\\Integer\\WeekDayInt;
+use PhpTypedValues\\Integer\\Integer;
 
-$age = new PositiveInt(27);          // ok
-$retries = new NonNegativeInt(0);    // ok
+$age = new PositiveInt(27);          // ok (positive-int)
+$retries = new NonNegativeInt(0);    // ok (0 or positive)
+$weekday = new WeekDayInt(5);        // ok (1..7)
+$any = new Integer(-42);             // ok (any integer)
 
-// Nullable wrapper: accepts PositiveInt or null semantics
-$maybeCount = new PositiveIntOrNull(null);  // ok
-$maybeCount = new PositiveIntOrNull(5);     // ok
+// Construct from string
+$fromString = PositiveInt::fromString('123');
 
 // Access the underlying scalar value
 $ageValue = $age->value(); // 27
+echo $weekday->toString(); // "5"
 ```
 
-All value objects are immutable; invalid input throws an InvalidArgumentException.
+All value objects are immutable; invalid input throws an exception with a helpful message.
+
+Provided integer types (so far):
+
+- Integer — any PHP integer
+- PositiveInt — positive integer (> 0)
+- NonNegativeInt — zero or positive integer (>= 0)
+- WeekDayInt — integer in range 1..7
 
 Why
 ---

composer.json

@@ -4,8 +4,14 @@
   "type": "library",
   "license": "MIT",
   "require": {
-    "php": ">=8.2",
-    "webmozart/assert": "^1.12"
+    "php": ">=8.2"
+  },
+  "require-dev": {
+    "friendsofphp/php-cs-fixer": "^v3.89",
+    "pestphp/pest": "^v3.8.4",
+    "pestphp/pest-plugin-type-coverage": "^v3.6",
+    "phpunit/phpunit": "^11.5",
+    "vimeo/psalm": "^6.13.1"
   },
   "autoload": {
     "psr-4": {
@@ -17,13 +23,6 @@
       "PhpTypedValues\\Tests\\": "tests/"
     }
   },
-  "require-dev": {
-    "friendsofphp/php-cs-fixer": "^v3.89",
-    "pestphp/pest": "^v3.8.4",
-    "pestphp/pest-plugin-type-coverage": "^v3.6",
-    "phpunit/phpunit": "^11.5",
-    "vimeo/psalm": "^6.13.1"
-  },
   "scripts": {
     "sca": [
       "vendor/bin/psalm --no-cache --config=psalm.xml --diff --show-info=false --threads=2 --no-cache"

composer.lock

@@ -19,7 +19,7 @@ composer require georgii-web/php-typed-values
 That’s it. Composer will autoload classes under the namespace:
 
 ```
-GeorgiiWeb\PhpTypedValues
+PhpTypedValues
 ```
 
 Quick verification
@@ -31,7 +31,7 @@ Create a quick test script (e.g., demo.php):
 <?php
 require __DIR__ . '/vendor/autoload.php';
 
-use GeorgiiWeb\PhpTypedValues\Types\Integer\PositiveInt;
+use PhpTypedValues\Integer\PositiveInt;
 
 $age = new PositiveInt(21);
 echo $age->value(); // 21

docs/INSTALL.md

@@ -0,0 +1,61 @@
+Usage
+=====
+
+This page shows concise, up-to-date examples for the available integer value objects.
+
+Namespaces
+----------
+
+All classes live under the base namespace:
+
+```
+PhpTypedValues
+```
+
+Available integer types
+-----------------------
+
+- PhpTypedValues\Integer\Integer — any PHP integer
+- PhpTypedValues\Integer\PositiveInt — positive integer (> 0)
+- PhpTypedValues\Integer\NonNegativeInt — zero or positive integer (>= 0)
+- PhpTypedValues\Integer\WeekDayInt — integer in range 1..7
+
+Quick start
+-----------
+
+```php
+use PhpTypedValues\Integer\Integer;
+use PhpTypedValues\Integer\NonNegativeInt;
+use PhpTypedValues\Integer\PositiveInt;
+use PhpTypedValues\Integer\WeekDayInt;
+
+$any = new Integer(-10);          // ok
+$pos = new PositiveInt(1);        // ok
+$nn  = new NonNegativeInt(0);     // ok
+$wd  = new WeekDayInt(7);         // ok (1..7)
+
+// From string
+$posFromString = PositiveInt::fromString('123');
+
+// Accessing the raw value and string form
+echo $pos->value();     // 1
+echo $wd->toString();   // "7"
+```
+
+Validation errors
+-----------------
+
+Invalid input throws an exception with a helpful message.
+
+```php
+use PhpTypedValues\Integer\PositiveInt;
+
+new PositiveInt(0);     // throws: Value must be a positive integer
+PositiveInt::fromString('12.3'); // throws: String has no valid integer
+```
+
+Notes
+-----
+
+- All value objects are immutable (readonly) and type-safe.
+- Utility constructors: fromInt(int) and fromString(string) are provided where applicable.

docs/USAGE.md

@@ -19,5 +19,8 @@
         <include>
             <directory>src</directory>
         </include>
+        <exclude>
+            <file>src/psalmTest.php</file>
+        </exclude>
     </source>
 </phpunit>

phpunit.xml

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Code\Assert;
+
+use PhpTypedValues\Code\Exception\TypeException;
+
+use function is_numeric;
+
+final class Assert
+{
+    /**
+     * @throws TypeException
+     */
+    public static function greaterThanEq(int|float $value, int|float $min, string $message = ''): void
+    {
+        if ($value < $min) {
+            throw new TypeException($message !== '' ? $message : 'Expected a value greater than or equal to the minimum');
+        }
+    }
+
+    /**
+     * @throws TypeException
+     */
+    public static function lessThanEq(int|float $value, int|float $max, string $message = ''): void
+    {
+        if ($value > $max) {
+            throw new TypeException($message !== '' ? $message : 'Expected a value less than or equal to the maximum');
+        }
+    }
+
+    //    /**
+    //     * @throws TypeException
+    //     */
+    //    public static function greaterThan(int|float $value, int|float $min, string $message = ''): void
+    //    {
+    //        if ($value <= $min) {
+    //            throw new TypeException($message !== '' ? $message : 'Expected a value greater than the minimum');
+    //        }
+    //    }
+    //
+    //    /**
+    //     * @throws TypeException
+    //     */
+    //    public static function lessThan(int|float $value, int|float $max, string $message = ''): void
+    //    {
+    //        if ($value >= $max) {
+    //            throw new TypeException($message !== '' ? $message : 'Expected a value less than the maximum');
+    //        }
+    //    }
+
+    /**
+     * Assert that the given value looks like an integer ("integerish").
+     * Accepts numeric strings that represent an integer value (e.g., '5', '5.0'),
+     * but rejects non-numeric strings and floats with a fractional part (e.g., '5.5').
+     *
+     * @throws TypeException
+     */
+    public static function integerish(mixed $value, string $message = ''): void
+    {
+        if (!is_numeric($value) || $value != (int) $value) {
+            throw new TypeException($message !== '' ? $message : 'Expected an "integerish" value');
+        }
+    }
+}

src/Code/Assert/Assert.php

@@ -2,19 +2,22 @@
 
 declare(strict_types=1);
 
-namespace PhpTypedValues\BaseType;
+namespace PhpTypedValues\Code\BaseType;
 
-use PhpTypedValues\Contract\IntTypeInterface;
-use Webmozart\Assert\Assert;
+use PhpTypedValues\Code\Assert\Assert;
+use PhpTypedValues\Code\Contract\IntTypeInterface;
+use PhpTypedValues\Code\Exception\TypeException;
 
 /**
  * @psalm-immutable
  */
 abstract readonly class BaseIntType implements IntTypeInterface
 {
+    /**
+     * @throws TypeException
+     */
     protected static function assertNumericString(string $value): void
     {
-        //        Assert::numeric($value, 'String has no valid integer');
         Assert::integerish($value, 'String has no valid integer');
     }