Introduce EnumInterface::getLabel (#39)

* Introduce EnumInterface::getLabel to not rely on getChoices from the outside

* Store translated enum choices in a private property to avoid calling translation more than once per enum

* Normalize assert method usage to static calls

* Fixed doc use statements

* #37 $choices assignment refacto + comment getLabel in EnumInterface for next major (#40)

Co-authored-by: Mathieu Ducrot <[email protected]>

Author: yann-eugone

doc/declaring-enum.md

@@ -30,6 +30,7 @@ Create a new class, implement both `getName` & `getChoices` methods.
 namespace App\Enum;
 
 use Yokai\EnumBundle\EnumInterface;
+use Yokai\EnumBundle\Exception\InvalidEnumValueException;
 
 class GenderEnum implements EnumInterface
 {
@@ -42,6 +43,15 @@ class GenderEnum implements EnumInterface
     {
         return ['m' => 'Male', 'f' => 'Female'];
     }
+
+    public function getLabel(string $value): string
+    {
+        if (!isset($this->getChoices()[$value])) {
+            throw InvalidEnumValueException::create($this, $value);
+        }
+
+        return $this->getChoices()[$value];
+    }
 }
 ```
 
@@ -64,11 +74,13 @@ Create a new class, use `EnumWithClassAsNameTrait` trait and implement `getChoic
 namespace App\Enum;
 
 use Yokai\EnumBundle\EnumInterface;
+use Yokai\EnumBundle\EnumLabelTrait;
 use Yokai\EnumBundle\EnumWithClassAsNameTrait;
 
 class GenderEnum implements EnumInterface
 {
     use EnumWithClassAsNameTrait;
+    use EnumLabelTrait;
 
     public function getChoices(): array
     {

src/AbstractTranslatedEnum.php

@@ -12,6 +12,8 @@
  */
 abstract class AbstractTranslatedEnum implements EnumInterface
 {
+    use EnumLabelTrait;
+
     /**
      * @var TranslatorInterface
      */
@@ -27,6 +29,11 @@ abstract class AbstractTranslatedEnum implements EnumInterface
      */
     private $transDomain = 'messages';
 
+    /**
+     * @var array|null
+     */
+    private $choices = null;
+
     /**
      * @param TranslatorInterface $translator
      * @param string              $transPattern
@@ -46,19 +53,23 @@ public function __construct(TranslatorInterface $translator, string $transPatter
      */
     public function getChoices(): array
     {
-        return array_combine(
-            $this->getValues(),
-            array_map(
-                function (string $value): string {
-                    return $this->translator->trans(
-                        sprintf($this->transPattern, $value),
-                        [],
-                        $this->transDomain
-                    );
-                },
-                $this->getValues()
-            )
-        );
+        if ($this->choices === null) {
+            $this->choices = array_combine(
+                $this->getValues(),
+                array_map(
+                    function (string $value): string {
+                        return $this->translator->trans(
+                            sprintf($this->transPattern, $value),
+                            [],
+                            $this->transDomain
+                        );
+                    },
+                    $this->getValues()
+                )
+            );
+        }
+
+        return $this->choices;
     }
 
     /**

src/ConfigurableEnum.php

@@ -9,6 +9,8 @@
  */
 class ConfigurableEnum implements EnumInterface
 {
+    use EnumLabelTrait;
+
     /**
      * @var string
      */

src/EnumInterface.php

@@ -6,16 +6,31 @@
 
 /**
  * @author Yann Eugoné <[email protected]>
+ *
+ * NEXT_MAJOR: Add all these methods to the interface by uncommenting them.
+ *
+ * @method string getLabel(string $value)
  */
 interface EnumInterface
 {
     /**
+     * Returns enum choices (value as keys, labels as values)
+     *
      * @return array
      */
     public function getChoices(): array;
 
     /**
+     * Returns enum identifier (must be unique across your app).
+     *
      * @return string
      */
     public function getName(): string;
+
+    /**
+     * NEXT_MAJOR: uncomment this method
+     *
+     * @return string
+     */
+//    public function getLabel(string $value): string;
 }

src/EnumLabelTrait.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Yokai\EnumBundle;
+
+use Yokai\EnumBundle\Exception\InvalidEnumValueException;
+
+trait EnumLabelTrait
+{
+    /**
+     * @inheritdoc
+     */
+    public function getLabel(string $value): string
+    {
+        $choices = $this->getChoices();
+        if (!isset($choices[$value])) {
+            throw InvalidEnumValueException::create($this, $value);
+        }
+
+        return $choices[$value];
+    }
+}

src/Exception/CannotExtractConstantsException.php

@@ -9,7 +9,7 @@
 /**
  * @author Yann Eugoné <[email protected]>
  */
-class CannotExtractConstantsException extends InvalidArgumentException
+class CannotExtractConstantsException extends InvalidArgumentException implements ExceptionInterface
 {
     public static function invalidPattern(string $pattern): self
     {

src/Exception/DuplicatedEnumException.php

@@ -9,7 +9,7 @@
 /**
  * @author Yann Eugoné <[email protected]>
  */
-class DuplicatedEnumException extends BadMethodCallException
+class DuplicatedEnumException extends BadMethodCallException implements ExceptionInterface
 {
     /**
      * @param string $name

src/Exception/ExceptionInterface.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Yokai\EnumBundle\Exception;
+
+use Throwable;
+
+interface ExceptionInterface extends Throwable
+{
+}

src/Exception/InvalidEnumException.php

@@ -9,7 +9,7 @@
 /**
  * @author Yann Eugoné <[email protected]>
  */
-class InvalidEnumException extends DomainException
+class InvalidEnumException extends DomainException implements ExceptionInterface
 {
     /**
      * @param string $name

src/Exception/InvalidEnumValueException.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Yokai\EnumBundle\Exception;
+
+use InvalidArgumentException;
+use Yokai\EnumBundle\EnumInterface;
+
+final class InvalidEnumValueException extends InvalidArgumentException implements ExceptionInterface
+{
+    public static function create(EnumInterface $enum, string $value): self
+    {
+        return new self(
+            \sprintf('Enum "%s" does not have "%s" value.', $enum->getName(), $value)
+        );
+    }
+}