Repository navigation
First iteration on option attributes - #1231
Merged
Merged
Conversation
jaapio
force-pushed
the
task/directive-options
branch
from
March 1, 2026 19:50
0c15922 to
1823455
Compare
jaapio
force-pushed
the
task/directive-options
branch
3 times, most recently
from
August 31, 2026 06:40
f9686be to
ac6822d
Compare
The new option attribute makes it easier to validate directives. An extra advantage is that we can use the new attributes to document the directive options.
The reverse node transformer allows us to transform children of nodes before the node itself is transformed. This is needed for directives which may contain child nodes that need processing.
jaapio
force-pushed
the
task/directive-options
branch
from
August 31, 2026 19:07
6718fd3 to
71634e9
Compare
jaapio
marked this pull request as ready for review
August 31, 2026 19:07
linawolf
pushed a commit
that referenced
this pull request
Sep 4, 2026
Highlights, PullQuote, Epigraph, Container, Sidebar, Replace, and Index now declare #[Attributes\Directive(...)] and implement createNode(), per the pattern from #1231 -- replacing their getName()/getAliases() overrides. Part of the migration tracked in #1373, requested by jaapio for the reference-doc generation he's building. Several other directives that looked equally trivial (Class, Tab, DocumentBlock) turned out to break real behavior once migrated, for structural reasons unrelated to their own complexity -- see #1378. Left those, and anything sharing their root cause, out of this batch. Verified via Docker (php:8.4-cli, matching CI): phpstan clean, phpcs clean, unit/functional/integration suites green (970 tests). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PP4LkejR5PSubbhNmF4RkT Signed-off-by: lina.wolf
wouterj
reviewed
Sep 18, 2026
Comment on lines
+68
to
+70
| if (count($attributes) === 0) { | ||
| throw new LogicException('Directive class must have a Directive attribute'); | ||
| } |
Contributor
There was a problem hiding this comment.
Unless I'm wrong, this is a BC break. This should be a deprecation trigger in 1.x, and only become an exception in 2.0 (at least, all of our test suite is now failing with this exception 😄)
Member
Author
There was a problem hiding this comment.
You should implement the getName, maybe the removal of abstract is confusing?
Contributor
There was a problem hiding this comment.
This is the directive that is causing the trouble (together with the other one): https://github.com/wouterj/docs-builder/blob/phpdocumentor-guides/src/GuidesExtension/src/Directives/BestPracticeDirective.php
The problem is actually that AbstractAdmonitionDirective removed the getName() method. I'll write a patch. I have a plan to add a "bc check" test job to the CI, so I try to combine both in 1 PR.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Directive attributes & compile-time directive processing
Introduces a new attribute-based declaration system for reStructuredText directives and moves directive processing from the parse phase into the compile phase.
Moving directive processing to a compiler pass is the groundwork that enables upcoming features such as option validation — with directives now declaratively describing their options via attributes, the framework can inspect and validate them centrally instead of each directive doing ad-hoc parsing.
Features
#[Directive]and#[Option]attributesphpDocumentor\Guides\RestructuredText\Directives\Attributes\Directiveattribute declares a directive's name and aliases on the class, replacing the abstractgetName()/getAliases()methods.#[Option]attribute (OptionType, default value, description, example) declares the options a directive supports — used for automatic option validation, type coercion, and documentation.Compile-time directive processing
DirectiveNoderepresents a parsed directive during compilation and is now processed by a dedicatedDirectiveProcessPasscompiler pass instead of being resolved eagerly by the parser.ReverseNodeTransformerinterface, with support inDocumentNodeTraverser, so parent transforms run after their children.createNode(DirectiveNode)entry point; a backward-compatprocess()path (withisUpgraded()) keeps existing directives working while they are migrated.Upgraded directives
readOption()/readAllOptions()onBaseDirectivenow coerce values to the declaredOptionTypeand apply attribute defaults (e.g. youtube width/height/allow/allowfullscreen).classto the rendered node.Deprecations
#[Directive]attribute now trigger a deprecation when their name is resolved, pointing to documentation on migrating custom directives.Notes
update-security-issuesand a dependency bump.