Update "Feature guide" documentation #1595

henriquemoody · 2026-01-08T08:07:40Z

The documentation was quite outdated after the many changes I made in the main branch. This commit will make sure it's up-to-date.

I'm also creating a "Placeholder pipes" documentation, so there's not too much content in the "Feature guide"

Copilot

Pull request overview

This PR updates the Feature Guide documentation to align with recent changes in the main branch and creates a new dedicated Placeholder Pipes documentation page to better organize content.

Key changes:

Adds comprehensive documentation for placeholder pipes with detailed examples of all available modifiers
Restructures and expands the Feature Guide with new sections on validation methods, smart validation, PHP attributes, result composition, and advanced features
Improves code examples and adds clearer explanations of validator behavior and immutability

Reviewed changes

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

File	Description
docs/placeholder-pipes.md	New documentation file dedicated to explaining placeholder pipe modifiers with usage examples for raw, quote, trans, listOr, listAnd, and custom modifiers
docs/feature-guide.md	Major restructuring and expansion adding sections on validation methods, PHP attributes, result composition, prefixed shortcuts, custom templates for nested structures, naming validators, reusing validators, and advanced features like nested validation paths and helpful stack traces

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

docs/feature-guide.md

Copilot · 2026-01-08T08:10:15Z

docs/placeholder-pipes.md

+
+## Custom Modifiers
+
+You can create custom placeholder pipes by implementing your own stringifier logic when needed for specialized formatting requirements.


The section "Custom Modifiers" is vague and doesn't provide actionable information. It mentions "implementing your own stringifier logic" but doesn't explain how to do this, what interface to implement, or where to register custom modifiers. Consider either providing a concrete example or removing this section if custom modifiers aren't fully supported yet.

Suggested change

You can create custom placeholder pipes by implementing your own stringifier logic when needed for specialized formatting requirements.

At the moment, only the modifiers documented above are officially supported. Support for registering custom placeholder pipes is not part of the public API yet; when it becomes available, this section will be updated with concrete examples and configuration details.

docs/feature-guide.md

alganet · 2026-01-09T01:30:06Z

docs/feature-guide.md

+```php
+$mysqlUserResult = $result->findByPath('mysql.user');
+if ($mysqlUserResult !== null) {
+    echo $mysqlUserResult;
+}
+```


This is missing some context. The last time we used the $result variable in this page was an int validation. Perhaps we need to introduce the database connection settings example more explicitly, or something smaller that can still be relevant for the path example.

alganet · 2026-01-09T01:31:34Z

docs/feature-guide.md

+
+### Prefixed shortcuts
+
+For convenience, several prefixed shortcuts are available for validators that wrap other validators:


Perhaps we can link to the mixin class so the user can see all available shortcuts.

That would be difficult, because there are multiple mixing classes. I think we could create a page with the prefixes, though. What do you think?

That would be cool. They're generated aren't they? Perhaps we can generate the docs too.

I just added a markdown with it. I haven't fully reviewed it though.

docs/feature-guide.md

alganet · 2026-01-09T01:35:59Z

docs/feature-guide.md

+### Nested validation paths
+
+Validation can trace the path of nested structures and display helpful messages:


There was a short introduction to paths before in this document, I left a comment about lacking context. Maybe we can remove it and replace for an anchor to this more in-depth part.

alganet

Some suggestions on terminology. Nothing critical.

The documentation was quite outdated after the many changes I made in the main branch. This commit will make sure it's up-to-date. I'm also creating a "Placeholder pipes" documentation, so there's not too much content in the "Feature guide" Assisted-by: Zed (devstral-2:123b)

henriquemoody requested review from alganet and Copilot January 8, 2026 08:07

Copilot started reviewing on behalf of henriquemoody January 8, 2026 08:08 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes