Change how we trace the path of results

Currently, we’re using scalar values to trace paths. The problem with
that approach is that we can’t create a reliable hierarchy with them, as
we can’t know for sure when a path is the same for different rules. By
using an object, we can easily compare and create a parent-child
relationship with it.

While making these changes, I deemed it necessary to also create objects
to handle Name and Id, which makes the code simpler and more robust. By
having Name and Path, we can create specific stringifiers that allow us
to customise how we render those values.

I didn’t manage to make those changes atomically, which is why this
commit makes so many changes. I found myself moving back and forth, and
making all those changes at once was the best solution I found.

Author: henriquemoody

library/Message/Formatter/FirstResultStringFormatter.php

@@ -16,8 +16,6 @@
 
 final readonly class FirstResultStringFormatter implements StringFormatter
 {
-    use PathProcessor;
-
     public function __construct(
         private Renderer $renderer,
         private TemplateResolver $templateResolver,
@@ -31,7 +29,7 @@ public function format(Result $result, array $templates, Translator $translator)
         if (!$this->templateResolver->hasMatch($result, $matchedTemplates)) {
             foreach ($result->children as $child) {
                 return $this->format(
-                    $this->overwritePath($result, $child),
+                    $child,
                     $matchedTemplates,
                     $translator,
                 );

library/Message/Formatter/NestedArrayFormatter.php

@@ -19,8 +19,6 @@
 
 final readonly class NestedArrayFormatter implements ArrayFormatter
 {
-    use PathProcessor;
-
     public function __construct(
         private Renderer $renderer,
         private TemplateResolver $templateResolver,
@@ -37,18 +35,18 @@ public function format(Result $result, array $templates, Translator $translator)
         $matchedTemplates = $this->templateResolver->selectMatches($result, $templates);
         if (count($result->children) === 0 || $this->templateResolver->hasMatch($result, $matchedTemplates)) {
             return [
-                $result->getDeepestPath() ?? $result->id => $this->renderer->render(
-                    $this->templateResolver->resolve($result->withDeepestPath(), $matchedTemplates),
+                $result->path->value ?? $result->id->value => $this->renderer->render(
+                    $this->templateResolver->resolve($result->withoutParentPath(), $matchedTemplates),
                     $translator,
                 ),
             ];
         }
 
         $messages = [];
         foreach ($result->children as $child) {
-            $key = $child->getDeepestPath() ?? $child->id ?? 0;
+            $key = $child->path->value ?? $child->id->value;
             $messages[$key] = $this->format(
-                $this->overwritePath($result, $child),
+                $child->withoutParentPath()->withoutName(),
                 $this->templateResolver->selectMatches($child, $matchedTemplates),
                 $translator,
             );
@@ -62,7 +60,7 @@ public function format(Result $result, array $templates, Translator $translator)
         if (count($messages) > 1) {
             $self = [
                 '__root__' => $this->renderer->render(
-                    $this->templateResolver->resolve($result->withDeepestPath(), $matchedTemplates),
+                    $this->templateResolver->resolve($result->withoutParentPath(), $matchedTemplates),
                     $translator,
                 ),
             ];

library/Message/Formatter/NestedListStringFormatter.php

@@ -15,7 +15,6 @@
 use Respect\Validation\Result;
 
 use function array_filter;
-use function array_map;
 use function array_reduce;
 use function count;
 use function rtrim;
@@ -26,8 +25,6 @@
 
 final readonly class NestedListStringFormatter implements StringFormatter
 {
-    use PathProcessor;
-
     public function __construct(
         private Renderer $renderer,
         private TemplateResolver $templateResolver,
@@ -51,14 +48,16 @@ private function formatRecursively(
         $matchedTemplates = $this->templateResolver->selectMatches($result, $templates);
 
         $formatted = '';
+        $displayedName = null;
         if ($this->isVisible($result, ...$siblings)) {
             $indentation = str_repeat(' ', $depth * 2);
+            $displayedName = $result->name;
             $formatted .= sprintf(
                 '%s- %s' . PHP_EOL,
                 $indentation,
                 $this->renderer->render(
                     $this->templateResolver->resolve(
-                        $depth > 0 ? $result->withDeepestPath() : $result,
+                        $result->withoutParentPath(),
                         $matchedTemplates,
                     ),
                     $translator,
@@ -68,17 +67,13 @@ private function formatRecursively(
         }
 
         if (!$this->templateResolver->hasMatch($result, $matchedTemplates)) {
-            $children = array_map(
-                fn(Result $child) => $this->overwritePath($result, $child),
-                $result->children,
-            );
-            foreach ($children as $child) {
+            foreach ($result->children as $child) {
                 $formatted .= $this->formatRecursively(
-                    $child,
+                    $displayedName === $child->name ? $child->withoutName() : $child,
                     $matchedTemplates,
                     $translator,
                     $depth,
-                    ...array_filter($children, static fn(Result $sibling) => $sibling !== $child),
+                    ...array_filter($result->children, static fn(Result $sibling) => $sibling !== $child),
                 );
                 $formatted .= PHP_EOL;
             }

library/Message/Formatter/PathProcessor.php

@@ -80,6 +80,9 @@ public function selectMatches(Result $result, array $templates): array
     /** @return non-empty-array<string|int> */
     private function getKeys(Result $result): array
     {
-        return array_filter([$result->path, $result->name, $result->id], static fn($key) => $key !== null);
+        return array_filter(
+            [$result->path?->value, $result->name?->value, $result->id->value],
+            static fn($key) => $key !== null,
+        );
     }
 }

library/Message/Formatter/TemplateResolver.php

@@ -12,10 +12,12 @@
 use ReflectionClass;
 use Respect\Stringifier\Stringifier;
 use Respect\Validation\Message\Placeholder\Listed;
+use Respect\Validation\Message\Placeholder\Name;
 use Respect\Validation\Message\Placeholder\Quoted;
 use Respect\Validation\Result;
 use Respect\Validation\Rule;
 
+use function array_key_exists;
 use function is_array;
 use function is_bool;
 use function is_scalar;
@@ -35,12 +37,8 @@ public function __construct(
 
     public function render(Result $result, Translator $translator): string
     {
-        $parameters = $result->parameters;
-        $parameters['path'] = $result->path !== null ? Quoted::fromPath($result->path) : null;
-        $parameters['input'] = $result->input;
-
-        $builtName = $result->name ?? $parameters['path'] ?? $this->placeholder('input', $result->input, $translator);
-        $parameters['name'] ??= $builtName;
+        $parameters = ['path' => $result->path, 'input' => $result->input, 'name' => $this->getName($result)];
+        $parameters += $result->parameters;
 
         $rendered = (string) preg_replace_callback(
             '/{{(\w+)(\|([^}]+))?}}/',
@@ -100,10 +98,6 @@ private function placeholder(
             return $translator->translate($value);
         }
 
-        if ($name === 'name' && is_string($value)) {
-            return $value;
-        }
-
         return $this->stringifier->stringify($value, 0) ?? print_r($value, true);
     }
 
@@ -127,4 +121,25 @@ private function getTemplateMessage(Result $result): string
 
         return $result->template;
     }
+
+    private function getName(Result $result): Name
+    {
+        if (array_key_exists('name', $result->parameters) && is_string($result->parameters['name'])) {
+            return new Name($result->parameters['name']);
+        }
+
+        if (array_key_exists('name', $result->parameters)) {
+            return new Name((string) $this->stringifier->stringify($result->parameters['name'], 0));
+        }
+
+        if ($result->name !== null) {
+            return $result->path ? $result->name->withPath($result->path) : $result->name;
+        }
+
+        if ($result->path?->value !== null) {
+            return new Name((string) $this->stringifier->stringify($result->path, 0));
+        }
+
+        return new Name((string) $this->stringifier->stringify($result->input, 0));
+    }
 }

library/Message/InterpolationRenderer.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Message\Placeholder;
+
+use Respect\Validation\Rule;
+
+use function lcfirst;
+use function strrchr;
+use function substr;
+use function ucfirst;
+
+final readonly class Id
+{
+    public function __construct(
+        public string $value,
+    ) {
+    }
+
+    public static function fromRule(Rule $rule): self
+    {
+        return new self(lcfirst(substr((string) strrchr($rule::class, '\\'), 1)));
+    }
+
+    public function withPrefix(string $prefix): self
+    {
+        return new self($prefix . ucfirst($this->value));
+    }
+}

library/Message/Placeholder/Id.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Message\Placeholder;
+
+final readonly class Name
+{
+    public function __construct(
+        public string $value,
+        public Path|null $path = null,
+    ) {
+    }
+
+    public function withPath(Path $path): Name
+    {
+        return new self($this->value, $path);
+    }
+}

library/Message/Placeholder/Name.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Validation\Message\Placeholder;
+
+final class Path
+{
+    public function __construct(
+        public int|string $value,
+        public Path|null $parent = null,
+    ) {
+    }
+
+    public function isOrphan(): bool
+    {
+        return $this->parent === null;
+    }
+
+    public function withParent(self $parent): self
+    {
+        if ($parent === $this->parent) {
+            return $this;
+        }
+
+        $this->parent = $parent;
+
+        return $this;
+    }
+}

library/Message/Placeholder/Path.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <[email protected]>
+ * SPDX-License-Identifier: MIT
+ */
+
+namespace Respect\Validation\Message\Stringifier;
+
+use Respect\Stringifier\Stringifier;
+use Respect\Validation\Message\Placeholder\Name;
+
+use function sprintf;
+
+final readonly class NameStringifier implements Stringifier
+{
+    public function __construct(
+        private Stringifier $stringifier,
+    ) {
+    }
+
+    public function stringify(mixed $raw, int $depth): string|null
+    {
+        if (!$raw instanceof Name) {
+            return null;
+        }
+
+        if ($raw->path === null || $raw->path->isOrphan()) {
+            return $raw->value;
+        }
+
+        return sprintf(
+            '%s (<- %s)',
+            $this->stringifier->stringify($raw->path, $depth),
+            $raw->value,
+        );
+    }
+}