ContentTypeItemNode
extends AbstractNode
in package
implements
RenderablePageInterface
Root AST node for a single item inside a content-type collection.
A content-type item is authored in any supported documentation format (RST, Markdown, …), parsed from a dedicated collection source directory, compiled, and rendered as a self-contained HTML page. Like PageNode, items are intentionally not part of the documentation tree.
In addition to the common RenderablePageInterface contract, a content-type item carries:
- A publication date read from the
:date:field-list entry (DateNode). - An optional per-item template override read from the
:page-template:field-list entry (ContentTypeTemplateNode). When present it takes precedence over the collection-levelitem-templateconfigured inguides.xml. - An auto-extracted summary — the first ParagraphNode found in
the document body (descending into the first SectionNode if the
body starts with one), returned as a node so templates can render it
directly via
renderNode(item.summary).
Table of Contents
Interfaces
- RenderablePageInterface
- Common contract for nodes that are rendered as standalone HTML pages outside the main documentation tree.
Properties
- $classes : array<string|int, string>
- $options : array<string, scalar|array<string|int, scalar>|null>
- $value : TValue
- $date : DateTimeImmutable|null
- Publication date, or null when no `:date:` field was present.
- $filePath : string
- $headerNodes : array<string|int, MetadataNode>
- Nodes rendered in the HTML <head> (metadata), excluding {@see PageDestinationNode}, {@see DateNode}, and {@see ContentTypeTemplateNode} which are promoted to dedicated fields.
- $itemTemplate : string|null
- Per-item Twig template path, or null when no `:page-template:` field was present (the collection default applies in that case).
- $outputPath : string
- Where this item should be written relative to the output root.
- $summary : ParagraphNode|null
- The first paragraph node from the document body, or null when no paragraph was found.
Methods
- __construct() : mixed
- addHeaderNode() : void
- from() : self
- Promotes a compiled {@see DocumentNode} into a {@see ContentTypeItemNode}.
- getChildren() : array<string|int, Node>
- Body nodes that make up the visible page content.
- getClasses() : array<string|int, string>
- getClassesString() : string
- getDate() : DateTimeImmutable|null
- Publication date parsed from the `:date:` field-list entry, or `null` when none was declared or the value could not be parsed as `Y-m-d`.
- getFilePath() : string
- Source file path relative to its source directory, without extension.
- getHeaderNodes() : array<string|int, MetadataNode>
- Metadata nodes that should be rendered inside the HTML <head>.
- getItemTemplate() : string|null
- Per-item Twig template path override from `:page-template:`, or `null` when the item does not override the collection default.
- getOption() : mixed
- getOptions() : array<string, scalar|array<string|int, scalar>|null>
- getOutputPath() : string
- Output path relative to the output root, without extension.
- getPageTitle() : string|null
- Returns the plain-text page title for use in the HTML `<title>` element.
- getSummary() : ParagraphNode|null
- The first paragraph node auto-extracted from the body, or `null` when no paragraph node was found. Templates should render this via `renderNode(item.summary)`.
- getValue() : TValue
- hasOption() : bool
- setClasses() : void
- Normalizes class names following the rules of identifier-normalization
- setOutputPath() : void
- setValue() : void
- toDocument() : DocumentNode
- Wraps this item's body children in a temporary {@see DocumentNode} so that the standard compiler can process cross-references.
- withItemTemplate() : self
- Returns a copy of this item with `$itemTemplate` set as the item template.
- withKeepExistingOptions() : static
- Adds $options as default options without overriding any options already set.
- withOptions() : static
- withSourceDirectory() : self
- Returns a copy of this item with `$sourceDir` prepended to both the {@see getFilePath()} and {@see getOutputPath()} values.
- extractSummary() : ParagraphNode|null
- Walks the top-level child nodes and returns the first {@see ParagraphNode} encountered, descending into the first {@see SectionNode} when the body opens with one.
- extractTitle() : string|null
- Walks top-level body nodes looking for the first {@see TitleNode}, descending into the first {@see SectionNode} when necessary.
- parseDateValue() : DateTimeImmutable|null
- Parses a raw date string (expected format `Y-m-d`) into a {@see DateTimeImmutable}, returning `null` for empty or non-conforming strings (e.g. `"not-a-date"`, `"2026-01"`).
Properties
$classes
protected
array<string|int, string>
$classes
= []
$options
protected
array<string, scalar|array<string|int, scalar>|null>
$options
= []
$value
protected
TValue
$value
$date
Publication date, or null when no `:date:` field was present.
private
DateTimeImmutable|null
$date
= null
$filePath read-only
private
string
$filePath
$headerNodes
Nodes rendered in the HTML <head> (metadata), excluding {@see PageDestinationNode}, {@see DateNode}, and {@see ContentTypeTemplateNode} which are promoted to dedicated fields.
private
array<string|int, MetadataNode>
$headerNodes
= []
$itemTemplate
Per-item Twig template path, or null when no `:page-template:` field was present (the collection default applies in that case).
private
string|null
$itemTemplate
= null
$outputPath
Where this item should be written relative to the output root.
private
string
$outputPath
Does not include the file extension (e.g. "news/2026-01-15-launch").
$summary
The first paragraph node from the document body, or null when no paragraph was found.
private
ParagraphNode|null
$summary
= null
Methods
__construct()
public
__construct(string $filePath[, array<string|int, Node> $children = [] ]) : mixed
Parameters
- $filePath : string
-
Source file path relative to the collection source directory, without extension
- $children : array<string|int, Node> = []
-
Parsed body nodes (sections, paragraphs, …)
addHeaderNode()
public
addHeaderNode(MetadataNode $node) : void
Parameters
- $node : MetadataNode
from()
Promotes a compiled {@see DocumentNode} into a {@see ContentTypeItemNode}.
public
static from(DocumentNode $documentNode) : self
Extracts DateNode, ContentTypeTemplateNode, and PageDestinationNode from the document's header nodes and finds the first ParagraphNode in the body as the summary.
Parameters
- $documentNode : DocumentNode
Return values
selfgetChildren()
Body nodes that make up the visible page content.
public
getChildren() : array<string|int, Node>
Return values
array<string|int, Node>getClasses()
public
getClasses() : array<string|int, string>
Return values
array<string|int, string>getClassesString()
public
getClassesString() : string
Return values
stringgetDate()
Publication date parsed from the `:date:` field-list entry, or `null` when none was declared or the value could not be parsed as `Y-m-d`.
public
getDate() : DateTimeImmutable|null
Return values
DateTimeImmutable|nullgetFilePath()
Source file path relative to its source directory, without extension.
public
getFilePath() : string
Used to build a thin DocumentNode for RenderContext compatibility.
Return values
stringgetHeaderNodes()
Metadata nodes that should be rendered inside the HTML <head>.
public
getHeaderNodes() : array<string|int, MetadataNode>
Return values
array<string|int, MetadataNode>getItemTemplate()
Per-item Twig template path override from `:page-template:`, or `null` when the item does not override the collection default.
public
getItemTemplate() : string|null
Return values
string|nullgetOption()
public
getOption(string $name[, TType|null $default = null ]) : mixed
Parameters
- $name : string
- $default : TType|null = null
Tags
getOptions()
public
getOptions() : array<string, scalar|array<string|int, scalar>|null>
Return values
array<string, scalar|array<string|int, scalar>|null>getOutputPath()
Output path relative to the output root, without extension.
public
getOutputPath() : string
This is the path at which the rendered HTML file is written.
Return values
stringgetPageTitle()
Returns the plain-text page title for use in the HTML `<title>` element.
public
getPageTitle() : string|null
The title is extracted from the first TitleNode found by walking the body children (descending into the first SectionNode when the body opens with one). This is the RST document/section heading.
Falls back to null when no title node is found in the body.
Return values
string|nullgetSummary()
The first paragraph node auto-extracted from the body, or `null` when no paragraph node was found. Templates should render this via `renderNode(item.summary)`.
public
getSummary() : ParagraphNode|null
Return values
ParagraphNode|nullgetValue()
public
getValue() : TValue
Return values
TValuehasOption()
public
hasOption(string $name) : bool
Parameters
- $name : string
Return values
boolsetClasses()
Normalizes class names following the rules of identifier-normalization
public
setClasses(array<string|int, string> $classes) : void
Parameters
- $classes : array<string|int, string>
Tags
setOutputPath()
public
setOutputPath(string $outputPath) : void
Parameters
- $outputPath : string
setValue()
public
setValue(TValue $value) : void
Parameters
- $value : TValue
toDocument()
Wraps this item's body children in a temporary {@see DocumentNode} so that the standard compiler can process cross-references.
public
toDocument() : DocumentNode
Return values
DocumentNodewithItemTemplate()
Returns a copy of this item with `$itemTemplate` set as the item template.
public
withItemTemplate(string $itemTemplate) : self
Used by ParseContentTypeListener
to stamp the collection-level default template onto items that do not
carry their own per-item :page-template: override.
Parameters
- $itemTemplate : string
Return values
selfwithKeepExistingOptions()
Adds $options as default options without overriding any options already set.
public
withKeepExistingOptions(array<string, scalar|null> $options) : static
Parameters
- $options : array<string, scalar|null>
Return values
staticwithOptions()
public
withOptions(array<string, scalar|array<string|int, scalar>|null> $options) : static
Parameters
- $options : array<string, scalar|array<string|int, scalar>|null>
Return values
staticwithSourceDirectory()
Returns a copy of this item with `$sourceDir` prepended to both the {@see getFilePath()} and {@see getOutputPath()} values.
public
withSourceDirectory(string $sourceDir) : self
This is needed because ParseFileCommand
returns a DocumentNode whose filePath is relative to the
collection $sourceDir rather than to the output root. Calling this
method after from() ensures that items render to the correct
output subdirectory (e.g. news/2026-01-release instead of just
2026-01-release).
A custom PageDestinationNode override is preserved unchanged when
it was explicitly set (i.e. outputPath !== filePath).
Parameters
- $sourceDir : string
Return values
selfextractSummary()
Walks the top-level child nodes and returns the first {@see ParagraphNode} encountered, descending into the first {@see SectionNode} when the body opens with one.
private
static extractSummary(array<string|int, Node> $children) : ParagraphNode|null
Parameters
- $children : array<string|int, Node>
Return values
ParagraphNode|nullextractTitle()
Walks top-level body nodes looking for the first {@see TitleNode}, descending into the first {@see SectionNode} when necessary.
private
static extractTitle(array<string|int, Node> $children) : string|null
Parameters
- $children : array<string|int, Node>
Return values
string|nullparseDateValue()
Parses a raw date string (expected format `Y-m-d`) into a {@see DateTimeImmutable}, returning `null` for empty or non-conforming strings (e.g. `"not-a-date"`, `"2026-01"`).
private
static parseDateValue(string|null $raw) : DateTimeImmutable|null
Parameters
- $raw : string|null