helmich / typo3-typoscript-lint
Static code analysis for the TypoScript configuration language.
Fund package maintenance!
martin-helmich
donate.helmich.me
Installs: 1 756 478
Dependents: 166
Suggesters: 0
Security: 0
Stars: 82
Watchers: 11
Forks: 19
Open Issues: 13
Requires
- php: ^8.1
- ext-json: *
- helmich/typo3-typoscript-parser: ^2.3
- symfony/config: ^5.4 || ^6.4 || ^7.0
- symfony/console: ^5.4 || ^6.4 || ^7.0
- symfony/dependency-injection: ^5.4 || ^6.4 || ^7.0
- symfony/event-dispatcher: ^5.4 || ^6.4 || ^7.0
- symfony/filesystem: ^5.4 || ^6.4 || ^7.0
- symfony/finder: ^5.4 || ^6.4 || ^7.0
- symfony/yaml: ^5.4 || ^6.4 || ^7.0
Requires (Dev)
- mikey179/vfsstream: ^1.6.11
- phpspec/prophecy-phpunit: ^2.0.2
- phpunit/phpunit: ^9.6.8
- vimeo/psalm: ^5.22.2
- dev-master
- v3.2.1
- v3.2.0
- v3.1.1
- v3.1.1-alpha1
- v3.1.0
- v3.0.0
- v2.x-dev
- v2.5.2
- v2.5.1
- v2.5.0
- v2.4.1
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.1
- v2.1.0
- v2.0.1
- v2.0.0
- v1.5.0
- v1.4.7
- v1.4.6
- v1.4.5
- v1.4.4
- v1.4.3
- v1.4.2
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.1
- v1.0.0
- dev-dependabot/add-v2-config-file
- dev-task/php8
- dev-bugfix/fix-phar-pkg-workflow
- dev-feature/auto-fixing
- dev-feature/path-glob
- dev-bugfix/multiple-search
- dev-bugfix/config-file-optional
- dev-bugfix/fck-you-symfony
This package is auto-updated.
Last update: 2024-11-03 14:02:42 UTC
README
Author
Martin Helmich (typo3 at martin-helmich dot de)
Contents
Synopsis
This package contains a tool that can parse TYPO3's configuration language,
"TypoScript", into an syntax tree and perform static code analysis on the
parsed code. typoscript-lint
can generate Checkstyle-compatible output and can be used
in Continuous Integration environments.
Why?!
This project started of as a private programming excercise. I was writing an article for the T3N magazine on Continuous Integration for TYPO3 projects, introducing tools like JSHint or CSSLint, and I noticed that no comparable tools exist for TypoScript. So I thought, "What the heck, let's go" and at some point realized that my little programming excercise might actually be useful to someone. So, that's that. Enjoy.
Getting started
Setup (using Composer)
Install typo3-typoscript-lint with Composer:
composer require --dev helmich/typo3-typoscript-lint
Of course, this works best if your TYPO3 project is also Composer-based. If it isn't, you can also install the Linter globally using the composer global
command:
composer global require helmich/typo3-typoscript-lint
Setup (using Phive)
Alternatively, you can also install typo3-typoscript-lint with Phive:
phive install martin-helmich/typo3-typoscript-lint
In this case, it will be installed into the ./tools
folder of your current directory:
./tools/typoscript-lint path/to/your.typoscript
Usage
Call typo3-typoscript-lint as follows:
vendor/bin/typoscript-lint path/to/your.typoscript
By default, it will print a report on the console. To generate a checkstyle-format XML file, call as follows:
vendor/bin/typoscript-lint -f xml -o checkstyle.xml path/to/your.typoscript
To generate a report formatted according to the GNU Coding Standards, call as follows:
vendor/bin/typoscript-lint -f gcc path/to/your.typoscript
Example
Code validation
Features
Certain aspects of code validation are organized into so-called "sniffs" (I borrowed the term from PHP's CodeSniffer project). Currently, there are sniffs for checking the following common mistakes or code-smells in TypoScript:
Indentation
The indentation level should be increased with each nested statement. In the configuration file, you can define whether you prefer tabs or spaces for indentation.
foo {
bar = 2
baz = 5
# ^----------- This will raise a warning!
}
By default, the indentation sniff expects code inside TypoScript conditions to
be not indented. You can change this behaviour by setting the
indentConditions
flag for the indentation sniff to true
in your typoscript-lint.yml
configuration file (see below).
Dead code
Code that was commented out just clutters your source code and obstructs readability. Remove it, that's what you have version control for (you do use version control, do you?).
foo {
bar.baz = 5
#baz.foo = Hello World
# ^----------- This will raise a warning!
}
Whitespaces
Check that no superflous whitespace float around your operators.
# v----------- This will raise a warning (one space too much)
foo {
bar= 3
# ^-------- This will also raise a warning (one space too few)
}
Repeating values
If the same value is assigned to different objects, it might be useful to extract this into a TypoScript constant.
foo {
bar = Hello World
baz = Hello World
# ^----- Time to extract "Hello World" into a constant!
By default, any value with a length of 8 characters or more will trigger a warning if it is repeated more than once. You can configure this threshold by setting the valueLengthThreshold
parameter for the RepeatingRValueSniff
in your configuration file.
It is also possible to whitelist certain values that are allowed to repeat. You can set those in the allowedRightValues
parameter in your configuration file.
Duplicate assignments
Assigning a value to the same object multiple times. Works across nested statements, too.
foo {
bar = baz
# ^----------- This statement is useless, because foo.bar is unconditionally overwritten!
}
foo.bar = test
The sniff is however smart enough to detect conditional overwrites. So the following code will not raise a warning:
foo {
bar = baz
}
[globalString = ENV:foo = bar]
foo.bar = test
[global]
Nesting consistency
This sniff checks if nesting assignments are used in a consistent manner. Consider the following example:
foo {
bar = test1
}
foo {
baz = test2
}
In this case, the two nested statements might very well be merged into one statement.
Consider another example:
foo {
bar = test1
}
foo.baz {
bar = test2
}
In this case, both statements could be nested in each other.
Empty blocks
Raises warnings about empty assignment blocks:
foo {
}
Discourage config.no_cache = 1
Raises warning about usage of config.no_cache = 1
.
Instead USER_INT or COA_INT should be used.
Configuration
typoscript-lint
looks for a file typoscript-lint.yml
in the current working directory.
If such a file is found, it will be merged with the typoscript-lint.dist.yml
from the
installation root directory. Have a look at said file for an
idea of what you can configure (granted, not much yet):
Note: Previous versions of this tool used the filename tslint.yml
for their
configuration files. This conflicted with the same-named tool for linting TypeScript,
and is thus considered deprecated (although the old file names are still supported).
-
The paths to lint can be set under the
paths
key:paths: - directory/with/typoscript - ...
You can also use the
*
character to match multiple files or directories:paths: - typo3conf/ext/yourprefix_*/Configuration/TypoScript
-
Configure individual sniffs under the
sniff
key in the configuration file. This key consists of a list of objects, each with aclass
key and an optionalparameters
key.Since a local configuration file will be merged with the distributed configuration file, you cannot disable sniffs by simply removing them from the local configuration file (see this bug report for more information). To disable a sniff, use the
disabled
configuration property. For example, to disable theDeadCode
sniff:sniffs: - class: DeadCode disabled: true
-
Configure file extensions that should be treated as TypoScript files in the
filePatterns
key. This key may contain a list of glob patterns that inspected files need to match. This is especially relevant when you're runningtyposcript-lint
on entire directory trees:filePatterns: - "*.typoscript" - "setup.txt" - # ...
If you have certain files you want to explicitly exclude from linting even if they match the
filePatterns
above, you can specify additionalexcludePatterns
:filePatterns: - "*.typoscript" excludePatterns: - "Constants.typoscript"
Articles
- Code Quality in TYPO3 Projects
- Continuous Integration in TYPO3 Projects (German)
- Integrate TYPO3 Linting with Gitlab CI by Daniel Siepmann
- Integrate Typoscript linter into VIM by Daniel Siepmann
Future features
- Sniffs for more code smells (ideas are welcome)
- Full test coverage (no, I did not do TDD. Shame on me.)
- Automated fixing of found errors