staempfli / typo3-conventions-checker
Enforces code quality guidelines for TYPO3 CMS projects
Requires
- php: ^7.0
- friendsofphp/php-cs-fixer: *
- phpmd/phpmd: *
- phpro/grumphp: *
This package is auto-updated.
Last update: 2024-10-12 00:38:57 UTC
README
What does it do?
This package lets you automatically test any changed code against the TYPO3 file formatting requirements right before you commit your changes. It also forces you to keep the commit messages tidy, according to the TYPO3 contribution workflow. There are some checks we're leaving out, though, as the commit message structure applies to TYPO3 core contributions and we're not usually committing to the core repository in our projects, eh.
This works via Git hooks, so every time you type 'git commit ...', the configured GrumPHP tasks get fired.
The package itself doesn't do much, honestly. :) It provides some configuration and requires some dependencies to get your code quality and conventions checks set up in no time.
But how does it do it?
Pretty simple. It requires GrumPHP which hits up the PHP Coding Standards Fixer and well as the PHP Mess Detector on each and every commit of yours. Only the files you're trying to commit are getting checked for any coding standards violations or code messes.
Installing
Prerequisites / TYPO3 project setup
This package expects you work with a composer-based TYPO3 setup, having a (probably versioned) composer manifest outside your public html directory called 'web' (though you may of course reconfigure this directory's name). Something along the lines of:
- your-typo3-project/
- bin
- vendor
(...)
- composer.json
- web
- fileadmin
- typo3
- typo3conf
(...)
- Reference the GrumPHP configuration file (
grumphp.yml
) in the "extra" section of your root composer manifest:
(...) "extra": { "grumphp": { "config-default-path": "vendor/staempfli/typo3-conventions-checker/conf/grumphp.yml" } }
(Alternatively, you can create a custom grumphp.yml file in your git root directory, this will work as well).
- Require this package via composer
composer require --dev "staempfli/typo3-conventions-checker"
- Commit changes to your project. All checks will be run automagically on commit.
Options and Customizing
Default configuration
Per default, this package uses
- a php-cs-fixer configuration corresponding to the TYPO3 core php-cs-fixer configuration
- Git commit message rules, mainly integrating the TYPO3 core commit message format, excluding the ones specific to the TYPO3 core contribution workflow such as the 'Releases' and/or 'Change-Id' requirements
- (see full configuration in /conf/grumphp.yml)
Override (i.e. 'extend') configuration
For this to work, you need to create your own grumphp.yml in your git root directory according to the GrumPHP configuration. In there, you may reference this package's grumphp configuration and override the settings.
Important notice on inheritance: To my knowledge, it is not possible to recursively inherit task settings, meaning: you override one property/setting of a task (see example below), you need to re-define all tasks and their settings. See the grumphp configuration provided for extensions.
Example 1: Reconfiguring the git commit message restrictions
Let's say you want to limit the git commit message length
to 42 characters. Update your
grumphp.yml
from
imports: - { resource: vendor/staempfli/typo3-conventions-checker/conf/grumphp.yml }
to something like
imports: - { resource: vendor/staempfli/typo3-conventions-checker/conf/grumphp.yml } parameters: tasks: git_commit_message: max_subject_width: 42 (other tasks' configuration with or without customization)
Example 2: Customizing the php-cs-fixer configuration
Like in the first example: reconfigure this via the grumphp configuration. This time though, reference a different (your own) php-cs-fixer configuration:
imports: - { resource: vendor/staempfli/typo3-conventions-checker/conf/grumphp.yml } parameters: tasks: phpcsfixer2: config: 'your/own/PhpCsFixer/conf.php' (other tasks' configuration with or without customization)
Initializing extensions
Let's say, you maintain an extension 'mynews' and of course, you want the code of 'mynews' to comply with some coding standards as well. You're working on the main project, where 'mynews' is included as a dependency but you'll probably introduce changes to 'mynews' while working on the main project. But, because 'mynews' is its own git repository, it doesn't get checked by GrumPHP automatically if you just initialized GrumPHP on your main project as described above.
- main-typo3-project/
- composer.json
- web
- fileadmin
- typo3
- typo3conf
- ext
- mynews <= doesn't get initialized by GrumPHP
(...)
Lucky you! You're just 2 baby steps away from forcing all commits to 'mynews' to get checked by GrumPHP.
- Add a reference to a grumphp.yml configuration via composer manifest of the 'mynews' extension or create a custom grumphp.yml in the extension's root directory. Note that this package already provides a dedicated grumphp configuration that respects the extension directory nesting.
Via 'extra' section of the composer manifest of the extension:
(...) "extra": { "grumphp": { "config-default-path": "./../../../../vendor/staempfli/typo3-conventions-checker/conf/grumphp-extensions.yml" } }
Via grumphp.yml in the root directory of the extension:
imports: - { resource: ./../../../../vendor/staempfli/typo3-conventions-checker/conf/grumphp-extensions.yml }
- In your root composer manifest, run the 'initializeExtensions'
method via composer scripts. Let's say, after each
composer update
, eh?
(...) "scripts": { "post-update-cmd": [ "Staempfli\\Typo3ConventionsChecker\\Composer\\Grumphp::initializeExtensions", ], }, (...)
Windows users
There currently is a bug, which leads to wrong paths of the grumphp
executable in the git hooks when used inside extensions as described
above. You might experience git cli responding with an error that the
GrumPHP executable could not be found. The reason for that is the
wrong registration in .git/hooks/pre-commit
as well as
.git/hooks/commit-message
.
Solution: In the files mentioned above, the calls to GrumPHP might look something like this:
# Run GrumPHP
(cd "./" && printf "%s\n" "${DIFF}" | exec X:\path\to\your-site\web\vendor\bin\grumphp git:pre-commit '--skip-success-output')
Notice that the path to the GrumPHP executable is not in enclosed in quotes and will lead to errors. Just enclose "X:\path (...) grumphp" in double quotes and you're all set:
# Run GrumPHP
(cd "./" && printf "%s\n" "${DIFF}" | exec "X:\path\to\your-site\web\vendor\bin\grumphp" git:pre-commit '--skip-success-output')