..  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: <my:obsolete> 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 <feature-108166-1763400992>`)
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 <breaking-108148-1763288414>`)
*   Usage of deprecated ViewHelpers or ViewHelper arguments (if deprecation
    is triggered during parse time, see
    :ref:`Deprecating ViewHelpers <feature-108763-1769331943-deprecating-viewhelpers>`
    and
    :ref:`Deprecating ViewHelper arguments <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.

..  _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 "<formvh:form.timePicker /> {_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(
                '<my:obsolete> 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 <my:some> 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
