Metadata (#8)

* Metadata

* Fix code style (php-cs-fixer)

* Code style

Co-authored-by: PHP CS Fixer <[email protected]>

Author: stancl

README.md

@@ -7,6 +7,7 @@ A collection of enum helpers for PHP.
 - [`Values`](#values)
 - [`Options`](#options)
 - [`From`](#from)
+- [`Metadata`](#metadata)
 
 You can read more about the idea on [Twitter](https://twitter.com/archtechx/status/1495158228757270528). I originally wanted to include the `InvokableCases` helper in [`archtechx/helpers`](https://github.com/archtechx/helpers), but it makes more sense to make it a separate dependency and use it *inside* the other package.
 
@@ -211,7 +212,7 @@ enum TaskStatus: int
 enum Role
 {
     use From;
-    
+
     case ADMINISTRATOR;
     case SUBSCRIBER;
     case GUEST;
@@ -246,6 +247,125 @@ Role::tryFromName('GUEST'); // Role::GUEST
 Role::tryFromName('TESTER'); // null
 ```
 
+### Metadata
+
+This trait lets you add metadata to enum cases.
+
+#### Apply the trait on your enum
+```php
+use ArchTech\Enums\Metadata;
+use ArchTech\Enums\Meta\Meta;
+use App\Enums\MetaProperties\{Description, Color};
+
+#[Meta(Description::class, Color::class)]
+enum TaskStatus: int
+{
+    use Metadata;
+
+    #[Description('Incomplete Task')] #[Color('red')]
+    case INCOMPLETE = 0;
+
+    #[Description('Completed Task')] #[Color('green')]
+    case COMPLETED = 1;
+
+    #[Description('Canceled Task')] #[Color('gray')]
+    case CANCELED = 2;
+}
+```
+
+Explanation:
+- `Description` and `Color` are userland class attributes — meta properties
+- The `#[Meta]` call enables those two meta properties on the enum
+- Each case must have a defined description & color (in this example)
+
+#### Access the metadata
+
+```php
+TaskStatus::INCOMPLETE->description(); // 'Incomplete Task'
+TaskStatus::COMPLETED->color(); // 'green'
+```
+
+#### Creating meta properties
+
+Each meta property (= attribute used on a case) needs to exist as a class.
+```php
+#[Attribute]
+class Color extends MetaProperty {}
+
+#[Attribute]
+class Description extends MetaProperty {}
+```
+
+Inside the class, you can customize a few things. For instance, you may want to use a different method name than the one derived from the class name (`Description` becomes `description()` by default). To do that, override the `method()` method on the meta property:
+```php
+#[Attribute]
+class Description extends MetaProperty
+{
+    public static function method(): string
+    {
+        return 'note';
+    }
+}
+```
+
+With the code above, the description of a case will be accessible as `TaskStatus::INCOMPLETE->note()`.
+
+Another thing you can customize is the passed value. For instance, to wrap a color name like `text-{$color}-500`, you'd add the following `transform()` method:
+```php
+#[Attribute]
+class Color extends MetaProperty
+{
+    protected function transform(mixed $value): mixed
+    {
+        return "text-{$color}-500";
+    }
+}
+```
+
+And now the returned color will be correctly transformed:
+```php
+TaskStatus::COMPLETED->color(); // 'text-green-500'
+```
+
+#### Use the `fromMeta()` method
+```php
+TaskStatus::fromMeta(Color::make('green')); // TaskStatus::COMPLETED
+TaskStatus::fromMeta(Color::make('blue')); // Error: ValueError
+```
+
+#### Use the `tryFromMeta()` method
+```php
+TaskStatus::tryFromMeta(Color::make('green')); // TaskStatus::COMPLETED
+TaskStatus::tryFromMeta(Color::make('blue')); // null
+```
+
+#### Recommendation: use annotations and traits
+
+If you'd like to add better IDE support for the metadata getter methods, you can use `@method` annotations:
+
+```php
+/**
+ * @method string description()
+ * @method string color()
+ */
+#[Meta(Description::class, Color::class)]
+enum TaskStatus: int
+{
+    use Metadata;
+
+    #[Description('Incomplete Task')] #[Color('red')]
+    case INCOMPLETE = 0;
+
+    #[Description('Completed Task')] #[Color('green')]
+    case COMPLETED = 1;
+
+    #[Description('Canceled Task')] #[Color('gray')]
+    case CANCELED = 2;
+}
+```
+
+And if you're using the same meta property in multiple enums, you can create a dedicated trait that includes this `@method` annotation.
+
 ## Development
 
 Run all checks locally:

phpstan.neon

@@ -11,6 +11,10 @@ parameters:
         - Illuminate\Routing\Route
 
     ignoreErrors:
+        - '#Access to an undefined static property static\(ArchTech\\Enums\\Meta\\MetaProperty\)\:\:\$method#'
+        - '#invalid typehint type ArchTech\\Enums\\Metadata#'
+        - '#invalid typehint type Enum#'
+        - '#on an unknown class Enum#'
         # -
         #     message: '#Offset (.*?) does not exist on array\|null#'
         #     paths:

src/Meta/Meta.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Meta;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Meta
+{
+    /** @var MetaProperty[] */
+    public array $metaProperties;
+
+    public function __construct(array|string ...$metaProperties)
+    {
+        // When an array is passed, it'll be wrapped in an outer array due to the ...variadic parameter
+        if (isset($metaProperties[0]) && is_array($metaProperties[0])) {
+            // Extract the inner array
+            $metaProperties = $metaProperties[0];
+        }
+
+        $this->metaProperties = $metaProperties;
+    }
+}

src/Meta/MetaProperty.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Meta;
+
+abstract class MetaProperty
+{
+    final public function __construct(
+        public mixed $value,
+    ) {
+        $this->value = $this->transform($value);
+    }
+
+    public static function make(mixed $value): static
+    {
+        return new static($value);
+    }
+
+    protected function transform(mixed $value): mixed
+    {
+        // Feel free to override this to transform the value during instantiation
+
+        return $value;
+    }
+
+    /** Get the name of the accessor method */
+    public static function method(): string
+    {
+        if (property_exists(static::class, 'method')) {
+            return static::${'method'};
+        }
+
+        $parts = explode('\\', static::class);
+
+        return lcfirst(end($parts));
+    }
+}

src/Meta/Reflection.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Meta;
+
+use ReflectionAttribute;
+use ReflectionEnumUnitCase;
+use ReflectionObject;
+
+class Reflection
+{
+    /**
+     * Get the meta properties enabled on an Enum.
+     *
+     * @param \Enum&\ArchTech\Enums\Metadata $enum
+     * @return string[]|array<\class-string<MetaProperty>>
+     */
+    public static function metaProperties(mixed $enum): array
+    {
+        $reflection = new ReflectionObject($enum);
+
+        // Attributes of the `Meta` type
+        $attributes = array_values(array_filter(
+            $reflection->getAttributes(),
+            fn (ReflectionAttribute $attr) => $attr->getName() === Meta::class,
+        ));
+
+        if ($attributes) {
+            return $attributes[0]->newInstance()->metaProperties;
+        }
+
+        return [];
+    }
+
+    /**
+     * Get the value of a meta property on the provided enum.
+     *
+     * @param \Enum $enum
+     */
+    public static function metaValue(string $metaProperty, mixed $enum): mixed
+    {
+        // Find the case used by $enum
+        $reflection = new ReflectionEnumUnitCase($enum::class, $enum->name);
+        $attributes = $reflection->getAttributes();
+
+        // Instantiate each ReflectionAttribute
+        /** @var MetaProperty[] $properties */
+        $properties = array_map(fn (ReflectionAttribute $attr) => $attr->newInstance(), $attributes);
+
+        // Find the property that matches the $metaProperty class
+        $properties = array_filter($properties, fn (MetaProperty $property) => $property::class === $metaProperty);
+
+        // Reset array index
+        $properties = array_values($properties);
+
+        if ($properties) {
+            return $properties[0]->value;
+        }
+
+        return null;
+    }
+}

src/Metadata.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums;
+
+use ArchTech\Enums\Meta\MetaProperty;
+use ValueError;
+
+trait Metadata
+{
+    /** Try to get the first case with this meta property value. */
+    public static function tryFromMeta(MetaProperty $metaProperty): static|null
+    {
+        foreach (static::cases() as $case) {
+            if (Meta\Reflection::metaValue($metaProperty::class, $case) === $metaProperty->value) {
+                return $case;
+            }
+        }
+
+        return null;
+    }
+
+    /** Get the first case with this meta property value. */
+    public static function fromMeta(MetaProperty $metaProperty): static
+    {
+        return static::tryFromMeta($metaProperty) ?? throw new ValueError(
+            'Enum ' . static::class . ' does not have a case with a meta property "' .
+            $metaProperty::class . '" of value "' . $metaProperty->value . '"'
+        );
+    }
+
+    public function __call(string $property, $arguments): mixed
+    {
+        $metaProperties = Meta\Reflection::metaProperties($this);
+
+        foreach ($metaProperties as $metaProperty) {
+            if ($metaProperty::method() === $property) {
+                return Meta\Reflection::metaValue($metaProperty, $this);
+            }
+        }
+
+        return null;
+    }
+}