Add Result::getPropertyErrorMessagesByPath() method (#774)

Author: vjik

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 2.4.1 under development
 
-- no changes in this release.
+- New #774: Add `Result::getPropertyErrorMessagesByPath()` method (@vjik)
 
 ## 2.4.0 July 07, 2025
 

docs/guide/en/result.md

@@ -86,6 +86,14 @@ The output for example above:
 ];
 ```
 
+#### Filtering by a specific path
+
+This list of error messages can be filtered by a specific path to property.
+
+```php
+$result->getPropertyErrorMessagesByPath(['person', 'first_name']);
+```
+
 ### Error messages indexed by property
 
 To group error messages by property, use the following `Result` API call:

docs/guide/ru/result.md

@@ -95,6 +95,14 @@ $result->getPropertyErrorMessages('email');
 ];
 ```
 
+#### Filtering by a specific path
+
+This list of error messages can be filtered by a specific path to property.
+
+```php
+$result->getPropertyErrorMessagesByPath(['person', 'first_name']);
+```
+
 ### Сообщения об ошибках, сгруппированные по свойству
 
 Для группировки сообщений об ошибках по свойству, используйте следующий

docs/po/result.md/result.md.pot

@@ -7,7 +7,7 @@
 msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2025-04-06 07:24+0000\n"
+"POT-Creation-Date: 2025-07-18 14:58+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -192,6 +192,24 @@ msgid ""
 "];\n"
 msgstr ""
 
+#. type: Title ####
+#: guide/en/result.md
+#, no-wrap
+msgid "Filtering by a specific path"
+msgstr ""
+
+#. type: Plain text
+#: guide/en/result.md
+msgid ""
+"This list of error messages can be filtered by a specific path to property."
+msgstr ""
+
+#. type: Fenced code block (php)
+#: guide/en/result.md
+#, no-wrap
+msgid "$result->getPropertyErrorMessagesByPath(['person', 'first_name']);\n"
+msgstr ""
+
 #. type: Title ###
 #: guide/en/result.md
 #, no-wrap

docs/po/result.md/ru/result.md.ru.po

@@ -6,7 +6,7 @@
 msgid ""
 msgstr ""
 "Project-Id-Version: \n"
-"POT-Creation-Date: 2025-04-06 07:24+0000\n"
+"POT-Creation-Date: 2025-07-18 14:58+0000\n"
 "PO-Revision-Date: 2025-04-12 21:30+0500\n"
 "Last-Translator: Automatically generated\n"
 "Language-Team: none\n"
@@ -198,6 +198,27 @@ msgstr ""
 "    'This value is not a valid email address.',\n"
 "];\n"
 
+#. type: Title ####
+#: guide/en/result.md
+#, fuzzy, no-wrap
+#| msgid "Filtering by a specific property"
+msgid "Filtering by a specific path"
+msgstr "Фильтрация по определенному свойству"
+
+#. type: Plain text
+#: guide/en/result.md
+#, fuzzy
+#| msgid "Error messages not bound to a specific property"
+msgid "This list of error messages can be filtered by a specific path to property."
+msgstr "Сообщения об ошибках, не привязанные к определенному свойству"
+
+#. type: Fenced code block (php)
+#: guide/en/result.md
+#, fuzzy, no-wrap
+#| msgid "$result->getPropertyErrorMessages('email');\n"
+msgid "$result->getPropertyErrorMessagesByPath(['person', 'first_name']);\n"
+msgstr "$result->getPropertyErrorMessages('email');\n"
+
 #. type: Title ###
 #: guide/en/result.md
 #, no-wrap

src/Result.php

@@ -8,6 +8,7 @@
 use Stringable;
 
 use function array_slice;
+use function count;
 use function implode;
 use function is_string;
 
@@ -202,6 +203,23 @@ public function getPropertyErrorMessages(string $property): array
         return $errors;
     }
 
+    /**
+     * Get an array of error messages for the path specified.
+     *
+     * @psalm-param list<string> $path
+     * @psalm-return list<string>
+     */
+    public function getPropertyErrorMessagesByPath(array $path): array
+    {
+        $errors = [];
+        foreach ($this->errors as $error) {
+            if ($path === array_slice($error->getValuePath(), 0, count($path))) {
+                $errors[] = $error->getMessage();
+            }
+        }
+        return $errors;
+    }
+
     /**
      * Get arrays of error messages for the property specified indexed by property path.
      * Each key is a dot-separated property path.

tests/ResultTest.php

@@ -189,6 +189,23 @@ public function testGetAttributeErrorMessages(): void
         $this->assertEquals(['error4.1', 'error4.2'], $result->getPropertyErrorMessages('attribute4'));
     }
 
+    public function testGetPropertyErrorMessagesByPath(): void
+    {
+        $result = (new Result())
+            ->addError('e1', valuePath: ['age'])
+            ->addError('e2', valuePath: ['person'])
+            ->addError('e3', valuePath: ['person', 'first_name'])
+            ->addError('e4', valuePath: ['person', 'first_name'])
+            ->addError('e5', valuePath: ['person', 'last_name'])
+            ->addError('e6');
+
+        $this->assertSame(['e1', 'e2', 'e3', 'e4', 'e5', 'e6'], $result->getPropertyErrorMessagesByPath([]));
+        $this->assertSame([], $result->getPropertyErrorMessagesByPath(['non-exists']));
+        $this->assertSame(['e1'], $result->getPropertyErrorMessagesByPath(['age']));
+        $this->assertSame(['e2', 'e3', 'e4', 'e5'], $result->getPropertyErrorMessagesByPath(['person']));
+        $this->assertSame(['e3', 'e4'], $result->getPropertyErrorMessagesByPath(['person', 'first_name']));
+    }
+
     public function testGetAttributeErrorMessagesIndexedByPath(): void
     {
         $result = $this->createAttributeErrorResult();