--- title: "Feature: #108763 - Console command to analyze Fluid templates" manual: "TYPO3 Core Changelog" version: "main" permalink: "https://docs.typo3.org/permalink/changelog:feature-108763-1769331943" source: "Changelog/14.2/Feature-108763-ConsoleCommandToAnalyseFluidTemplates.rst" typo3-version: "14.2" typo3-major: 14 type: "feature" issue: 108763 forge: "https://forge.typo3.org/issues/108763" tags: ["CLI", "Fluid", "ext:fluid"] rendered: "2026-09-20T18:31:11+00:00" --- # Feature: #108763 - Console command to analyze Fluid templates {#feature-108763-1769331943} See [forge#108763](https://forge.typo3.org/issues/108763) ## Description {#description} The `typo3 fluid:analyze` console command is introduced, which analyzes Fluid templates in the current project for correct Fluid syntax and reports deprecations that are emitted during template parsing. Usage: ```bash vendor/bin/typo3 fluid:analyze ``` Example output: ``` [DEPRECATION] packages/myext/Resources/Private/Templates/Test.fluid.html: has been deprecated in X and will be removed in Y. [ERROR] packages/myext/Resources/Private/Templates/Test2.fluid.html: Variable identifiers cannot start with a "_": _temp ``` In its initial implementation, the command automatically finds all Fluid templates within the current project based on the `*.fluid.*` file extension (see [Feature: #108166 - Fluid file extension and template resolving](https://docs.typo3.org/permalink/changelog:feature-108166-1763400992)) and analyzes them. By default, TYPO3 system extensions are skipped. This can be adjusted by specifying the `--include-system-extensions` CLI option. The following errors and deprecations are currently supported: - Fluid syntax errors (for example, invalid nesting of ViewHelper tags) - Usage of invalid ViewHelpers or ViewHelper namespaces - Usage of variable names that start with `_` (see [Breaking: #108148 - Disallow Fluid variable names with underscore prefix](https://docs.typo3.org/permalink/changelog:breaking-108148-1763288414)) - Usage of deprecated ViewHelpers or ViewHelper arguments (if deprecation is triggered during parse time, see [Deprecating ViewHelpers](https://docs.typo3.org/permalink/changelog:feature-108763-1769331943-deprecating-viewhelpers) and [Deprecating ViewHelper arguments](https://docs.typo3.org/permalink/changelog:feature-108763-1769331943-deprecating-viewhelper-arguments)) If exceptions are caught during the parsing process of at least one template, the console command will have a return status of 1 (error). Otherwise, it will return 0 (success). This means that deprecations are not interpreted as errors. This should make it possible to use the command in CI workflows of most projects, since deprecated functionality used by third-party templates will not make the pipeline fail. Verbose output allows users to get feedback on the analyzed templates and the number of errors and deprecations, or success. ### Integration with other tools {#feature-108763-1769331943-tool-integration} The command also supports input of a template string via `STDIN` as well as machine-readable output as JSON. This enables better integration with other development-related tools. Usage: ```bash echo " {_invalidVariable}" | vendor/bin/typo3 fluid:analyze --stdin --json ``` Example output (formatted): ```json { "identifier": "template__5adb1a7702b9dcbf", "path": "php:\/\/stdin", "errors": [ { "file": "\/var\/www\/html\/vendor\/typo3fluid\/fluid\/src\/Core\/Parser\/TemplateParser.php", "line": 130, "message": "Fluid parse error in template php:\/\/stdin, line 2 at character 27. Error: Variable identifiers cannot start with a \"_\": _invalidVariable (error code 1765900762). Template source chunk: {_invalidVariable}\n", "templateLocation": { "identifierOrPath": "php:\/\/stdin", "line": 2, "character": 27 } } ], "deprecations": [ { "file": "\/var\/www\/html\/typo3\/sysext\/form\/Classes\/ViewHelpers\/Form\/TimePickerViewHelper.php", "line": 143, "message": "The TimePickerViewHelper is deprecated since TYPO3 v14 and will be removed in v15." } ] } ``` ### Deprecating ViewHelpers {#feature-108763-1769331943-deprecating-viewhelpers} The `fluid:analyze` console command can catch deprecations of whole ViewHelpers if the deprecation is emitted during the parse time of a template. This is possible by implementing the `ViewHelperNodeInitializedEventInterface`: **ObsoleteViewHelper.php** ```php use TYPO3Fluid\Fluid\Core\Parser\ParsingState; use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode; use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper; use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperNodeInitializedEventInterface; /** * @deprecated since X, will be removed in Y. */ final class ObsoleteViewHelper extends AbstractViewHelper implements ViewHelperNodeInitializedEventInterface { // ... public static function nodeInitializedEvent(ViewHelperNode $node, array $arguments, ParsingState $parsingState): void { trigger_error( ' has been deprecated in X and will be removed in Y.', E_USER_DEPRECATED, ); } } ``` ### Deprecating ViewHelper arguments {#feature-108763-1769331943-deprecating-viewhelper-arguments} The `ViewHelperNodeInitializedEventInterface` can be used to deprecate a ViewHelper argument. The deprecation is only triggered if the argument is actually used in a template. **SomeViewHelper.php** ```php use TYPO3Fluid\Fluid\Core\Parser\ParsingState; use TYPO3Fluid\Fluid\Core\Parser\SyntaxTree\ViewHelperNode; use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper; use TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperNodeInitializedEventInterface; final class SomeViewHelper extends AbstractViewHelper implements ViewHelperNodeInitializedEventInterface { public function initializeArguments(): void { // @deprecated since X, will be removed in Y. $this->registerArgument('obsoleteArgument', 'string', 'Original description. Deprecated since X, will be removed in Y'); } public static function nodeInitializedEvent(ViewHelperNode $node, array $arguments, ParsingState $parsingState): void { if (array_key_exists('obsoleteArgument', $arguments)) { trigger_error( 'ViewHelper argument "obsoleteArgument" in is deprecated since X and will be removed in Y.', E_USER_DEPRECATED, ); } } } ``` ## Impact {#impact} The new `typo3 fluid:analyze` console command can be used to check basic validity of Fluid templates in projects that use the `*.fluid.*` file extension and to discover deprecated functionality in template files.