phpDocumentor / phpDocumentor/guides

Migrating a directive to #[Directive]/createNode() can silently break parse-time-dependent or ordering-dependent behavior

Open
#1,378 1 comment 0 reactions 0 assignees View on GitHub

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-numbers integration 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_html functional 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.