phpDocumentor / phpDocumentor/guides
Migrating a directive to #[Directive]/createNode() can silently break parse-time-dependent or ordering-dependent behavior
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 36
- Forks
- 22
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 24
Description
Follow-up from #1373. Three directives that looked like trivial migrations broke real behavior once upgraded. Root cause is structural, so filing separately -- it'll keep hitting the #1373 effort otherwise.
Once a directive has #[Directive], DirectiveRule::apply() stops calling process()/processSub() at parse time -- createNode() only runs later, from DirectiveProcessPass at compile time, after every document is already fully parsed. That breaks anything assuming the node existed earlier.
Confirmed broken by migrating and running the test suite:
- ClassDirective -- broke
class-in-list/big-numbersintegration tests (ClassNodeTransformer, priority 40,000, runs before DirectiveProcessPass, priority 100, so the class-marker node doesn't exist yet when the transformer tries to apply it to the next sibling) - TabDirective -- broke
tabs_htmlfunctional test (rendered completely empty): parent TabsDirective is still old-style and inspects its children synchronously at parse time, but migrated TabDirective's children are still unresolved placeholders then - DocumentBlockDirective -- broke 13 bootstrap/menu integration tests: whatever collects its content into parts.footer for the theme template runs before DirectiveProcessPass resolves it, so the footer ends up empty and the content leaks into the main body
Flagged by code inspection, not yet migrated/tested:
- TestLoggerDirective, SectionauthorDirective, ConfigurationBlockDirective, TabsDirective -- all log warnings via $blockContext->getLoggerInformation() (file/line), which createNode() has no equivalent access to
- RawDirective -- needs literal unparsed source text, but the compile-time content parser always fully RST-parses first
Proposed fix for the logging case: snapshot the needed info into Directive/DirectiveNode at parse time instead of trying to carry BlockContext across the phase boundary. No fix proposed yet for the raw-content or transformer-ordering cases.
Any directive with logging, raw-content needs, or a role in another pass's ordering needs case-by-case review before migrating, not just "add the attribute and go."
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with DirectiveRule::apply(), createNode(), and DirectiveProcessPass, then reproduce the listed ClassDirective, TabDirective, and DocumentBlockDirective failures in their named integration and functional tests. Review the flagged directives for logging, raw-content, and ordering dependencies; done means each case has a migration decision and the affected tests preserve their existing behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- compilers, documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100