Merge branch 'release/3.1.0'

Author: lindyhopchris

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [3.1.0] - 2025-02-15
+
+### Added
+
+- Can now provide an enum as the type of the GUID identifier.
+- Can now provide multiple types when checking if a GUID is of a type - the `Guid::isType()` method. It returns `true`
+  if *any* of the provided types match the type of the GUID.
+- The `LazyListOfGuids` iterator now has an `only()` method. This can be provided a list of types, and the iterator will
+  yield only GUIDs with a matching type.
+
 ## [3.0.0] - 2025-01-29
 
 ### Added
@@ -392,6 +402,8 @@ All notable changes to this project will be documented in this file. This projec
 
 Initial release.
 
+[3.1.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.0.0...v3.1.0
+
 [3.0.0]: https://github.com/cloudcreativity/ddd-modules/compare/v3.0.0-rc.2...v3.0.0
 
 [3.0.0-rc.2]: https://github.com/cloudcreativity/ddd-modules/compare/v3.0.0-rc.1...v3.0.0-rc.2

composer.json

@@ -57,8 +57,8 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "2.x-dev",
-            "dev-next": "3.x-dev"
+            "dev-develop": "3.x-dev",
+            "dev-next": "4.x-dev"
         }
     },
     "minimum-stability": "stable",

src/Toolkit/Identifiers/Guid.php

@@ -12,10 +12,12 @@
 
 namespace CloudCreativity\Modules\Toolkit\Identifiers;
 
+use BackedEnum;
 use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
 use CloudCreativity\Modules\Toolkit\ContractException;
 use CloudCreativity\Modules\Toolkit\Contracts;
 use Ramsey\Uuid\UuidInterface;
+use UnitEnum;
 
 final class Guid implements Identifier
 {
@@ -35,47 +37,47 @@ public static function from(Identifier $value): self
     /**
      * Create a GUID with an integer id.
      *
-     * @param string $type
+     * @param UnitEnum|string $type
      * @param int $id
-     * @return static
+     * @return self
      */
-    public static function fromInteger(string $type, int $id): self
+    public static function fromInteger(UnitEnum|string $type, int $id): self
     {
         return new self($type, new IntegerId($id));
     }
 
     /**
      * Create a GUID with a string id.
      *
-     * @param string $type
+     * @param UnitEnum|string $type
      * @param string $id
-     * @return static
+     * @return self
      */
-    public static function fromString(string $type, string $id): self
+    public static function fromString(UnitEnum|string $type, string $id): self
     {
         return new self($type, new StringId($id));
     }
 
     /**
      * Create a GUID for a UUID.
      *
-     * @param string $type
+     * @param UnitEnum|string $type
      * @param UuidInterface|string $uuid
      * @return self
      */
-    public static function fromUuid(string $type, UuidInterface|string $uuid): self
+    public static function fromUuid(UnitEnum|string $type, UuidInterface|string $uuid): self
     {
         return new self($type, Uuid::from($uuid));
     }
 
     /**
      * Create a GUID.
      *
-     * @param string $type
+     * @param UnitEnum|string $type
      * @param string|int $id
      * @return self
      */
-    public static function make(string $type, string|int $id): self
+    public static function make(UnitEnum|string $type, string|int $id): self
     {
         if (is_int($id)) {
             return self::fromInteger($type, $id);
@@ -87,11 +89,11 @@ public static function make(string $type, string|int $id): self
     /**
      * Guid constructor.
      *
-     * @param string $type
+     * @param UnitEnum|string $type
      * @param StringId|IntegerId|Uuid $id
      */
     public function __construct(
-        public readonly string $type,
+        public readonly UnitEnum|string $type,
         public readonly StringId|IntegerId|Uuid $id,
     ) {
         Contracts::assert(!empty($this->type), 'Type must be a non-empty string.');
@@ -106,12 +108,18 @@ public function __toString(): string
     }
 
     /**
-     * @param string $type
+     * @param UnitEnum|string ...$types
      * @return bool
      */
-    public function isType(string $type): bool
+    public function isType(UnitEnum|string ...$types): bool
     {
-        return $this->type === $type;
+        foreach ($types as $type) {
+            if ($this->type === $type) {
+                return true;
+            }
+        }
+
+        return false;
     }
 
     /**
@@ -149,7 +157,9 @@ public function equals(self $other): bool
      */
     public function toString(string $glue = ':'): string
     {
-        return "{$this->type}{$glue}{$this->id->value}";
+        $type = $this->type();
+
+        return "{$type}{$glue}{$this->id->value}";
     }
 
     /**
@@ -166,26 +176,44 @@ public function key(): string
     public function context(): array
     {
         return [
-            'type' => $this->type,
+            'type' => $this->type(),
             'id' => $this->id->context(),
         ];
     }
 
     /**
      * Assert that this GUID is of the expected type.
      *
-     * @param string $expected
+     * @param UnitEnum|string $expected
      * @param string $message
      * @return $this
      */
-    public function assertType(string $expected, string $message = ''): self
+    public function assertType(UnitEnum|string $expected, string $message = ''): self
     {
         Contracts::assert($this->type === $expected, $message ?: sprintf(
             'Expecting type "%s", received "%s".',
-            $expected,
-            $this->type,
+            match (true) {
+                $expected instanceof BackedEnum => $expected->value,
+                $expected instanceof UnitEnum => $expected->name,
+                default => $expected,
+            },
+            $this->type(),
         ));
 
         return $this;
     }
+
+    /**
+     * Get the type expressed as a string or an integer.
+     *
+     * @return string|int
+     */
+    public function type(): string|int
+    {
+        return match (true) {
+            $this->type instanceof BackedEnum => $this->type->value,
+            $this->type instanceof UnitEnum => $this->type->name,
+            default => $this->type,
+        };
+    }
 }

src/Toolkit/Identifiers/LazyListOfGuids.php

@@ -12,11 +12,13 @@
 
 namespace CloudCreativity\Modules\Toolkit\Identifiers;
 
+use BackedEnum;
 use Closure;
 use CloudCreativity\Modules\Contracts\Toolkit\Iterables\LazyList;
 use CloudCreativity\Modules\Toolkit\Contracts;
 use CloudCreativity\Modules\Toolkit\Iterables\IsLazyList;
 use Generator;
+use UnitEnum;
 
 /**
  * @implements LazyList<Guid>
@@ -39,21 +41,42 @@ public function __construct(?Closure $source = null)
     /**
      * Ensure all GUIDs are of the expected type.
      *
-     * @param string $expected
+     * @param UnitEnum|string $expected
      * @param string $message
      * @return self
      */
-    public function ofOneType(string $expected, string $message = ''): self
+    public function ofOneType(UnitEnum|string $expected, string $message = ''): self
     {
         return new self(function () use ($expected, $message) {
             foreach ($this as $guid) {
                 Contracts::assert($guid->isType($expected), $message ?: sprintf(
                     'Expecting GUIDs of type "%s", found "%s".',
-                    $expected,
-                    $guid->type,
+                    match (true) {
+                        $expected instanceof BackedEnum => $expected->value,
+                        $expected instanceof UnitEnum => $expected->name,
+                        default => $expected,
+                    },
+                    $guid->type(),
                 ));
                 yield $guid;
             }
         });
     }
+
+    /**
+     * Return a list that only contains the provided types.
+     *
+     * @param UnitEnum|string ...$types
+     * @return self
+     */
+    public function only(UnitEnum|string ...$types): self
+    {
+        return new self(function () use ($types) {
+            foreach ($this as $guid) {
+                if ($guid->isType(...$types)) {
+                    yield $guid;
+                }
+            }
+        });
+    }
 }

src/Toolkit/Iterables/IsLazyList.php

@@ -40,10 +40,16 @@ public function getIterator(): Generator
     }
 
     /**
-     * @return array<T>
+     * @return list<T>
      */
     public function all(): array
     {
-        return iterator_to_array($this->getIterator());
+        $all = [];
+
+        foreach ($this as $value) {
+            $all[] = $value;
+        }
+
+        return $all;
     }
 }

tests/Unit/Toolkit/Loggable/TestEnum.php tests/TestBackedEnum.phptests/Unit/Toolkit/Loggable/TestEnum.php renamed to tests/TestBackedEnum.php

@@ -10,10 +10,10 @@
 
 declare(strict_types=1);
 
-namespace CloudCreativity\Modules\Tests\Unit\Toolkit\Loggable;
+namespace CloudCreativity\Modules\Tests;
 
-enum TestEnum: string
+enum TestBackedEnum: string
 {
-    case Foo = 'foo';
-    case Bar = 'bar';
+    case Foo = 'foo!';
+    case Bar = 'bar!';
 }

tests/TestUnitEnum.php

@@ -0,0 +1,19 @@
+<?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\Modules\Tests;
+
+enum TestUnitEnum
+{
+    case Baz;
+    case Bat;
+}