Update English documentation to match current API by WarLikeLaux · Pull Request #792 · yiisoft/validator

WarLikeLaux · 2026-03-21T23:17:43Z

Q	A
Is bugfix?	❌
New feature?	❌
Tests added?	❌
Breaks BC?	❌
Fixed issues

What does this PR do?

Update English guide to match the current API (2.0.0–2.5.2): add missing sections, fix broken code examples, remove obsolete PHP 8.0 notes.

Changelog not required, because no source files changed.

Copilot

Pull request overview

Updates the validator documentation to align with the current API (notably around rules providers vs PHP attributes, Result convenience methods, and rule guides), and refreshes gettext POT/PO artifacts accordingly.

Changes:

Refreshes English guides with new/updated sections (Compare rule guide, Result “first error” helpers, Each options like stopOnError, conditional validation in nested structures).
Updates rule-provider/attributes documentation to match current behavior (including merging rules when validating data objects).
Regenerates POT/PO files and updates Russian docs/translations to reflect the new English source strings.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
docs/po/using-validator.md/using-validator.md.pot	Updates source strings for “using validator” guide (rules provider vs attributes behavior).
docs/po/using-validator.md/ru/using-validator.md.ru.po	Updates RU translation entries for “using validator” (many now fuzzy/untranslated).
docs/po/result.md/ru/result.md.ru.po	Updates RU translation entries for `Result` guide, adds new sections and fixes examples.
docs/po/result.md/result.md.pot	Updates source strings for `Result` guide, including “first error” helper methods and new sections.
docs/po/README.md/ru/README.md.ru.po	Updates RU translation entries for docs README navigation (adds Compare link).
docs/po/README.md/README.md.pot	Updates source strings for docs README navigation (adds Compare link).
docs/po/customizing-error-messages.md/ru/customizing-error-messages.md.ru.po	Updates RU translation entries for property placeholders and adds attributes/Label note and link ref.
docs/po/customizing-error-messages.md/customizing-error-messages.md.pot	Updates source strings for property placeholders and adds attributes/Label note and link ref.
docs/po/conditional-validation.md/ru/conditional-validation.md.ru.po	Adds new extracted section about `when` in nested structures (RU translation now fuzzy/untranslated).
docs/po/conditional-validation.md/conditional-validation.md.pot	Adds new source section about `when` in nested structures.
docs/po/built-in-rules-nested.md/ru/built-in-rules-nested.md.ru.po	Updates extracted strings, adds nested conditional validation section and link refs.
docs/po/built-in-rules-nested.md/built-in-rules-nested.md.pot	Updates extracted strings, adds nested conditional validation section and link refs.
docs/po/built-in-rules-each.md/ru/built-in-rules-each.md.ru.po	Updates extracted strings, adds `Each` sections (stop on error, current key) and fixes nested example.
docs/po/built-in-rules-each.md/built-in-rules-each.md.pot	Updates extracted strings, adds `Each` sections and fixes nested example.
docs/po/built-in-rules-composite.md/ru/built-in-rules-composite.md.ru.po	Updates extracted strings and fixes `Nested` constructor usage in Composite example.
docs/po/built-in-rules-composite.md/built-in-rules-composite.md.pot	Updates extracted strings and fixes `Nested` constructor usage in Composite example.
docs/po/built-in-rules-compare.md/ru/built-in-rules-compare.md.ru.po	Updates extracted strings and expands Compare guide content (RU translation now largely untranslated).
docs/po/built-in-rules-compare.md/built-in-rules-compare.md.pot	Updates extracted strings and expands Compare guide content.
docs/guide/ru/using-validator.md	Updates RU guide content and examples for rules provider vs attributes (currently includes English text).
docs/guide/ru/result.md	Updates RU `Result` guide (currently includes English sections and wording changes).
docs/guide/ru/README.md	Adds Compare link to RU docs index.
docs/guide/ru/customizing-error-messages.md	Updates RU guide section about property placeholders and Label attribute (currently includes English text).
docs/guide/ru/conditional-validation.md	Adds `when` within nested structures section (currently in English).
docs/guide/ru/built-in-rules-nested.md	Adds nested conditional validation section and link (currently in English).
docs/guide/ru/built-in-rules-each.md	Adds `Each` guide sections and fixes nested example (currently includes English sections).
docs/guide/ru/built-in-rules-composite.md	Fixes `Nested` constructor usage in RU Composite example.
docs/guide/ru/built-in-rules-compare.md	Expands Compare guide (currently includes English content).
docs/guide/en/using-validator.md	Updates rules-provider vs attributes behavior explanation and examples.
docs/guide/en/result.md	Adds “first error” helper sections, adds “adding errors”/“merging results”, fixes wording and examples.
docs/guide/en/README.md	Adds Compare link to docs index.
docs/guide/en/customizing-error-messages.md	Documents `{Property}` placeholder and recommends `Label` attribute; adds link reference.
docs/guide/en/creating-custom-rules.md	Updates custom-rule handler snippets to match rule property-based message configuration.
docs/guide/en/configuring-rules-via-php-attributes.md	Removes obsolete PHP 8.0 limitations text, adds section on combining attributes with `RulesProviderInterface`, fixes provider naming.
docs/guide/en/conditional-validation.md	Adds `when` usage examples within nested structures (and inside `Each`).
docs/guide/en/built-in-rules.md	Updates built-in rules list (renames Boolean rules, adds Uuid).
docs/guide/en/built-in-rules-nested.md	Adds nested conditional validation section and link to conditional validation guide.
docs/guide/en/built-in-rules-each.md	Adds `Each` sections (stop on first error, current key) and fixes nested example structure.
docs/guide/en/built-in-rules-composite.md	Fixes `Nested` constructor usage in Composite example.
docs/guide/en/built-in-rules-compare.md	Expands Compare guide with shortcut classes, compare types, target property examples, and fixes DateTime examples.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-04T21:06:06Z

docs/guide/ru/using-validator.md

+When an object implementing `RulesProviderInterface` is passed as the
+`$rules` argument (second argument of `validate()`), only the rules from
+`getRules()` are used. PHP attributes on the object are not parsed in this
+case.


docs/guide/ru/using-validator.md is a Russian guide, but this updated paragraph is now in English. Please translate it to Russian (and keep terminology consistent with the rest of the RU docs) or avoid changing RU content in an “English documentation” PR.

Copilot · 2026-04-04T21:06:06Z

docs/guide/ru/using-validator.md

+    #[Length(min: 2)] // Ignored because the object is passed as the $rules argument.
    public string $name;

-    #[Number(min: 21)] // Будет тихо проигнорировано.
+    #[Number(min: 21)] // Ignored because the object is passed as the $rules argument.
    protected int $age;
-    
-    public function getRules() : iterable
+
+    public function getRules(): iterable


The inline comments in this RU guide code sample were changed to English ("Ignored because..."). Please translate these comments to Russian (or keep the previous RU wording) to avoid mixing languages in the Russian documentation.

Copilot · 2026-04-04T21:06:07Z

docs/guide/ru/result.md

+### First error messages indexed by property
+
+To get only the first error message for each property (useful for displaying
+a single error per field), use:
+
+```php
+use Yiisoft\Validator\Result;
+


This section of the Russian Result guide was added in English (heading + explanatory text). Please translate it to Russian or revert the RU guide changes if translation is out of scope for this PR.

Copilot · 2026-04-04T21:06:07Z

docs/guide/ru/result.md


 Список также может быть отфильтрован по конкретному свойству. Поддерживаются
-свойства только верхнего уровня.
+атрибуты только верхнего уровня.


This sentence now says “Only top-level attributes are supported.” in Russian as “атрибуты”, but the API refers to data properties (свойства), not PHP attributes. The previous wording (“свойства”) was correct—please revert/fix the translation.

Suggested change

атрибуты только верхнего уровня.

только свойства верхнего уровня.

Copilot · 2026-04-04T21:06:07Z

docs/guide/ru/customizing-error-messages.md

+Almost all error templates have support for `{property}` and `{Property}`
+placeholders which are substituted with an actual property name that was set
+during rules configuration. The `{Property}` variant capitalizes the first
+letter. By default, a property name is formatted as is. It can be acceptable
+for English language (for example, `currentPassword is required.`), but when
+using translations for error messages, it's better to provide an additional
+property translation.
+
+The simplest approach for properties defined via PHP attributes is to use
+the `Label` attribute directly on the property. See [Configuring rules via
+PHP attributes] for details.


This Russian guide section was replaced with English text describing {property}/{Property} placeholders. Please translate it to Russian or keep the Russian explanation; currently the RU guide mixes languages.

Suggested change

Almost all error templates have support for `{property}` and `{Property}`

placeholders which are substituted with an actual property name that was set

during rules configuration. The `{Property}` variant capitalizes the first

letter. By default, a property name is formatted as is. It can be acceptable

for English language (for example, `currentPassword is required.`), but when

using translations for error messages, it's better to provide an additional

property translation.

The simplest approach for properties defined via PHP attributes is to use

the `Label` attribute directly on the property. See [Configuring rules via

PHP attributes] for details.

Почти все шаблоны ошибок поддерживают плейсхолдеры `{property}` и

`{Property}`, которые заменяются фактическим именем свойства, заданным при

настройке правил. Вариант `{Property}` делает первую букву заглавной. По

умолчанию имя свойства форматируется как есть. Для английского языка это

может быть приемлемо (например, `currentPassword is required.`), но при

использовании переводов сообщений об ошибках лучше также предоставить

перевод имени свойства.

Самый простой подход для свойств, определенных через PHP-атрибуты, —

использовать атрибут `Label` непосредственно на свойстве. Подробнее см. в

разделе [Configuring rules via PHP attributes].

Copilot · 2026-04-04T21:06:09Z

docs/guide/ru/using-validator.md

+When an object implementing `RulesProviderInterface` is passed as the
+`$rules` argument (second argument of `validate()`), only the rules from
+`getRules()` are used. PHP attributes on the object are not parsed in this
+case.


PR description says it updates the English guide, but this PR also modifies multiple docs/guide/ru/* files (and some new content is left in English). Either update the PR description/scope to include RU docs translation work, or revert RU guide changes from this PR.

Copilot · 2026-04-04T21:06:09Z

docs/guide/ru/using-validator.md

+In this way, rules are provided in addition to data in the same object. Both
+PHP attributes and `getRules()` method are supported — their rules are
+merged (attribute rules are applied first). Note that the `rules` argument
+is `null` in the `validate()` method call.


This paragraph in the Russian guide was changed to English (“Providing rules via the data object…”). Please translate it to Russian (and update the example comments accordingly) or revert RU guide changes if translation is out of scope.

Copilot · 2026-04-04T21:06:09Z

docs/guide/ru/result.md

+## Adding errors
+
+When writing custom rule handlers, errors are added to a `Result`
+object. There are three methods available, each with different
+post-processing behavior:
+


The new “Adding errors” section in the Russian Result guide is written in English. Please translate these additions to Russian (or keep them out of RU docs until translated) to avoid mixed-language documentation.

Copilot · 2026-04-04T21:06:09Z

docs/guide/ru/customizing-error-messages.md

+the `Label` attribute directly on the property. See [Configuring rules via
+PHP attributes] for details.


This Russian document now references [Configuring rules via PHP attributes], but the link reference defined at the bottom is [Настройка правил с помощью PHP атрибутов]: .... As a result, the Markdown reference link will be unresolved. Please either change the in-text reference to [Настройка правил с помощью PHP атрибутов] or add a matching [Configuring rules via PHP attributes]: ... definition.

Suggested change

the `Label` attribute directly on the property. See [Configuring rules via

PHP attributes] for details.

the `Label` attribute directly on the property. See [Настройка правил с помощью PHP атрибутов]

for details.

Copilot · 2026-04-04T21:06:10Z

docs/po/built-in-rules-nested.md/ru/built-in-rules-nested.md.ru.po

+#, fuzzy, no-wrap
+#| msgid "[Conditional validation](conditional-validation.md)"
+msgid "[Conditional validation]: conditional-validation.md"
+msgstr "[Условия валидации](conditional-validation.md)"


This is a Markdown reference definition ([...]: ...) in the source, but the Russian msgstr turns it into an inline link ([...](...)). That will break the generated Markdown link reference. Please keep the : URL reference-definition format in the translation, only translating the label if needed.

Update English documentation to match current API (2.0.0–2.5.2)

2e460b2

WarLikeLaux force-pushed the docs-update-english-guide branch from 217a1ec to 2e460b2 Compare March 21, 2026 23:19

WarLikeLaux and others added 2 commits March 21, 2026 23:19

Update docs translation

166f8e5

Update docs translation

3002afe

samdark requested a review from Copilot April 4, 2026 21:00

Copilot started reviewing on behalf of samdark April 4, 2026 21:00 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update English documentation to match current API#792

Update English documentation to match current API#792
WarLikeLaux wants to merge 3 commits intoyiisoft:masterfrom
WarLikeLaux:docs-update-english-guide

WarLikeLaux commented Mar 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	атрибуты только верхнего уровня.
	только свойства верхнего уровня.

		the `Label` attribute directly on the property. See [Configuring rules via
		PHP attributes] for details.

Uh oh!

Conversation

WarLikeLaux commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

WarLikeLaux commented Mar 21, 2026 •

edited

Loading