README

作者

Martin Helmich (typo3 at martin-helmich dot de)

内容

概述
为什么？
入门
- 设置
- 使用
- 示例
代码验证
- 功能
- 配置
文章
未来功能

概述

此包包含一个工具，可以将TYPO3的配置语言"TypoScript"解析成语法树，并对解析后的代码进行静态代码分析。typoscript-lint可以生成兼容Checkstyle的输出，并可用于持续集成环境。

为什么？

该项目最初是一个私人编程练习。我正在为T3N杂志撰写关于TYPO3项目的持续集成文章，介绍JSHint或CSSLint等工具，并注意到没有可比较的TypoScript工具。所以我心想，“那又怎样，让我们试试看” ，在某个时候意识到我的这个小编程练习可能对某个人有用。所以，就是这样。祝您好运。

入门

设置（使用Composer）

使用Composer安装typo3-typoscript-lint

composer require --dev helmich/typo3-typoscript-lint

当然，如果您的TYPO3项目也是基于Composer的，则效果最好。如果不是，您也可以使用composer global命令全局安装 Linter

composer global require helmich/typo3-typoscript-lint

设置（使用Phive）

或者，您还可以使用Phive安装typo3-typoscript-lint

phive install martin-helmich/typo3-typoscript-lint

在这种情况下，它将安装到当前目录的./tools文件夹中

./tools/typoscript-lint path/to/your.typoscript

使用

按照以下方式调用typo3-typoscript-lint

vendor/bin/typoscript-lint path/to/your.typoscript

默认情况下，它将在控制台打印报告。要生成一个checkstyle格式的XML文件，请按以下方式调用

vendor/bin/typoscript-lint -f xml -o checkstyle.xml path/to/your.typoscript

要生成一个符合GNU编码标准的报告，请按以下方式调用

vendor/bin/typoscript-lint -f gcc path/to/your.typoscript

示例

代码验证

功能

代码验证的某些方面被组织成所谓的“sniffs”（我从PHP的CodeSniffer项目借用了这个术语）。目前，有针对以下常见错误或代码臭味的TypoScript的sniffs

缩进

缩进级别应该随着每个嵌套语句的增加而增加。在配置文件中，您可以定义您是否更喜欢使用制表符或空格进行缩进。

foo {
    bar = 2
  baz = 5
# ^----------- This will raise a warning!
}

默认情况下，缩进sniff期望TypoScript条件内的代码没有缩进。您可以通过将缩进sniff的indentConditions标志设置为true在您的typoscript-lint.yml配置文件中（见下文）来更改此行为。

死代码

被注释掉的代码只是使源代码杂乱无章，并阻碍可读性。删除它，您有版本控制（您确实使用版本控制，对吧？）。

foo {
    bar.baz = 5
    #baz.foo = Hello World
#   ^----------- This will raise a warning!
}

空白字符

检查是否在您的运算符周围有多余的空白字符。

#   v----------- This will raise a warning (one space too much)
foo  {
    bar= 3
#      ^-------- This will also raise a warning (one space too few)
}

重复的值

如果相同的值分配给了不同的对象，将这个值提取为TypoScript常量可能很有用。

foo {
    bar = Hello World
    baz = Hello World
#         ^----- Time to extract "Hello World" into a constant!

默认情况下，任何长度为8个字符或更长的值，如果重复出现多次，则会触发警告。您可以通过设置配置文件中 RepeatingRValueSniff 的 valueLengthThreshold 参数来配置此阈值。

也可以将某些允许重复的值列入白名单。您可以在配置文件中的 allowedRightValues 参数中设置这些值。

重复分配

将值分配给同一对象多次。即使在嵌套语句中也可以。

foo {
    bar = baz
#   ^----------- This statement is useless, because foo.bar is unconditionally overwritten!
}
foo.bar = test

但是，嗅探器足够智能，可以检测条件覆盖。因此，以下代码将不会触发警告

foo {
    bar = baz
}

[globalString = ENV:foo = bar]
foo.bar = test
[global]

嵌套一致性

此嗅探器检查嵌套分配是否以一致的方式使用。考虑以下示例

foo {
    bar = test1
}

foo {
    baz = test2
}

在这种情况下，两个嵌套语句完全可以合并为一个语句。

再考虑另一个示例

foo {
    bar = test1
}

foo.baz {
    bar = test2
}

在这种情况下，两个语句可以相互嵌套。

空块

对空分配块发出警告

foo {
}

不建议使用 config.no_cache = 1

对使用 config.no_cache = 1 发出警告。相反，应使用 USER_INT 或 COA_INT。

配置

typoscript-lint 在当前工作目录中查找 typoscript-lint.yml 文件。如果找到该文件，则将其与安装根目录中的 typoscript-lint.dist.yml 合并。查看此文件了解您可以配置的内容（当然，目前还不太多）

注意：此工具的先前版本使用 tslint.yml 文件名作为它们的配置文件。这与同名工具用于检查 TypeScript 的工具冲突，因此被认为是过时的（尽管仍然支持旧文件名）。

可以在配置文件中的 paths 键下设置要检查的路径
```
paths:
  - directory/with/typoscript
  - ...
```
您还可以使用 * 字符来匹配多个文件或目录
```
paths:
  - typo3conf/ext/yourprefix_*/Configuration/TypoScript
```
在配置文件中的 sniff 键下配置单个嗅探器。此键由一个对象列表组成，每个对象都有一个 class 键和一个可选的 parameters 键。

由于本地配置文件将与分布式配置文件合并，因此您不能通过简单地从本地配置文件中删除它们来禁用嗅探器（有关更多信息，请参阅此错误报告）。要禁用嗅探器，请使用 disabled 配置属性。例如，要禁用 DeadCode 嗅探器
```
sniffs:
  - class: DeadCode
    disabled: true
```
在 filePatterns 键中配置应被视为 TypoScript 文件的文件扩展名。此键可能包含需要检查的文件必须匹配的 glob 模式列表。当您在目录树上运行 typoscript-lint 时，这特别相关
```
filePatterns:
  - "*.typoscript"
  - "setup.txt"
  - # ...
```
如果您有某些文件希望明确排除在检查之外，即使它们与上面的 filePatterns 匹配，您也可以指定额外的 excludePatterns
```
filePatterns:
  - "*.typoscript"
excludePatterns:
  - "Constants.typoscript"
```

文章

TYPO3 项目中的代码质量
TYPO3 项目的持续集成（德语）
通过 Daniel Siepmann 集成 TYPO3 Linting 与 Gitlab CI by Daniel Siepmann
将 Typoscript 检查器集成到 VIM 中 by Daniel Siepmann

未来功能

更多代码气味嗅探器（欢迎提出想法）
全面测试覆盖率（不，我没有进行 TDD。真遗憾。）
自动修复找到的错误

helmich / typo3-typoscript-lint

维护者

详细信息