class ArrayAccessGetterSetter

final class ArrayAccessGetterSetter implements PropagationGetterInterface, PropagationSetterInterface {
    private static ?self $instance = null;
    
    /**
     * Returns a singleton instance of `self` to avoid, multiple runtime allocations.
     */
    public static function getInstance() : self {
        if (null === self::$instance) {
            self::$instance = new self();
        }
        return self::$instance;
    }
    
    /** {@inheritdoc} */
    public function keys($carrier) : array {
        if ($this->isSupportedCarrier($carrier)) {
            $keys = [];
            foreach ($carrier as $key => $_) {
                $keys[] = (string) $key;
            }
            return $keys;
        }
        throw new InvalidArgumentException(sprintf('Unsupported carrier type: %s.', get_debug_type($carrier)));
    }
    
    /** {@inheritdoc} */
    public function get($carrier, string $key) : ?string {
        if ($this->isSupportedCarrier($carrier)) {
            $value = $carrier[$this->resolveKey($carrier, $key)] ?? null;
            if (is_array($value) && $value) {
                $value = $value[array_key_first($value)];
            }
            return is_string($value) ? $value : null;
        }
        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 {
        if ($key === '') {
            throw new InvalidArgumentException('Unable to set value with an empty key');
        }
        if ($this->isSupportedCarrier($carrier)) {
            if (($r = $this->resolveKey($carrier, $key)) !== $key) {
                unset($carrier[$r]);
            }
            $carrier[$key] = $value;
            return;
        }
        throw new InvalidArgumentException(sprintf('Unsupported carrier type: %s. Unable to set value associated with key:%s', get_debug_type($carrier), $key));
    }
    private function isSupportedCarrier($carrier) : bool {
        return is_array($carrier) || $carrier instanceof ArrayAccess && $carrier instanceof Traversable;
    }
    private function resolveKey($carrier, string $key) : string {
        if (isset($carrier[$key])) {
            return $key;
        }
        foreach ($carrier as $k => $_) {
            $k = (string) $k;
            if (strcasecmp($k, $key) === 0) {
                return $k;
            }
        }
        return $key;
    }

}