[BUGFIX] Validate guides.xml against XSD schema before loading #1118
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
4 tasks
CybotTM
force-pushed
the
fix/validate-guidesxml-before-loading
branch
from
0cd034b to
ee20ae6
Compare
This adds proper XSD schema validation before the configuration is
loaded into Symfony's container. When validation fails, users now see
precise error messages with line and column numbers instead of
cryptic PHP fatal errors.
Example output for invalid guides.xml:
Invalid guides.xml configuration
Your guides.xml file failed XSD schema validation:
Schema validation failed for Documentation/guides.xml
Line 3, Column 0: Element 'theme': This element is not expected.
The fix:
- Validates all guides.xml files against the XSD schema upfront
- Shows exact file path, line number, and column for each error
- Links to official documentation for correct format
- Keeps a fallback catch for any edge cases not covered by XSD
This provides much better developer experience compared to the
previous "Expected scalar, but got array" fatal error.
Adds integration tests that verify: - Invalid guides.xml shows helpful error message instead of PHP Fatal error - XSD validation error includes line number - Valid guides.xml files still render successfully
CybotTM
force-pushed
the
fix/validate-guidesxml-before-loading
branch
from
ee20ae6 to
501b733
Compare
linawolf
pushed a commit
that referenced
this pull request
Dec 11, 2025
…1117) ## Summary Instead of crashing with a PHP Fatal error when guides.xml contains invalid configuration, the guides entrypoint now catches `InvalidTypeException` and `InvalidConfigurationException` and displays a helpful error message. **Before:** ``` PHP Fatal error: Uncaught Symfony\Component\Config\Definition\Exception\InvalidTypeException: Invalid type for path "guides.theme". Expected "scalar", but got "array". in ... Stack trace: #0 ... (20+ lines of stack trace) ``` **After:** ``` Invalid guides.xml configuration Your guides.xml file contains a configuration error: Invalid type for path "guides.theme". Expected "scalar", but got "array". Common causes: - Invalid or unknown XML element - Missing required attributes - Invalid attribute values or types Run vendor/bin/typo3-guides lint-guides-xml for detailed validation. See: https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/GuideXml.html ``` ## Approach This is a **minimal fix** that catches exceptions and provides a user-friendly error message. It's simple (~25 lines) but doesn't provide line numbers or specific validation details. ## Alternative See also the companion PR with a **comprehensive fix** that validates against XSD schema before loading, providing exact line/column numbers: #1118 ## Test plan - [ ] Create a malformed guides.xml with `<theme name="typo3docs" />` as child element - [ ] Run `bin/guides run --config=Documentation Documentation` - [ ] Verify helpful error message is shown instead of PHP Fatal error - [ ] Verify valid guides.xml files still render correctly
Member
|
With #1117 we merged the "small variant" of this change, let us see if that is sufficient or we want to merge this, improved variant |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This adds proper XSD schema validation before the configuration is loaded into Symfony's container. When validation fails, users now see precise error messages with line and column numbers instead of cryptic PHP fatal errors.
Before:
After:
Approach
This is a comprehensive fix that:
Alternative
See also the companion PR with a simpler fix that only catches exceptions without XSD validation: #1117
Test plan
<theme name="typo3docs" />as child elementbin/guides run --config=Documentation Documentation