- Added overridable defineInstances method to allow bulk instance definition

- Updated documentation

Author: lhellemons-sqills

docs/enums.md

@@ -32,7 +32,7 @@ class FooBarEnum implements EnumInterface
     }
 }
 
-FooBarEnum::FOO() === FooBarEnum::FOO() // true
+FooBarEnum::FOO() === FooBarEnum::FOO(); // true
 ```
 
 If you want to store extra data on your Enum instances, you can add a
@@ -75,6 +75,9 @@ class FooBarEnum implements EnumInterface
 echo FooBarEnum::FOO()->getMessage(); // outputs 'foo mama'
 ```
 
+Subclasses
+----------
+
 Enum classes can have subclasses as well, but the following caveats apply:
 - although the factory methods are inherited from the parent Enum, these
  still produce instances of the class on which they are called, so
@@ -85,3 +88,51 @@ Enum classes can have subclasses as well, but the following caveats apply:
   and any extra parameters not accepted by the parent constructor _must
   be optional_, so that the data from the parent factory methods can be
   accepted by the child constructor.
+
+Bulk definitions
+----------------
+
+Some enum classes may need a large number of instances, or even instances
+depending on some external definition, such as a CSV file. In these 
+cases, it will be tedious or even error-prone to create a separate
+factory method for each of the instances. For these cases, you can
+override the `defineInstances` method of `EnumTrait`. Inside this method
+you can call `define` multiple times to create as many instances as
+you need, like so:
+
+```php
+<?php
+
+use SolidPhp\ValueObjects\Enum\EnumTrait;
+use SolidPhp\ValueObjects\Enum\EnumInterface;
+
+class Country implements EnumInterface
+{
+    use EnumTrait;
+    
+    protected static function defineInstances() : void
+    {
+        // countries.csv:
+        // US;United States of America
+        // NL;Netherlands
+        // UK;United Kingdom
+        // ...
+        $countryDefinitions = explode("\n", file_get_contents(__DIR__ . 'countries.csv'));
+        
+        foreach ($countryDefinitions as $countryDefinition) {
+            [$code, $name] = explode(';', $countryDefinition);
+            self::define($code, $name);
+        }
+    }
+}
+```
+
+If you define your instances like this, the following caveats apply:
+
+- You can no longer use `define` in other methods. Any factory methods
+  you write will need to use `instance` or `instances` to get their
+  instances.
+- Because of this, if the class has any child classes, they also need
+  to override this method and use it to define their instances. As a consequence,
+  they can choose whether or not to include the parent class instances 
+  for themselves by calling or not calling `parent::defineInstances()` there.

src/Enum/EnumTrait.php

@@ -10,7 +10,7 @@
  * After using this Trait, the class can define public static "factory" methods to define its instances.
  *
  * For example, here is a very simple implementation:
- * ```
+ * ```php
  * class FooBarEnum implements EnumInterface
  * {
  *   use EnumTrait;
@@ -72,7 +72,7 @@ trait EnumTrait /* implements EnumInterface */
 {
     private static $instancesById;
 
-    /** @var array */
+    /** @var int[] */
     private static $allInstancesInitialized = [];
 
     /**
@@ -99,14 +99,30 @@ final protected static function define(string $id, ...$constructorArguments)
         return self::$instancesById[static::class][$id];
     }
 
+    /**
+     * This method is called the first time it's needed.
+     * It should call `define` for each instance to be created.
+     *
+     * The default behavior is to call every public factory method in the class, with
+     * the expectation that those methods will call `define`. Override this method to provide
+     * different behavior, for instance loading instances parametrically from an array or file.
+     *
+     * If you override this method, the class must be final, because child classes won't be able
+     * to add instances.
+     */
+    protected static function defineInstances(): void
+    {
+        call_all_public_nullary_factory_methods(static::class);
+    }
+
     /**
      * @param string $id
      * @param bool $throwIfNotFound
      * @return null|$this
      */
     final public static function instance(string $id, bool $throwIfNotFound = false)
     {
-        static::_ensureAllInstancesInitialized(static::class);
+        static::_ensureAllInstancesInitialized();
 
         if (isset(self::$instancesById[static::class][$id])) {
             return self::$instancesById[static::class][$id];
@@ -124,42 +140,39 @@ final public static function instance(string $id, bool $throwIfNotFound = false)
      */
     final public static function instances(): array
     {
-        static::_ensureAllInstancesInitialized(static::class);
+        static::_ensureAllInstancesInitialized();
 
         return array_values(self::$instancesById[static::class]);
     }
 
     final public function getId(): string
     {
-        static::_ensureAllInstancesInitialized(static::class);
+        static::_ensureAllInstancesInitialized();
 
-        foreach (self::$instancesById[static::class] as $id => $instance) {
-            if ($instance === $this) {
-                return $id;
-            }
-        }
-
-        return null;
+        return array_search($this, self::$instancesById[static::class], true);
     }
 
-    private static function _ensureAllInstancesInitialized(string $class): void
+    private static function _ensureAllInstancesInitialized(): void
     {
-        if (!isset(self::$allInstancesInitialized[$class])) {
-            initialize_all_enum_instances($class);
-            self::$allInstancesInitialized[$class] = true;
+        static $_isInitializing;
+        if (!$_isInitializing && !isset(self::$allInstancesInitialized[static::class])) {
+            $_isInitializing = true;
+            static::defineInstances();
+            $_isInitializing = false;
+            self::$allInstancesInitialized[static::class] = true;
         }
     }
 }
 
-function initialize_all_enum_instances(string $enumClass): void
+function call_all_public_nullary_factory_methods(string $enumClass): void
 {
     try {
         $reflectionClass = new \ReflectionClass($enumClass);
 
         /** @var \ReflectionMethod[] $factoryMethods */
         $factoryMethods = array_filter(
             $reflectionClass->getMethods(),
-            'SolidPhp\ValueObjects\Enum\is_enum_factory_method'
+            'SolidPhp\ValueObjects\Enum\is_public_nullary_factory_method'
         );
         foreach ($factoryMethods as $method) {
             $method->invoke(null);
@@ -169,7 +182,7 @@ function initialize_all_enum_instances(string $enumClass): void
     }
 }
 
-function is_enum_factory_method(\ReflectionMethod $method): bool
+function is_public_nullary_factory_method(\ReflectionMethod $method): bool
 {
     return $method->isPublic()
         && $method->isStatic()

test/Enum/Enum/EnumTest.php

@@ -48,6 +48,11 @@ public function testInheritance(): void
         $this->assertNotSame(TestInheritanceParentEnum::PARENT(), TestInheritanceChildEnum::PARENT());
         $this->assertNotSame(TestInheritanceParentEnum::PARENT(), TestInheritanceChildEnum::PARENT());
     }
+
+    public function testDefineInstances(): void
+    {
+        $this->assertSame(TestCustomDefineInstances::instances(), [TestCustomDefineInstances::instance('FOO'), TestCustomDefineInstances::instance('BAR')]);
+    }
 }
 
 class TestInstancesEnum extends Enum
@@ -173,3 +178,15 @@ public function getChildProp()
         return $this->childProp;
     }
 }
+
+final class TestCustomDefineInstances extends Enum
+{
+    public const FOO = 'FOO';
+    public const BAR = 'BAR';
+
+    protected static function defineInstances(): void
+    {
+        self::define(self::FOO);
+        self::define(self::BAR);
+    }
+}

test/Enum/EnumTrait/EnumTraitTest.php

@@ -49,6 +49,11 @@ public function testInheritance(): void
         $this->assertNotSame(TestInheritanceParentEnum::PARENT(), TestInheritanceChildEnum::PARENT());
         $this->assertNotSame(TestInheritanceParentEnum::PARENT(), TestInheritanceChildEnum::PARENT());
     }
+
+    public function testDefineInstances(): void
+    {
+        $this->assertSame(TestCustomDefineInstances::instances(), [TestCustomDefineInstances::instance('FOO'), TestCustomDefineInstances::instance('BAR')]);
+    }
 }
 
 class TestInstancesEnum implements EnumInterface
@@ -185,3 +190,17 @@ public function getChildProp()
         return $this->childProp;
     }
 }
+
+final class TestCustomDefineInstances
+{
+    use EnumTrait;
+
+    public const FOO = 'FOO';
+    public const BAR = 'BAR';
+
+    private static function defineInstances(): void
+    {
+        self::define(self::FOO);
+        self::define(self::BAR);
+    }
+}