implement getAll function in TextMap Extract (open-telemetry#1570)

* implement getAll function in TextMap Extract

* refactor propagation interfaces to introduce ExtendedPropagationGetterInterface

* Refactor getAll method in SanitizeCombinedHeadersPropagationGetter to streamline conditional logic for getter instance check

Author: ycchuang99

src/Context/Propagation/ArrayAccessGetterSetter.php

@@ -16,10 +16,10 @@
 /**
  * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.6.1/specification/context/api-propagators.md#textmap-propagator Getter and Setter.
  *
- * Default implementation of {@see PropagationGetterInterface} and {@see PropagationSetterInterface}.
+ * Default implementation of {@see ExtendedPropagationGetterInterface} and {@see PropagationSetterInterface}.
  * This type is used if no custom getter/setter is provided to {@see TextMapPropagatorInterface::inject()} or {@see TextMapPropagatorInterface::extract()}.
  */
-final class ArrayAccessGetterSetter implements PropagationGetterInterface, PropagationSetterInterface
+final class ArrayAccessGetterSetter implements ExtendedPropagationGetterInterface, PropagationSetterInterface
 {
     private static ?self $instance = null;
 
@@ -78,6 +78,29 @@ public function get($carrier, string $key): ?string
         );
     }
 
+    /** {@inheritdoc} */
+    public function getAll($carrier, string $key): array
+    {
+        if ($this->isSupportedCarrier($carrier)) {
+            $value = $carrier[$this->resolveKey($carrier, $key)] ?? null;
+            if (is_array($value) && $value) {
+                return array_values(array_filter($value, 'is_string'));
+            }
+
+            return is_string($value)
+                ? [$value]
+                : [];
+        }
+
+        throw new InvalidArgumentException(
+            sprintf(
+                'Unsupported carrier type: %s. Unable to get value associated with key:%s',
+                get_debug_type($carrier),
+                $key
+            )
+        );
+    }
+
     /** {@inheritdoc} */
     public function set(&$carrier, string $key, string $value): void
     {

src/Context/Propagation/ExtendedPropagationGetterInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Context\Propagation;
+
+/**
+ * Interface for getting values from a carrier.
+ * This interface extends the base PropagationGetterInterface to avoid breaking changes.
+ */
+interface ExtendedPropagationGetterInterface extends PropagationGetterInterface
+{
+    /**
+     * Gets all values of a given key from a carrier.
+     *
+     * @see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.44.0/specification/context/api-propagators.md#getall
+     *
+     * @return list<string>
+     */
+    public function getAll($carrier, string $key): array;
+}

src/Context/Propagation/SanitizeCombinedHeadersPropagationGetter.php

@@ -12,7 +12,7 @@
  * handle edge cases where the header has a trailing ';' or an empty trace state.
  * We also need to trim trailing separators from the header, found when a header is empty.
  */
-final class SanitizeCombinedHeadersPropagationGetter implements PropagationGetterInterface
+final class SanitizeCombinedHeadersPropagationGetter implements ExtendedPropagationGetterInterface
 {
     private const LIST_MEMBERS_SEPARATOR = ',';
     private const SERVER_CONCAT_HEADERS_REGEX = '/;(?=[^,=;]*=|$)/';
@@ -40,4 +40,23 @@ public function get($carrier, string $key): ?string
             $value,
         );
     }
+
+    public function getAll($carrier, string $key): array
+    {
+        $value = $this->getter instanceof ExtendedPropagationGetterInterface
+            ? $this->getter->getAll($carrier, $key)
+            : (array) $this->getter->get($carrier, $key);
+
+        if ($value === []) {
+            return [];
+        }
+
+        $value = preg_replace(
+            [self::SERVER_CONCAT_HEADERS_REGEX, self::TRAILING_LEADING_SEPARATOR_REGEX],
+            [self::LIST_MEMBERS_SEPARATOR],
+            $value,
+        );
+
+        return array_values($value);
+    }
 }

tests/Unit/Context/Propagation/ArrayAccessGetterSetterTest.php

@@ -138,4 +138,42 @@ public function test_set_empty_key(): void
         $this->expectExceptionMessage('Unable to set value with an empty key');
         $map->set($carrier, '', 'alpha');
     }
+
+    public function test_get_all_from_carrier(): void
+    {
+        $carrier = ['a' => ['alpha', 'beta'], 'b' => 'bravo'];
+        $map = new ArrayAccessGetterSetter();
+
+        $this->assertSame(['alpha', 'beta'], $map->getAll($carrier, 'a'));
+        $this->assertSame(['bravo'], $map->getAll($carrier, 'b'));
+        $this->assertSame(['a', 'b'], $map->keys($carrier));
+    }
+
+    public function test_get_all_from_not_existing_key(): void
+    {
+        $carrier = ['a' => 'alpha'];
+        $map = new ArrayAccessGetterSetter();
+
+        $this->assertSame([], $map->getAll($carrier, 'b'));
+        $this->assertSame(['a'], $map->keys($carrier));
+    }
+
+    public function test_get_all_numeric_key_from_carrier(): void
+    {
+        $carrier = [1 => ['alpha', 'beta']];
+        $map = new ArrayAccessGetterSetter();
+
+        $this->assertSame(['alpha', 'beta'], $map->getAll($carrier, '1'));
+        $this->assertSame(['1'], $map->keys($carrier));
+    }
+
+    public function test_get_all_from_unsupported_carrier(): void
+    {
+        $carrier = new stdClass();
+        $map = new ArrayAccessGetterSetter();
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unsupported carrier type: ' . \get_class($carrier) . '. Unable to get value associated with key:a');
+        $map->getAll($carrier, 'a');
+    }
 }

tests/Unit/Context/Propagation/SanitizeCombinedHeadersPropagationGetterTest.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Tests\Unit\Context\Propagation;
+
+use Mockery;
+use Mockery\Adapter\Phpunit\MockeryTestCase;
+use OpenTelemetry\Context\Propagation\ExtendedPropagationGetterInterface;
+use OpenTelemetry\Context\Propagation\PropagationGetterInterface;
+use OpenTelemetry\Context\Propagation\SanitizeCombinedHeadersPropagationGetter;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+#[CoversClass(SanitizeCombinedHeadersPropagationGetter::class)]
+class SanitizeCombinedHeadersPropagationGetterTest extends MockeryTestCase
+{
+    /** @var Mockery\MockInterface&PropagationGetterInterface */
+    private $propagationGetter;
+
+    /** @var Mockery\MockInterface&ExtendedPropagationGetterInterface */
+    private $extendedPropagationGetter;
+
+    protected function setUp(): void
+    {
+        $this->propagationGetter = Mockery::mock(PropagationGetterInterface::class);
+        $this->extendedPropagationGetter = Mockery::mock(ExtendedPropagationGetterInterface::class);
+    }
+
+    public function test_get_all_from_carrier_with_semicolons(): void
+    {
+        $carrier = ['a' => ['key1=value1;key2=value2', 'key3=value3']];
+
+        $this->extendedPropagationGetter->shouldReceive('getAll')->with($carrier, 'a')->andReturn(['key1=value1;key2=value2', 'key3=value3']);
+        $getter = new SanitizeCombinedHeadersPropagationGetter($this->extendedPropagationGetter);
+
+        $this->assertSame(['key1=value1,key2=value2', 'key3=value3'], $getter->getAll($carrier, 'a'));
+    }
+
+    public function test_get_all_from_carrier_with_leading_commas(): void
+    {
+        $carrier = ['a' => [',,alpha,beta']];
+
+        $this->extendedPropagationGetter->shouldReceive('getAll')->with($carrier, 'a')->andReturn([',,alpha,beta']);
+        $getter = new SanitizeCombinedHeadersPropagationGetter($this->extendedPropagationGetter);
+
+        $this->assertSame(['alpha,beta'], $getter->getAll($carrier, 'a'));
+    }
+
+    public function test_get_all_from_not_existing_key(): void
+    {
+        $carrier = ['a' => 'alpha'];
+
+        $this->extendedPropagationGetter->shouldReceive('getAll')->with($carrier, 'b')->andReturn([]);
+        $getter = new SanitizeCombinedHeadersPropagationGetter($this->extendedPropagationGetter);
+
+        $this->assertSame([], $getter->getAll($carrier, 'b'));
+    }
+
+    public function test_get_all_from_carrier_without_implement_extended_getter(): void
+    {
+        $carrier = ['a' => 'alpha'];
+
+        $this->propagationGetter->shouldReceive('get')->with($carrier, 'a')->andReturn('alpha');
+        $getter = new SanitizeCombinedHeadersPropagationGetter($this->propagationGetter);
+
+        $this->assertSame(['alpha'], $getter->getAll($carrier, 'a'));
+    }
+}