Integrate cuyz/valinor for type-safe object mapping

Author: jeromegamez

composer.json

@@ -31,6 +31,7 @@
         "beste/clock": "^3.0",
         "beste/in-memory-cache": "^1.3.1",
         "beste/json": "^1.5.1",
+        "cuyz/valinor": "^2.0",
         "fig/http-message-util": "^1.1.5",
         "firebase/php-jwt": "^6.10.2",
         "google/auth": "^v1.45",

phpstan.neon.dist

@@ -28,4 +28,5 @@ parameters:
 	reportPossiblyNonexistentConstantArrayOffset: true
 	treatPhpDocTypesAsCertain: false
 includes:
+	- vendor/cuyz/valinor/qa/PHPStan/valinor-phpstan-configuration.php
 	- vendor/phpstan/phpstan/conf/bleedingEdge.neon

src/Firebase/Factory.php

@@ -38,6 +38,9 @@
 use Kreait\Firebase\JWT\SessionCookieVerifier;
 use Kreait\Firebase\Messaging\AppInstanceApiClient;
 use Kreait\Firebase\Messaging\RequestFactory;
+use Kreait\Firebase\Valinor\Mapper;
+use Kreait\Firebase\Valinor\Normalizer;
+use Kreait\Firebase\Valinor\Source;
 use Psr\Cache\CacheItemPoolInterface;
 use Psr\Clock\ClockInterface;
 use Psr\Http\Message\UriInterface;
@@ -134,6 +137,14 @@ final class Factory
      */
     private array $firestoreClientConfig = [];
 
+    private mixed $mapperCache = null;
+
+    private mixed $normalizerCache = null;
+
+    private ?Mapper $mapper = null;
+
+    private ?Normalizer $normalizer = null;
+
     public function __construct()
     {
         $this->clock = SystemClock::create();
@@ -308,6 +319,24 @@ public function withKeySetCache(CacheItemPoolInterface $cache): self
         return $factory;
     }
 
+    public function withMapperCache(mixed $cache): self
+    {
+        $factory = clone $this;
+        $factory->mapperCache = $cache;
+        $factory->mapper = null;
+
+        return $factory;
+    }
+
+    public function withNormalizerCache(mixed $cache): self
+    {
+        $factory = clone $this;
+        $factory->normalizerCache = $cache;
+        $factory->normalizer = null;
+
+        return $factory;
+    }
+
     public function withHttpClientOptions(HttpClientOptions $options): self
     {
         $factory = clone $this;
@@ -711,6 +740,16 @@ private function createIdTokenVerifier(): IdTokenVerifier
         return $verifier->withExpectedTenantId($this->tenantId);
     }
 
+    private function getMapper(): Mapper
+    {
+        return $this->mapper ??= new Mapper($this->mapperCache);
+    }
+
+    private function getNormalizer(): Normalizer
+    {
+        return $this->normalizer ??= new Normalizer($this->normalizerCache);
+    }
+
     private function createSessionCookieVerifier(): SessionCookieVerifier
     {
         return SessionCookieVerifier::createWithProjectIdAndCache($this->getProjectId(), $this->verifierCache ?? $this->defaultCache);

src/Firebase/Valinor/Converter/SnakeCaseToCamelCaseConverter.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Valinor\Converter;
+
+use Traversable;
+
+/**
+ * @internal
+ *
+ * @see https://valinor.cuyz.io/latest/how-to/convert-input/#converting-keys-format-from-snake_case-to-camelcase
+ */
+final class SnakeCaseToCamelCaseConverter
+{
+    public function __invoke(mixed $values, callable $next): object
+    {
+        if ($values instanceof Traversable) {
+            $values = iterator_to_array($values);
+        }
+
+        if (!is_array($values)) {
+            return $next($values);
+        }
+
+        $camelCaseConverted = array_combine(
+            array_map(
+                fn($key): string => lcfirst(str_replace('_', '', ucwords((string) $key, '_'))),
+                array_keys($values),
+            ),
+            $values,
+        );
+
+        return $next($camelCaseConverted);
+    }
+}

src/Firebase/Valinor/Mapper.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Valinor;
+
+use CuyZ\Valinor\Mapper\MappingError;
+use CuyZ\Valinor\MapperBuilder;
+use Kreait\Firebase\Exception\InvalidArgumentException;
+use Kreait\Firebase\Valinor\Converter\SnakeCaseToCamelCaseConverter;
+
+/**
+ * @internal
+ */
+final class Mapper
+{
+    private readonly MapperBuilder $mapperBuilder;
+
+    public function __construct(private readonly mixed $cache = null, ?MapperBuilder $builder = null)
+    {
+        $builder ??= new MapperBuilder();
+
+        if ($cache !== null) {
+            $builder = $builder->withCache($this->cache);
+        }
+
+        $this->mapperBuilder = $builder;
+    }
+
+    public function withConverter(callable $converter): self
+    {
+        $mapperBuilder = $this->mapperBuilder->registerConverter($converter); // @phpstan-ignore-line argument.type
+
+        return new self($this->cache, $mapperBuilder);
+    }
+
+    public function snakeToCamelCase(): self
+    {
+        return $this->withConverter(new SnakeCaseToCamelCaseConverter());
+    }
+
+    public function allowSuperfluousKeys(): self
+    {
+        return new self($this->cache, $this->mapperBuilder->allowSuperfluousKeys());
+    }
+
+    /**
+     * @template T
+     * @param class-string<T> $signature
+     *
+     * @throws InvalidArgumentException
+     *
+     * @return T
+     */
+    public function map(string $signature, mixed $source): mixed
+    {
+        try {
+            return $this->mapperBuilder->mapper()->map($signature, $source);
+        } catch (MappingError $e) {
+            $errorMessages = [];
+            foreach ($e->messages() as $message) {
+                $errorMessages[] = '- `'.$message->path().'`: '.$message->toString();
+            }
+
+            $message = "Could not map type `$signature`:".PHP_EOL;
+            $message .= implode(PHP_EOL, $errorMessages);
+
+            throw new InvalidArgumentException($message, 0, $e);
+        }
+    }
+}

src/Firebase/Valinor/Normalizer.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Valinor;
+
+use CuyZ\Valinor\Normalizer\ArrayNormalizer;
+use CuyZ\Valinor\Normalizer\Format;
+use CuyZ\Valinor\Normalizer\JsonNormalizer;
+use CuyZ\Valinor\NormalizerBuilder;
+use Kreait\Firebase\Valinor\Transformer\CamelToSnakeCaseTransformer;
+
+/**
+ * @internal
+ */
+final class Normalizer
+{
+    private const DEFAULT_JSON_OPTIONS = JSON_UNESCAPED_SLASHES
+        | JSON_UNESCAPED_UNICODE
+        | JSON_UNESCAPED_SLASHES
+        | JSON_UNESCAPED_UNICODE
+    ;
+
+    public NormalizerBuilder $normalizerBuilder;
+
+    public ?ArrayNormalizer $arrayNormalizer = null;
+
+    public ?JsonNormalizer $jsonNormalizer = null;
+
+    public function __construct(private readonly mixed $cache = null, ?NormalizerBuilder $builder = null)
+    {
+        $builder ??= new NormalizerBuilder();
+
+        if ($cache !== null) {
+            $builder = $builder->withCache($this->cache);
+        }
+
+        $this->normalizerBuilder = $builder;
+    }
+
+    public function withTransformer(callable $transformer): self
+    {
+        $builder = $this->normalizerBuilder->registerTransformer($transformer); // @phpstan-ignore-line argument.type
+
+        return new self($this->cache, $builder);
+    }
+
+    public function camelToSnakeCase(): self
+    {
+        return $this->withTransformer(new CamelToSnakeCaseTransformer());
+    }
+
+    /**
+     * @return array<mixed>
+     */
+    public function toArray(mixed $value): array
+    {
+        $this->arrayNormalizer ??= $this->normalizerBuilder->normalizer(Format::array());
+
+        $result = $this->arrayNormalizer->normalize($value);
+        assert(is_array($result));
+
+        return $result;
+    }
+
+    /**
+     * @param int $options JSON encoding options
+     *
+     * @return non-empty-string
+     */
+    public function toJson(mixed $value, ?int $options = null): string
+    {
+        $options ??= self::DEFAULT_JSON_OPTIONS;
+
+        $this->jsonNormalizer ??=  $this->normalizerBuilder->normalizer(Format::json())->withOptions($options);
+
+        $result = $this->jsonNormalizer->normalize($value);
+        assert($result !== '');
+
+        return $result;
+    }
+}

src/Firebase/Valinor/Source.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Valinor;
+
+use CuyZ\Valinor\Mapper\Source\Source as BaseSource;
+use IteratorAggregate;
+use Kreait\Firebase\Exception\InvalidArgumentException;
+use SplFileObject;
+use Throwable;
+use Traversable;
+
+/**
+ * @internal
+ *
+ * @implements IteratorAggregate<mixed>
+ */
+final class Source implements IteratorAggregate
+{
+    private function __construct(
+        /** @var iterable<mixed> */
+        private readonly iterable $delegate,
+    ) {
+    }
+
+    public static function parse(mixed $value): self
+    {
+        if (is_iterable($value)) {
+            return new self(BaseSource::iterable($value));
+        }
+
+        if (str_starts_with((string) $value, '{')) {
+            try {
+                return new self(BaseSource::json($value));
+            } catch (Throwable $e) {
+                throw new InvalidArgumentException(message: $e->getMessage(), previous: $e);
+            }
+        }
+
+        try {
+            return new self(BaseSource::file(new SplFileObject($value)));
+        } catch (Throwable $e) {
+            throw new InvalidArgumentException(message: $e->getMessage(), previous: $e);
+        }
+    }
+
+    public function getIterator(): Traversable
+    {
+        yield from $this->delegate;
+    }
+}

src/Firebase/Valinor/Transformer/CamelToSnakeCaseTransformer.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Kreait\Firebase\Valinor\Transformer;
+
+/**
+ * @internal
+ *
+ * @see https://valinor.cuyz.io/latest/serialization/common-transformers-examples/#transforming-property-name-to-snake_case
+ */
+final class CamelToSnakeCaseTransformer
+{
+    public function __invoke(object $object, callable $next): mixed
+    {
+        $result = $next();
+
+        if (! is_array($result)) {
+            return $result;
+        }
+
+        $snakeCased = [];
+
+        foreach ($result as $key => $value) {
+            $newKey = preg_replace('/[A-Z]/', '_$0', lcfirst($key));
+            assert(is_string($newKey));
+
+            $newKey = strtolower($newKey);
+
+            $snakeCased[$newKey] = $value;
+        }
+
+        return $snakeCased;
+    }
+}