.. include:: /Includes.rst.txt .. _feature-108763-1769331943: ============================================================= Feature: #108763 - Console command to analyze Fluid templates ============================================================= See :issue:`108763` Description =========== The :bash:`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: .. code-block:: bash vendor/bin/typo3 fluid:analyze Example output: .. code-block:: [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 :ref:`Feature: #108166 - Fluid file extension and template resolving `) and analyzes them. By default, TYPO3 system extensions are skipped. This can be adjusted by specifying the :bash:`--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 :ref:`Breaking: #108148 - Disallow Fluid variable names with underscore prefix `) * Usage of deprecated ViewHelpers or ViewHelper arguments (if deprecation is triggered during parse time, see :ref:`Deprecating ViewHelpers ` and :ref:`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. .. _feature-108763-1769331943-tool-integration: Integration with other tools ---------------------------- 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: .. code-block:: bash echo " {_invalidVariable}" | vendor/bin/typo3 fluid:analyze --stdin --json Example output (formatted): .. code-block:: 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." } ] } .. _feature-108763-1769331943-deprecating-viewhelpers: Deprecating ViewHelpers ----------------------- The :bash:`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 :php-short:`\TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperNodeInitializedEventInterface`: .. code-block:: php :caption: ObsoleteViewHelper.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, ); } } .. _feature-108763-1769331943-deprecating-viewhelper-arguments: Deprecating ViewHelper arguments -------------------------------- The :php-short:`\TYPO3Fluid\Fluid\Core\ViewHelper\ViewHelperNodeInitializedEventInterface` can be used to deprecate a ViewHelper argument. The deprecation is only triggered if the argument is actually used in a template. .. code-block:: php :caption: SomeViewHelper.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 ====== The new :bash:`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. .. index:: CLI, Fluid, ext:fluid