182 lines
6.9 KiB
ReStructuredText
182 lines
6.9 KiB
ReStructuredText
.. 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
|