WIP state machine pattern for generators

Author: bram-pkg

src/Container/Container.php

@@ -14,17 +14,20 @@
 final class Container implements ContainerInterface
 {
     /**
-     * @var array<string, callable|object|string>
+     * @var array<string, callable(): Extension|Extension|class-string<Extension>>
      */
-    private $definitions;
+    private array $definitions;
 
-    private $services = [];
+    /**
+     * @var array<string, mixed>
+     */
+    private array $services = [];
 
     /**
      * Create a container object with a set of definitions. The array value MUST
      * produce an object that implements Extension.
      *
-     * @param array<string, callable|object|string> $definitions
+     * @param array<string, callable(): Extension|Extension|class-string<Extension>> $definitions
      */
     public function __construct(array $definitions)
     {
@@ -41,15 +44,8 @@ public function __construct(array $definitions)
      * @throws ContainerException
      * @throws NotInContainerException
      */
-    public function get($id): Extension
+    public function get(string $id): Extension
     {
-        if (!is_string($id)) {
-            throw new \InvalidArgumentException(sprintf(
-                'First argument of %s::get() must be string',
-                self::class
-            ));
-        }
-
         if (array_key_exists($id, $this->services)) {
             return $this->services[$id];
         }
@@ -79,9 +75,13 @@ public function get($id): Extension
     /**
      * Get the service from a definition.
      *
-     * @param callable|object|string $definition
+     * @template T of \Faker\Core\Extension\Extension
+     *
+     * @param callable(): T|T|class-string<T> $definition
+     *
+     * @return T
      */
-    private function getService($id, $definition)
+    private function getService(string $id, callable|object|string $definition): object
     {
         if (is_callable($definition)) {
             try {
@@ -121,22 +121,17 @@ private function getService($id, $definition)
      *
      * @param string $id
      *
-     * @throws \InvalidArgumentException
+     * @return bool
      */
-    public function has($id): bool
+    public function has(string $id): bool
     {
-        if (!is_string($id)) {
-            throw new \InvalidArgumentException(sprintf(
-                'First argument of %s::get() must be string',
-                self::class
-            ));
-        }
-
         return array_key_exists($id, $this->definitions);
     }
 
     /**
      * Get the bindings between Extension interfaces and implementations.
+     *
+     * @return array<string, callable(): Extension|Extension|class-string<Extension>>
      */
     public function getDefinitions(): array
     {

src/Container/ContainerBuilder.php

@@ -4,14 +4,14 @@
 
 namespace Faker\Core\Container;
 
+use Faker\Core\Extension\Extension;
 use Faker\Core\Implementation;
 use Faker\Core\Extension\BarcodeExtension;
 use Faker\Core\Extension\BloodExtension;
 use Faker\Core\Extension\ColorExtension;
 use Faker\Core\Extension\DateTimeExtension;
 use Faker\Core\Extension\FileExtension;
 use Faker\Core\Extension\NumberExtension;
-use Faker\Core\Extension\UuidExtension;
 use Faker\Core\Extension\VersionExtension;
 
 /**
@@ -20,24 +20,17 @@
 final class ContainerBuilder
 {
     /**
-     * @var array<string, callable|object|string>
+     * @var array<string, callable|object|class-string>
      */
-    private $definitions = [];
+    private array $definitions = [];
 
     /**
-     * @param callable|object|string $value
+     * @param callable|object|class-string $value
      *
      * @throws \InvalidArgumentException
      */
-    public function add($value, string $name = null): self
+    public function add(callable|object|string $value, string $name = null): self
     {
-        if (!is_string($value) && !is_callable($value) && !is_object($value)) {
-            throw new \InvalidArgumentException(sprintf(
-                'First argument to "%s::add()" must be a string, callable or object.',
-                self::class
-            ));
-        }
-
         if ($name === null) {
             if (is_string($value)) {
                 $name = $value;
@@ -64,6 +57,8 @@ public function build(): ContainerInterface
     /**
      * Get an array with extension that represent the default English
      * functionality.
+     *
+     * @return array<class-string<Extension>, class-string<Extension>>
      */
     public static function defaultExtensions(): array
     {
@@ -75,7 +70,6 @@ public static function defaultExtensions(): array
             FileExtension::class => Implementation\File::class,
             NumberExtension::class => Implementation\Number::class,
             VersionExtension::class => Implementation\Version::class,
-            UuidExtension::class => Implementation\Uuid::class,
         ];
     }
 

src/Container/ContainerInterface.php

@@ -8,6 +8,8 @@ interface ContainerInterface extends BaseContainerInterface
 {
     /**
      * Get the bindings between Extension interfaces and implementations.
+     *
+     * @return array<class-string, class-string>
      */
     public function getDefinitions(): array;
 }

src/Generator.php src/DefaultGenerator.php

@@ -13,8 +13,10 @@
 use Faker\Core\Extension\FileExtension;
 use Faker\Core\Extension\GeneratorAwareExtension;
 use Faker\Core\Extension\NumberExtension;
-use Faker\Core\Extension\UuidExtension;
 use Faker\Core\Extension\VersionExtension;
+use Faker\Core\Generator\ChanceGenerator;
+use Faker\Core\Generator\UniqueGenerator;
+use Faker\Core\Generator\ValidGenerator;
 
 /**
  * @mixin BarcodeExtension
@@ -24,9 +26,8 @@
  * @mixin FileExtension
  * @mixin NumberExtension
  * @mixin VersionExtension
- * @mixin UuidExtension
  */
-class Generator
+class DefaultGenerator
 {
     protected array $formatters = [];
 
@@ -38,13 +39,12 @@ public function __construct(ContainerInterface $container = null)
     }
 
     /**
-     * @template T of Extension\Extension
+     * @template T of \Faker\Core\Extension\Extension
      *
      * @param class-string<T> $id
      *
      * @return T
      * @throws ExtensionNotFound
-     *
      */
     public function ext(string $id): Extension
     {
@@ -74,17 +74,17 @@ public function ext(string $id): Extension
      * </code>
      *
      * @param bool $reset If set to true, resets the list of existing values
-     * @param int $maxRetries Maximum number of retries to find a unique value,
+     * @param int $retries Maximum number of retries to find a unique value,
      *                         After which an OverflowException is thrown.
      *
      * @return self A proxy class returning only non-existing values
      * @throws \OverflowException When no unique value can be found by iterating $maxRetries times
      *
      */
-    public function unique($reset = false, $maxRetries = 10000)
+    public function unique(bool $reset = false, int $retries = 10000)
     {
         if ($reset || $this->uniqueGenerator === null) {
-            $this->uniqueGenerator = new UniqueGenerator($this, $maxRetries);
+            $this->uniqueGenerator = new UniqueGenerator($this, $retries);
         }
 
         return $this->uniqueGenerator;
@@ -117,7 +117,7 @@ public function optional(float $weight = 0.5, $default = null)
      *   $values []= $faker->valid($evenValidator)->randomDigit;
      * }
      * print_r($values); // [0, 4, 8, 4, 2, 6, 0, 8, 8, 6]
-     * </code>
+     * </code>a
      *
      * @param ?\Closure $validator A function returning true for valid values
      * @param int $maxRetries Maximum number of retries to find a valid value,
@@ -151,7 +151,7 @@ public function format($format, $arguments = [])
      *
      * @return callable
      */
-    public function getFormatter($format): callable
+    public function getFormatter(string $format): callable
     {
         if (isset($this->formatters[$format])) {
             return $this->formatters[$format];
@@ -180,7 +180,7 @@ public function getFormatter($format): callable
      *
      * @return string
      */
-    public function parse($string)
+    public function parse(string $string): string
     {
         $callback = function ($matches) {
             return $this->format($matches[1]);
@@ -189,4 +189,18 @@ public function parse($string)
         return preg_replace_callback('/{{\s?(\w+|[\w\\\]+->\w+?)\s?}}/u', $callback, $string);
     }
 
+    public function __call(string $name, array $arguments)
+    {
+        return $this->format($name, $arguments);
+    }
+
+    public function __destruct()
+    {
+        $this->seed();
+    }
+
+    public function __wakeup(): void
+    {
+        $this->formatters = [];
+    }
 }

src/Extension/GeneratorAwareExtension.php

@@ -4,7 +4,7 @@
 
 namespace Faker\Core\Extension;
 
-use Faker\Core\Generator;
+use Faker\Core\DefaultGenerator;
 
 /**
  * @experimental This interface is experimental and does not fall under our BC promise
@@ -14,7 +14,8 @@ interface GeneratorAwareExtension extends Extension
     /**
      * This method MUST be implemented in such a way as to retain the
      * immutability of the extension, and MUST return an instance that has the
-     * new Generator.
+     * new DefaultGenerator.
      */
-    public function withGenerator(Generator $generator): Extension;
+    // TODO: make generator more generic, with different generation strategies
+    public function withGenerator(DefaultGenerator $generator): Extension;
 }

src/Extension/GeneratorAwareExtensionTrait.php

@@ -5,22 +5,22 @@
 namespace Faker\Core\Extension;
 
 
-use Faker\Core\Generator;
+use Faker\Core\DefaultGenerator;
 
 /**
  * A helper trait to be used with GeneratorAwareExtension.
  */
 trait GeneratorAwareExtensionTrait
 {
     /**
-     * @var Generator|null
+     * @var DefaultGenerator
      */
     private $generator;
 
     /**
      * @return static
      */
-    public function withGenerator(Generator $generator): Extension
+    public function withGenerator(DefaultGenerator $generator): Extension
     {
         $instance = clone $this;
 

src/Extension/Helper.php

@@ -11,8 +11,10 @@ final class Helper
 {
     /**
      * Returns a random element from a passed array.
+     *
+     * @param array<int|string, mixed> $array
      */
-    public static function randomElement(array $array)
+    public static function randomElement(array $array): mixed
     {
         if ($array === []) {
             return null;

src/ChanceGenerator.php src/Generator/ChanceGenerator.php

@@ -1,14 +1,15 @@
 <?php
 
-namespace Faker\Core;
+namespace Faker\Core\Generator;
 
+use Faker\Core\DefaultGenerator;
 use Faker\Core\Extension\Extension;
 
 /**
  * This generator returns a default value for all called properties
- * and methods. It works with Faker\Generator::optional().
+ * and methods. It works with Faker\DefaultGenerator::optional().
  *
- * @mixin Generator
+ * @mixin DefaultGenerator
  */
 class ChanceGenerator
 {
@@ -17,7 +18,7 @@ class ChanceGenerator
     protected $default;
 
     /**
-     * @param Extension|Generator $generator
+     * @param Extension|DefaultGenerator $generator
      */
     public function __construct($generator, float $weight, $default = null)
     {