Allow iterable<T> where ramsey/collection would be used, deprecate collection classes

This patch is based on https://github.com/ramsey/uuid/pull/405

As discussed in https://github.com/ramsey/uuid/pull/405#discussion_r832095457, the `ramsey/collection`
dependency can be phased out.

Doing so via direct removal is not feasible without a clear BC break, so this change only deprecates:

 * `Ramsey\Uuid\Builder\BuilderCollection`
 * `Ramsey\Uuid\Provider\Node\NodeProviderCollection`

These classes will then be removed in `5.0.0`, along with the `ramsey/collection` dependency.

src/Builder/BuilderCollection.php

@@ -27,6 +27,11 @@ use Traversable;
 /**
  * A collection of UuidBuilderInterface objects
  *
+ * @deprecated this class has been deprecated, and will be removed in 5.0.0. The use-case for this class comes from
+ *             a pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced
+ *             at runtime: that is no longer necessary, now that you can safely verify your code to be correct, and use
+ *             more generic types like `iterable<T>` instead.
+ *
  * @extends AbstractCollection<UuidBuilderInterface>
  */
 class BuilderCollection extends AbstractCollection

src/Builder/FallbackBuilder.php

@@ -28,14 +28,14 @@ use Ramsey\Uuid\UuidInterface;
 class FallbackBuilder implements UuidBuilderInterface
 {
     /**
-     * @var BuilderCollection
+     * @var iterable<UuidBuilderInterface>
      */
     private $builders;
 
     /**
-     * @param BuilderCollection $builders An array of UUID builders
+     * @param iterable<UuidBuilderInterface> $builders An array of UUID builders
      */
-    public function __construct(BuilderCollection $builders)
+    public function __construct(iterable $builders)
     {
         $this->builders = $builders;
     }

src/FeatureSet.php

@@ -14,7 +14,6 @@ declare(strict_types=1);
 
 namespace Ramsey\Uuid;
 
-use Ramsey\Uuid\Builder\BuilderCollection;
 use Ramsey\Uuid\Builder\FallbackBuilder;
 use Ramsey\Uuid\Builder\UuidBuilderInterface;
 use Ramsey\Uuid\Codec\CodecInterface;
@@ -43,7 +42,6 @@ use Ramsey\Uuid\Nonstandard\UuidBuilder as NonstandardUuidBuilder;
 use Ramsey\Uuid\Provider\Dce\SystemDceSecurityProvider;
 use Ramsey\Uuid\Provider\DceSecurityProviderInterface;
 use Ramsey\Uuid\Provider\Node\FallbackNodeProvider;
-use Ramsey\Uuid\Provider\Node\NodeProviderCollection;
 use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
 use Ramsey\Uuid\Provider\Node\SystemNodeProvider;
 use Ramsey\Uuid\Provider\NodeProviderInterface;
@@ -350,10 +348,10 @@ class FeatureSet
             return new RandomNodeProvider();
         }
 
-        return new FallbackNodeProvider(new NodeProviderCollection([
+        return new FallbackNodeProvider([
             new SystemNodeProvider(),
             new RandomNodeProvider(),
-        ]));
+        ]);
     }
 
     /**
@@ -432,11 +430,10 @@ class FeatureSet
             return new GuidBuilder($this->numberConverter, $this->timeConverter);
         }
 
-        /** @psalm-suppress ImpureArgument */
-        return new FallbackBuilder(new BuilderCollection([
+        return new FallbackBuilder([
             new Rfc4122UuidBuilder($this->numberConverter, $this->timeConverter),
             new NonstandardUuidBuilder($this->numberConverter, $this->timeConverter),
-        ]));
+        ]);
     }
 
     /**

src/Provider/Node/FallbackNodeProvider.php

@@ -25,14 +25,14 @@ use Ramsey\Uuid\Type\Hexadecimal;
 class FallbackNodeProvider implements NodeProviderInterface
 {
     /**
-     * @var NodeProviderCollection
+     * @var iterable<NodeProviderInterface>
      */
     private $nodeProviders;
 
     /**
-     * @param NodeProviderCollection $providers Array of node providers
+     * @param iterable<NodeProviderInterface> $providers Array of node providers
      */
-    public function __construct(NodeProviderCollection $providers)
+    public function __construct(iterable $providers)
     {
         $this->nodeProviders = $providers;
     }

src/Provider/Node/NodeProviderCollection.php

@@ -21,6 +21,11 @@ use Ramsey\Uuid\Type\Hexadecimal;
 /**
  * A collection of NodeProviderInterface objects
  *
+ * @deprecated this class has been deprecated, and will be removed in 5.0.0. The use-case for this class comes from
+ *             a pre-`phpstan/phpstan` and pre-`vimeo/psalm` ecosystem, in which type safety had to be mostly enforced
+ *             at runtime: that is no longer necessary, now that you can safely verify your code to be correct, and use
+ *             more generic types like `iterable<T>` instead.
+ *
  * @extends AbstractCollection<NodeProviderInterface>
  */
 class NodeProviderCollection extends AbstractCollection

tests/Builder/FallbackBuilderTest.php

@@ -6,7 +6,6 @@ namespace Ramsey\Uuid\Test\Builder;
 
 use DateTimeInterface;
 use Mockery;
-use Ramsey\Uuid\Builder\BuilderCollection;
 use Ramsey\Uuid\Builder\FallbackBuilder;
 use Ramsey\Uuid\Builder\UuidBuilderInterface;
 use Ramsey\Uuid\Codec\CodecInterface;
@@ -53,7 +52,7 @@ class FallbackBuilderTest extends TestCase
             ->with($codec, $bytes)
             ->andThrow(UnableToBuildUuidException::class);
 
-        $fallbackBuilder = new FallbackBuilder(new BuilderCollection([$builder1, $builder2, $builder3]));
+        $fallbackBuilder = new FallbackBuilder([$builder1, $builder2, $builder3]);
 
         $this->expectException(BuilderNotFoundException::class);
         $this->expectExceptionMessage(
@@ -83,25 +82,16 @@ class FallbackBuilderTest extends TestCase
         $rfc4122Builder2 = new Rfc4122UuidBuilder($genericNumberConverter, $phpTimeConverter);
         $nonstandardBuilder2 = new NonstandardUuidBuilder($genericNumberConverter, $phpTimeConverter);
 
-        $builderCollection = new BuilderCollection(
-            [
-                $guidBuilder,
-                $guidBuilder2,
-                $rfc4122Builder,
-                $rfc4122Builder2,
-                $nonstandardBuilder,
-                $nonstandardBuilder2,
-            ]
-        );
+        /** @var list<UuidBuilderInterface> $unserializedBuilderCollection */
+        $unserializedBuilderCollection = unserialize(serialize([
+            $guidBuilder,
+            $guidBuilder2,
+            $rfc4122Builder,
+            $rfc4122Builder2,
+            $nonstandardBuilder,
+            $nonstandardBuilder2,
+        ]));
 
-        $serializedBuilderCollection = serialize($builderCollection);
-
-        /** @var BuilderCollection $unserializedBuilderCollection */
-        $unserializedBuilderCollection = unserialize($serializedBuilderCollection);
-
-        $this->assertInstanceOf(BuilderCollection::class, $unserializedBuilderCollection);
-
-        /** @var UuidBuilderInterface $builder */
         foreach ($unserializedBuilderCollection as $builder) {
             $codec = new StringCodec($builder);
 

tests/Provider/Node/FallbackNodeProviderTest.php

@@ -6,7 +6,6 @@ namespace Ramsey\Uuid\Test\Provider\Node;
 
 use Ramsey\Uuid\Exception\NodeException;
 use Ramsey\Uuid\Provider\Node\FallbackNodeProvider;
-use Ramsey\Uuid\Provider\Node\NodeProviderCollection;
 use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
 use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
 use Ramsey\Uuid\Provider\Node\SystemNodeProvider;
@@ -27,7 +26,7 @@ class FallbackNodeProviderTest extends TestCase
             ->method('getNode')
             ->willThrowException(new NodeException());
 
-        $provider = new FallbackNodeProvider(new NodeProviderCollection([$providerWithoutNode, $providerWithNode]));
+        $provider = new FallbackNodeProvider([$providerWithoutNode, $providerWithNode]);
         $provider->getNode();
     }
 
@@ -45,9 +44,7 @@ class FallbackNodeProviderTest extends TestCase
         $anotherProviderWithoutNode->expects($this->never())
             ->method('getNode');
 
-        $provider = new FallbackNodeProvider(new NodeProviderCollection(
-            [$providerWithoutNode, $providerWithNode, $anotherProviderWithoutNode]
-        ));
+        $provider = new FallbackNodeProvider([$providerWithoutNode, $providerWithNode, $anotherProviderWithoutNode]);
         $node = $provider->getNode();
 
         $this->assertSame('57764a07f756', $node->toString());
@@ -59,7 +56,7 @@ class FallbackNodeProviderTest extends TestCase
         $providerWithoutNode->method('getNode')
             ->willThrowException(new NodeException());
 
-        $provider = new FallbackNodeProvider(new NodeProviderCollection([$providerWithoutNode]));
+        $provider = new FallbackNodeProvider([$providerWithoutNode]);
 
         $this->expectException(NodeException::class);
         $this->expectExceptionMessage(
@@ -75,20 +72,12 @@ class FallbackNodeProviderTest extends TestCase
         $randomNodeProvider = new RandomNodeProvider();
         $systemNodeProvider = new SystemNodeProvider();
 
-        $nodeProviderCollection = new NodeProviderCollection(
-            [
-                $staticNodeProvider,
-                $randomNodeProvider,
-                $systemNodeProvider,
-            ]
-        );
-
-        $serializedNodeProviderCollection = serialize($nodeProviderCollection);
-
-        /** @var NodeProviderCollection $unserializedNodeProviderCollection */
-        $unserializedNodeProviderCollection = unserialize($serializedNodeProviderCollection);
-
-        $this->assertInstanceOf(NodeProviderCollection::class, $unserializedNodeProviderCollection);
+        /** @var list<NodeProviderInterface> $unserializedNodeProviderCollection */
+        $unserializedNodeProviderCollection = unserialize(serialize([
+            $staticNodeProvider,
+            $randomNodeProvider,
+            $systemNodeProvider,
+        ]));
 
         foreach ($unserializedNodeProviderCollection as $nodeProvider) {
             $this->assertInstanceOf(NodeProviderInterface::class, $nodeProvider);