fix: streamline Metadata usage (#220)

Author: dkarlovi

psalm.baseline.xml

@@ -668,6 +668,11 @@
       <code><![CDATA[__construct]]></code>
     </PossiblyUnusedMethod>
   </file>
+  <file src="src/Metadata.php">
+    <PossiblyUnusedProperty>
+      <code><![CDATA[$id]]></code>
+    </PossiblyUnusedProperty>
+  </file>
   <file src="src/Permutator.php">
     <MixedArgument>
       <code><![CDATA[$parameters]]></code>

src/Bridge/Twig/Extension/ThumbnailExtension.php

@@ -15,6 +15,7 @@
 
 use Sigwin\YASSG\Asset\AssetFetch;
 use Sigwin\YASSG\AssetQueue;
+use Sigwin\YASSG\Metadata;
 use Symfony\Component\Asset\Packages;
 use Symfony\Component\HttpFoundation\RequestStack;
 use Twig\Extension\AbstractExtension;
@@ -34,21 +35,22 @@ public function getFunctions(): array
                 if (str_starts_with($path, './')) {
                     if (! isset($context['__path'])) {
                         if (isset($options['self'])) {
-                            if (! \is_object($options['self']) || ! property_exists($options['self'], '__path')) {
+                            if (! \is_object($options['self']) || ! property_exists($options['self'], '__metadata')
+                                || ! \is_object($options['self']->__metadata) || ! $options['self']->__metadata instanceof Metadata) {
                                 throw new \RuntimeException('Cannot use yassg_thumbnail() with {self: object} as the second argument, pass {self: object} as the second argument');
                             }
-                            $context['__path'] = $options['self']->__path;
+                            $context['__path'] = $options['self']->__metadata->path;
                         } else {
                             $candidates = [];
                             foreach ($context as $item) {
-                                if (\is_object($item) && property_exists($item, '__path')) {
-                                    $candidates[] = $item;
+                                if (\is_object($item) && property_exists($item, '__metadata') && $item->__metadata instanceof Metadata) {
+                                    $candidates[] = $item->__metadata;
                                 }
                             }
                             if (\count($candidates) !== 1) {
                                 throw new \RuntimeException('Cannot use yassg_thumbnail() without a single Locatable object in context, pass {self: object} as the second argument');
                             }
-                            $context['__path'] = $candidates[0]->__path;
+                            $context['__path'] = $candidates[0]->path;
                         }
                     }
 

src/Metadata.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sigwin Yassg project.
+ *
+ * (c) sigwin.hr
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Sigwin\YASSG;
+
+final class Metadata
+{
+    public function __construct(
+        public readonly string $id,
+        public readonly ?string $path = null,
+    ) {
+    }
+}

src/Storage/DenormalizingStorage.php

@@ -15,6 +15,7 @@
 
 use Sigwin\YASSG\Context\LocaleContext;
 use Sigwin\YASSG\Exception\UnexpectedAttributeException;
+use Sigwin\YASSG\Metadata;
 use Sigwin\YASSG\Storage;
 use Symfony\Component\Serializer\Exception\ExtraAttributesException;
 use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
@@ -108,21 +109,18 @@ private function denormalize(string $id, array $data, array $context): object
             $metadata = [];
             foreach ($data as $key => $value) {
                 if (str_starts_with($key, '__')) {
-                    $metadata[$key] = $value;
+                    if (! \is_string($value)) {
+                        throw new \LogicException('Invalid metadata value');
+                    }
+                    $metadata[mb_substr($key, 2)] = $value;
                     unset($data[$key]);
                 }
             }
             $object = $this->denormalizer->denormalize($data, $this->class, null, $context + [
                 AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES => false,
             ]);
-
-            // attach metadata to the object as dynamic properties
-            foreach ($metadata as $key => $value) {
-                /**
-                 * @phpstan-ignore-next-line
-                 */
-                $object->{$key} = $value;
-            }
+            /** @phpstan-ignore-next-line */
+            $object->__metadata = new Metadata(...$metadata);
 
             return $object;
         } catch (ExtraAttributesException $extraAttributesException) {

src/Storage/FilesystemStorage.php

@@ -64,7 +64,7 @@ public function load(): iterable
             }
             $ids[$id] = true;
 
-            yield $id => $this->decode($file);
+            yield $id => $this->decode($id, $file);
         }
     }
 
@@ -73,7 +73,7 @@ public function get(string $id): array
         foreach ($this->roots as $root) {
             $path = $root.$id;
             if (file_exists($path)) {
-                return $this->decode(new \SplFileObject($path));
+                return $this->decode($id, new \SplFileObject($path));
             }
         }
 
@@ -109,13 +109,14 @@ public static function resolveOptions(array $options): array
         return $resolver->resolve($options);
     }
 
-    private function decode(\SplFileInfo $file): array
+    private function decode(string $id, \SplFileInfo $file): array
     {
         if ($this->decoder->supports($file) === false) {
             throw new \RuntimeException(\sprintf('Decoder does not know how to decode %1$s file', $file->getRealPath()));
         }
 
         $decoded = $this->decoder->decode($file);
+        $decoded['__id'] = $id;
         $decoded['__path'] = $file->getRealPath();
 
         return $decoded;

src/Storage/MemoryStorage.php

@@ -23,12 +23,20 @@
  */
 final class MemoryStorage implements StorageWithOptions
 {
-    public function __construct(
-        /**
-         * @var array<string, array>
-         */
-        private array $values,
-    ) {
+    /**
+     * @var array<string, array<string, mixed>>
+     */
+    private array $values;
+
+    /**
+     * @param array<string, array<string, mixed>> $values
+     */
+    public function __construct(array $values)
+    {
+        foreach (array_keys($values) as $id) {
+            $values[$id]['__id'] = $id;
+        }
+        $this->values = $values;
     }
 
     public static function resolveOptions(array $options): array