Added begin of Link resolving

Author: toonvandenbos

src/Exceptions/InvalidSerializedValue.php

@@ -3,21 +3,39 @@
 namespace Whitecube\Links\Exceptions;
 
 use InvalidArgumentException;
+use Whitecube\Links\Resolvers\Archive;
 
 class InvalidSerializedValue extends InvalidArgumentException
 {
     /**
-     * Create a new Exception for an invalid serialized array value.
+     * Create a new Exception for an invalid serialized inline tag value.
      */
-    public static function forArray(): never
+    public static function inlineTagSyntax(string $tag): static
     {
-        throw new self('Provided serialized link array should at least contain a "key" index.');
+        return new self(sprintf('Provided serialized inline tag should match syntax "@link(key:value)", got "%s"', $tag));
     }
+
     /**
-     * Create a new Exception for an invalid serialized inline tag value.
+     * Create a new Exception for an invalid serialized array value because of a missing "resolver" key.
      */
-    public static function forInlineTag(string $tag): never
+    public static function missingResolver(): static
     {
-        throw new self(sprintf('Provided serialized inline tag should match syntax "@link(key:value)", got "%s"', $tag));
+        return new self('Provided serialized link value should at least contain a "resolver" attribute.');
+    }
+
+    /**
+     * Create a new Exception for an invalid serialized array value because of a missing "resolver" key.
+     */
+    public static function ambiguousArchiveResolver(Archive $archive, string $key): static
+    {
+        $available = implode(', ', array_map(fn($key) => '"'.$key.'"', array_filter([
+            $archive->getIndex()?->key,
+            $archive->getItems()?->key,
+        ])));
+
+        return new self(sprintf(
+            'Provided serialized link value is targetting an ambiguous archive resolver (available: %s, got "%s").',
+            $available, $key
+        ));
     }
 }

src/Link.php

@@ -2,62 +2,53 @@
 
 namespace Whitecube\Links;
 
+use Illuminate\Support\Facades\App;
 use Whitecube\Links\Exceptions\InvalidSerializedValue;
 
 class Link
 {
     /**
-     * The URL resolver's identification key.
+     * The resolved URL.
      */
-    protected string $key;
+    public readonly string $url;
 
     /**
-     * The represented resource's immutable identifier.
+     * The eventual extra provided arguments.
      */
-    protected null|int|string $id;
+    protected array $arguments;
 
     /**
-     * The default displayable title.
+     * The defined title attribute for this link.
      */
-    protected string $title;
+    protected ?string $title;
 
     /**
-     * The eventual extra arguments for the URL resolver.
+     * The resolver used to create this link.
      */
-    protected array $arguments = [];
+    protected ResolverInterface $resolver;
 
     /**
-     * Create a new Link instance.
+     * The eventual variant represented by this link.
      */
-    public function __construct(string $key, null|int|string $id = null)
-    {
-        $this->key = $key;
-        $this->id = $id;
-    }
+    protected ?Variant $variant;
 
     /**
-     * Create a new Link instance dynamically.
+     * Create a new Link instance.
      */
-    public static function make(string $key, null|int|string $id = null): static
+    public function __construct(string $url, ResolverInterface $resolver, ?Variant $variant = null, array $arguments = [])
     {
-        return new static($key, $id);
+        $this->url = $url;
+        $this->resolver = $resolver;
+        $this->variant = $variant;
+        $this->arguments = $arguments;
     }
 
     /**
      * Create a link instance from serialized array.
      */
     public static function fromArray(array $value): static
     {
-        if(! isset($value['key'])) {
-            return InvalidSerializedValue::forArray();
-        }
-
-        $instance = static::make($value['key'], $value['id'] ?? null);
-
-        unset($value['key']);
-        unset($value['id']);
-
-        return $instance->arguments($value);
+        return App::make(Manager::class)->resolve($value);
     }
 
     /**
@@ -68,7 +59,7 @@ public static function fromInlineTag(string $value): static
         preg_match('/^\\@link\\((.+?)\\)$/', trim($value), $matches);
 
         if(! ($matches[1] ?? null)) {
-            return InvalidSerializedValue::forInlineTag($value);
+            throw InvalidSerializedValue::inlineTagSyntax($value);
         }
 
         $data = array_reduce(explode(',', $matches[1]), function ($data, $pair) {
@@ -81,20 +72,12 @@ public static function fromInlineTag(string $value): static
         return static::fromArray($data);
     }
 
-    /**
-     * Get the link's resolver identifying key
-     */
-    public function getResolverKey(): string
-    {
-        return $this->key;
-    }
-
     /**
      * Define the link's default displayable title.
      */
     public function title(string $title): static
     {
-        $this->title = $title;
+        $this->title = trim($title) ?: null;
 
         return $this;
     }
@@ -104,7 +87,7 @@ public function title(string $title): static
      */
     public function getTitle(): string
     {
-        return $this->title;
+        return $this->title ?? $this->resolver->getTitle($this->variant);
     }
 
     /**
@@ -136,10 +119,11 @@ public function argument(string $attribute, mixed $value): static
      */
     public function toArray(): array
     {
-        return array_filter(array_merge([
-            'key' => $this->key,
-            'id' => $this->id,
-        ], $this->arguments));
+        return array_filter([
+            'resolver' => $this->resolver->key,
+            'variant' => $this->variant?->getKey(),
+            'data' => $this->arguments ?: null,
+        ]);
     }
 
     /**

src/Manager.php

@@ -6,6 +6,7 @@
 use Whitecube\Links\Resolvers\Route;
 use Whitecube\Links\Resolvers\Archive;
 use Whitecube\Links\Exceptions\ResolverNotFound;
+use Whitecube\Links\Exceptions\InvalidSerializedValue;
 
 class Manager
 {
@@ -50,6 +51,26 @@ public function register(ResolverInterface $resolver): ResolverInterface
         return $resolver;
     }
 
+    /**
+     * Transform a serialized link value into a proper resolved Link instance.
+     */
+    public function resolve(array $value, bool $silent = false): ?Link
+    {
+        if(! isset($value['resolver'])) {
+            throw InvalidSerializedValue::missingResolver();
+        }
+
+        $resolver = ($silent)
+            ? $this->tryFor($value['resolver'])
+            : $this->for($value['resolver']);
+
+        if(! $resolver) {
+            return null;
+        }
+
+        return $resolver->resolve($value, $silent);
+    }
+
     /**
      * Retrieve a registered resolver from the links resolvers repository
      * and throw an exception if not defined.

src/ResolverInterface.php

@@ -9,14 +9,14 @@ interface ResolverInterface
      * itself or a more appropriate/specific resolver if available.
      */
     public function for(string $key): ?ResolverInterface;
+
+    /**
+     * Instantiate a Link object based on provided serialized value.
+     */
+    public function resolve(array $value, bool $silent): ?Link;
 
     /**
      * Transform the resolver into an available Link Option.
      */
     public function toOption(): null|OptionInterface|OptionsCollection;
-
-    /**
-     * Generate the effective URL.
-     */
-    public function resolve(array $arguments = []): string;
 }

src/Resolvers/Archive.php

@@ -3,10 +3,12 @@
 namespace Whitecube\Links\Resolvers;
 
 use Closure;
+use Whitecube\Links\Link;
 use Whitecube\Links\OptionPanel;
 use Whitecube\Links\OptionInterface;
 use Whitecube\Links\OptionsCollection;
 use Whitecube\Links\ResolverInterface;
+use Whitecube\Links\Exceptions\InvalidSerializedValue;
 
 class Archive implements ResolverInterface
 {
@@ -50,6 +52,14 @@ public function index(Closure $setup): static
         return $this;
     }
 
+    /**
+     * Get the eventual defined index URL resolver.
+     */
+    public function getIndex(): ?ArchiveIndexRoute
+    {
+        return $this->index;
+    }
+
     /**
      * Define the archive's items URLs resolver.
      */
@@ -62,6 +72,14 @@ public function items(Closure $setup): static
         return $this;
     }
 
+    /**
+     * Get the eventual defined items URL resolver.
+     */
+    public function getItems(): ?ArchiveItemsRoute
+    {
+        return $this->items;
+    }
+
     /**
      * Check if this resolver is suited for the provided key and return
      * itself or a more appropriate/specific resolver if available.
@@ -73,6 +91,18 @@ public function for(string $key): ?ResolverInterface
             ?? $this->items?->for($key)
             ?? null;
     }
+    
+    /**
+     * Instantiate a Link object based on provided serialized value.
+     */
+    public function resolve(array $value, bool $silent): ?Link
+    {
+        if(! $silent) {
+            throw InvalidSerializedValue::ambiguousArchiveResolver($this, $value['resolver'] ?? $this->key);
+        }
+
+        return null;
+    }
 
     /**
      * Transform the resolver into an available Link Option.
@@ -103,12 +133,4 @@ protected function configureOptionChoicesPanel(OptionPanel $panel): void
 
         $panel->archive($this->items->toOption());
     }
-
-    /**
-     * Generate the effective URL.
-     */
-    public function resolve(array $arguments = []): string
-    {
-        return '#'; // TODO
-    }
 }

src/Resolvers/ArchiveIndexRoute.php

@@ -2,6 +2,7 @@
 
 namespace Whitecube\Links\Resolvers;
 
+use Whitecube\Links\Link;
 use Whitecube\Links\OptionInterface;
 use Whitecube\Links\OptionsCollection;
 use Whitecube\Links\ResolverInterface;
@@ -33,6 +34,14 @@ public function for(string $key): ?ResolverInterface
         return ($this->key === $key) ? $this : null;
     }
 
+    /**
+     * Instantiate a Link object based on provided serialized value.
+     */
+    public function resolve(array $value, bool $silent): ?Link
+    {
+        return null;
+    }
+
     /**
      * Transform the resolver into an available Link Option.
      */

src/Resolvers/ArchiveItemsRoute.php

@@ -2,6 +2,7 @@
 
 namespace Whitecube\Links\Resolvers;
 
+use Whitecube\Links\Link;
 use Whitecube\Links\OptionInterface;
 use Whitecube\Links\OptionsCollection;
 use Whitecube\Links\ResolverInterface;
@@ -34,6 +35,14 @@ public function for(string $key): ?ResolverInterface
         return ($this->key === $key) ? $this : null;
     }
 
+    /**
+     * Instantiate a Link object based on provided serialized value.
+     */
+    public function resolve(array $value, bool $silent): ?Link
+    {
+        return null;
+    }
+
     /**
      * Transform the resolver into an available Link Option.
      */

src/Resolvers/Concerns/ResolvesRoutes.php

@@ -52,9 +52,9 @@ public function getRouteArgument(string $key): mixed
     }
 
     /**
-     * Generate the effective URL.
+     * Generate the route's effective URL.
      */
-    public function resolve(array $arguments = []): string
+    protected function generateUrl(array $arguments = []): string
     {
         return URL::route($this->getRouteName(), array_merge(
             $this->getRouteArguments(),

src/Resolvers/Route.php

@@ -2,6 +2,7 @@
 
 namespace Whitecube\Links\Resolvers;
 
+use Whitecube\Links\Link;
 use Whitecube\Links\OptionInterface;
 use Whitecube\Links\OptionsCollection;
 use Whitecube\Links\ResolverInterface;
@@ -32,6 +33,18 @@ public function for(string $key): ?ResolverInterface
     {
         return ($this->key === $key) ? $this : null;
     }
+    
+    /**
+     * Instantiate a Link object based on provided serialized value.
+     */
+    public function resolve(array $value, bool $silent): ?Link
+    {
+        return new Link(
+            url: $this->generateUrl($value['data'] ?? []),
+            arguments: $value['data'] ?? [],
+            resolver: $this,
+        );
+    }
 
     /**
      * Transform the resolver into an available Link Option.