feat: initial support for FlagMetadata in resolution

src/implementation/flags/Attributes.php

@@ -32,11 +32,7 @@ public function keys(): array
      */
     public function get(string $key): bool | string | int | float | DateTime | array | null
     {
-        if (isset($this->attributesMap[$key])) {
-            return $this->attributesMap[$key];
-        }
-
-        return null;
+        return $this->attributesMap[$key] ?? null;
     }
 
     /**

src/implementation/flags/FlagMetadata.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenFeature\implementation\flags;
+
+use DateTime;
+use OpenFeature\implementation\common\ArrayHelper;
+use OpenFeature\interfaces\flags\FlagMetadata as FlagMetadataInterface;
+
+class FlagMetadata implements FlagMetadataInterface
+{
+    /**
+     * @param Array<array-key, bool|string|int|float|DateTime|mixed[]|null> $attributesMap
+     */
+    public function __construct(protected array $metadata = [])
+    {
+    }
+
+    /**
+     * Return key-type pairs of the attributes
+     *
+     * @return Array<int, string>
+     */
+    public function keys(): array
+    {
+        return ArrayHelper::getStringKeys($this->metadata);
+    }
+
+    /**
+     * @return bool|string|int|float|null
+     */
+    public function get(string $key): bool | string | int | float | null
+    {
+        return $this->metadata[$key] ?? null;
+    }
+
+    /**
+     * @return Array<array-key, bool|string|int|float|DateTime|mixed[]|null>
+     */
+    public function toArray(): array
+    {
+        return [...$this->metadata];
+    }
+}

src/implementation/provider/ResolutionDetails.php

@@ -4,6 +4,8 @@
 
 namespace OpenFeature\implementation\provider;
 
+use OpenFeature\implementation\flags\FlagMetadata as FlagMetadata;
+use OpenFeature\interfaces\flags\FlagMetadata as FlagMetadataInterface;
 use OpenFeature\interfaces\provider\ResolutionDetails as ResolutionDetailsInterface;
 use OpenFeature\interfaces\provider\ResolutionError;
 
@@ -14,6 +16,7 @@ class ResolutionDetails implements ResolutionDetailsInterface
     private ?ResolutionError $error = null;
     private ?string $reason = null;
     private ?string $variant = null;
+    private FlagMetadataInterface $flagMetadata = new FlagMetadata();
 
     /**
      * @return bool|string|int|float|mixed[]|null
@@ -60,4 +63,14 @@ public function setVariant(?string $variant): void
     {
         $this->variant = $variant;
     }
+
+    public function getFlagMetadata(): FlagMetadataInterface
+    {
+        return $this->flagMetadata;
+    }
+
+    public function setFlagMetadata(FlagMetadataInterface $flagMetadata): void
+    {
+        $this->flagMetadata = $flagMetadata;
+    }
 }

src/implementation/provider/ResolutionDetailsBuilder.php

@@ -4,6 +4,7 @@
 
 namespace OpenFeature\implementation\provider;
 
+use OpenFeature\interfaces\flags\FlagMetadata;
 use OpenFeature\interfaces\provider\ResolutionDetails as ResolutionDetailsInterface;
 use OpenFeature\interfaces\provider\ResolutionError;
 
@@ -47,6 +48,13 @@ public function withVariant(string $variant): ResolutionDetailsBuilder
         return $this;
     }
 
+    public function withFlagMetadata(FlagMetadata $flagMetadata): ResolutionDetailsBuilder
+    {
+        $this->flagMetadata->setFlagMetadata($flagMetadata);
+
+        return $this;
+    }
+
     public function build(): ResolutionDetailsInterface
     {
         return $this->details;

src/interfaces/flags/FlagMetadata.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenFeature\interfaces\flags;
+
+use DateTime;
+
+/**
+ * flag metadata MUST be a structure supporting the definition of arbitrary properties,
+ * with keys of type string, and values of type boolean | string | number.
+ */
+interface FlagMetadata
+{
+    /**
+     * Return key-type pairs of the attributes
+     *
+     * @return Array<int, string>
+     */
+    public function keys(): array;
+
+    /**
+     * @return bool|string|int|float|null
+     */
+    public function get(string $key): bool | string | int | float | null;
+
+    /**
+     * @return Array<array-key, bool|string|int|float|null>
+     */
+    public function toArray(): array;
+}

src/interfaces/provider/ResolutionDetails.php

@@ -4,6 +4,8 @@
 
 namespace OpenFeature\interfaces\provider;
 
+use OpenFeature\interfaces\flags\FlagMetadata;
+
 /**
  * A structure which contains a subset of the fields defined in the evaluation
  * details, representing the result of the provider's flag resolution process
@@ -49,4 +51,14 @@ public function getReason(): ?string;
      * with a string identifier corresponding to the returned flag value.
      */
     public function getVariant(): ?string;
+
+
+    /**
+     * ---------------
+     * Requirement 2.2.10
+     * ---------------
+     * `flag metadata` **MUST** be a structure supporting the definition of arbitrary properties, with keys of type
+     * `string`, and values of type `boolean | string | number`.
+     */
+    public function getFlagMetadata(): FlagMetadata;
 }

tests/unit/ProviderTest.php

@@ -5,6 +5,7 @@
 namespace OpenFeature\Test\unit;
 
 use Mockery;
+use OpenFeature\implementation\flags\FlagMetadata;
 use OpenFeature\Test\TestCase;
 use OpenFeature\Test\TestHook;
 use OpenFeature\Test\TestProvider;
@@ -202,6 +203,48 @@ public function testShouldPopulateReasonField(): void
         $this->assertEquals($expectedReason, $actualResolution->getReason());
     }
 
+    /**
+     * Requirement 2.6
+     *
+     * The provider SHOULD populate the flag resolution structure's reason field with "DEFAULT", "TARGETING_MATCH", "SPLIT", "DISABLED", "UNKNOWN", "ERROR" or some other string indicating the semantic reason for the returned flag value.
+     */
+    public function testShouldPopulateFlagMetadataField(): void
+    {
+        $expectedFlagMetadata = new FlagMetadata(['str' => 'value', 'num' => 42, 'bool' => true]);
+
+        /** @var Mockery\MockInterface|Provider $mockProvider */
+        $mockProvider = $this->mockery(TestProvider::class)->makePartial();
+        $mockProvider->shouldReceive('resolveBooleanValue')
+                     ->andReturn((new ResolutionDetailsBuilder())
+                                    ->withValue(true)
+                                    ->withFlagMetadata($expectedFlagMetadata)
+                                    ->build());
+
+
+        $actualResolution = $mockProvider->resolveBooleanValue('flagKey', false, null);
+
+        $this->assertEquals($expectedFlagMetadata, $actualResolution->getFlagMetadata());
+    }
+
+    /**
+     * Requirement 2.6
+     *
+     * The provider SHOULD populate the flag resolution structure's reason field with "DEFAULT", "TARGETING_MATCH", "SPLIT", "DISABLED", "UNKNOWN", "ERROR" or some other string indicating the semantic reason for the returned flag value.
+     */
+    public function testShouldDefaultAnEmptyFlagMetadataField(): void
+    {
+        $expectedFlagMetadata = new FlagMetadata();
+
+        /** @var Mockery\MockInterface|Provider $mockProvider */
+        $mockProvider = $this->mockery(TestProvider::class)->makePartial();
+        $mockProvider->shouldReceive('resolveBooleanValue')
+                     ->andReturn(ResolutionDetailsFactory::fromSuccess(true));
+
+        $actualResolution = $mockProvider->resolveBooleanValue('flagKey', false, null);
+
+        $this->assertEquals($expectedFlagMetadata, $actualResolution->getFlagMetadata());
+    }
+
     /**
      * Requirement 2.7
      *