[BUGFIX] Render a code block without a language instead of aborting the run

[CybotTM]

Problem

Rendering a code block whose language is not set aborts the entire run:

In CodeExtension.php line 40:
  phpDocumentor\Guides\Code\Twig\CodeExtension::highlight(): Argument #3 ($language) must be of type string, null given

CodeNode::getLanguage() is nullable, and packages/guides/resources/template/html/body/code.html.twig → body/code/highlighted-code.html.twig passes it straight into the filter as {{ node.value|highlight(node.language) }}. The filter's signature already carries the intended fallback — string $language = 'text' — but a default value cannot apply to an argument that is passed explicitly, so null reaches a non-nullable parameter and PHP throws.

Reproduction

The shortest way to reach a CodeNode without a language is a literalinclude without :language::

index
=====

..  literalinclude:: _Example.php

vendor/bin/guides run input --output=out on that project fails with the TypeError above and renders nothing. Measured on main at 90594491, so this is not a regression from anything currently in flight.

The project needs <extension class="phpDocumentor\Guides\Code"/> in its guides.xml, the way this repository's own guides.xml has it. Without the extension the container keeps the fallback template packages/guides/resources/template/html/body/code/highlighted-code.html.twig, a bare {{ node.value }}, and the filter is never called.

code-block is not affected: CodeBlockDirective always calls setLanguage(), either with the given language or with getCodeBlockDefaultLanguage(), which returns a string.

Fix

CodeExtension::highlight() accepts string|null and falls back to text, which is what the existing default already expressed.

code.html.twig writes class="language-{{ node.language ?? 'text' }}", so the class attribute names the language the content is actually highlighted with. Without this the block rendered as text but was labelled class="language-".

Only null is mapped, matching the filter. An empty-string language still renders class="language-", which is what a literal block (::) and a code-block without language produce today; the highlighter maps '' to text as well, so normalizing that too would be consistent, but it rewrites ten further expectations across nine files and is a separate change.

Tests

packages/guides-code/tests/unit/Twig/CodeExtensionTest.php asserts that a null language renders exactly like an explicit text, plus one test that a real language still highlights.

The fixture is <a> & "b" on purpose: a highlighter returns plain input unchanged for every language, so a plain fixture would pass no matter what the fallback is. With this one, text leaves the quoted part alone while php wraps it in a string token, and a second assertion states that the two differ, so the fixture itself is pinned as discriminating. Two mutations were checked against it: removing the null acceptance fails with the TypeError above, and changing the fallback to php fails the equality assertion.

tests/Integration/tests/code/literalinclude-without-language runs the reproduction above through the CLI. Its guides.xml enables the Code extension, because otherwise the fallback template packages/guides/resources/template/html/body/code/highlighted-code.html.twig renders and the filter is never reached. Both halves of the fix were mutated against it: reverting the filter signature fails with the original TypeError raised in body/code/highlighted-code.html.twig, reverting the template fallback fails on language- vs language-text.

tests/Integration/tests/markdown/code-md changes: a fenced code block without an info string carries a null language too, so its two expectations move from language- to language-text.

The TeX template renders \lstset{language={{ node.language }}} without a fallback as well, but null and '' produce the same \lstset{language=} there, which is the committed expectation for a language-less block in tests/Functional/tests/code/code.tex. There is nothing null-specific to fix there, so it is left unchanged.

Local run of phpunit (unit, functional, integration), phpcs, phpstan and deptrac: green.

Note

There is a second, complementary option: let LiteralincludeDirective fall back to getCodeBlockDefaultLanguage() the way CodeBlockDirective does — the producer-side approach #1302 took for markdown fenced code blocks. I did not do that here because it would leave the crash reachable from any other producer, and because the type mismatch really is at the template-to-filter boundary. Happy to add the directive-side default as well if you prefer both.

Assisted by claude-code:claude-opus-5 — Session

[linawolf]

Thanks a lot for your Bug report and suggested solution, I think it would also be helpful to turn your reproduction instructions into an integration test.

I am also wondering if it really makes sense to create a Code Node without language in the first place. In TYPO3 we try to guess the language by file ending and default to text and a warning if it cannot be auto detected / resolves to an unsupported language. That would however be something for a follow up

[linawolf]

One more thing: code.html.twig:10 still does class="language-{{ node.language }}" with no null fallback. That was unreachable before (the render crashed first), but now that highlight() defaults null to text, this renders class="language-" instead of class="language-text" — worth aligning with ?? 'text'.

[CybotTM]

Both points are in e5edfbb.

Class attribute. code.html.twig:10 now writes class="language-{{ node.language ?? 'text' }}". Scope of that: only null is mapped. An empty-string language keeps rendering class="language-" — that is what a literal block (::) and a code-block without language produce today. The highlighter maps '' to text as well (HighlightPhpHighlighter::__invoke() short-circuits on 'text', '' and 'rest'), so normalizing those two the same way would be consistent, but it rewrites ten further expectations across nine files. Say the word and I add it here, otherwise it is a separate change.

Integration test. tests/Integration/tests/code/literalinclude-without-language, the reproduction from the description run through the CLI. It carries a guides.xml that enables the Code extension: without it the container falls back to packages/guides/resources/template/html/body/code/highlighted-code.html.twig, which is a bare {{ node.value }}, and the filter is never reached — the existing literalinclude fixture never touches the highlighter for that reason.

Both halves were mutated against the new fixture: reverting the filter signature fails it with the original TypeError in body/code/highlighted-code.html.twig, reverting the template fallback fails it on language- vs language-text.

One expectation changed as a consequence: tests/Integration/tests/markdown/code-md. A fenced code block without an info string carries a null language too, so its two language- become language-text.

I also checked body/code.tex.twig, which has the same missing fallback. Nothing to do there: null and '' both render \lstset{language=}, which is the committed expectation for a language-less block in tests/Functional/tests/code/code.tex, so there is nothing null-specific to fix there.

On guessing the language from the file extension: agreed, and out of scope here — happy to open an issue for it if you want it tracked.

Marked as draft while the empty-string question above is open.

[linawolf]

Thanks a lot for your contribution, yes an issue about the auto discovery of the language would be good

[phpdoc-bot]

💔 All backports failed

Status	Branch	Result
❌	1.x	The branch "1.x" does not exist

Manual backport

To create the backport manually run:

backport --pr 1353

Questions ?

Please refer to the Backport tool documentation and see the Github Action logs for details