A module that helps to easily apply static code analysers to the project's code. It uses grumphp under the hood with a predefined set of rules based on Magento 2 coding standards but tuned to be less annoying!
After pulling and installing/updating project locally run following command to update local git hooks and install npm packages:
make linters-init
It will add precommit git hook, so on each commit linters will run for the files added to commit.
A commit will fail if linters found errors in your code, check the 'console' tab in 'Git' section of the PhpStorm for errors output by linters. Fix all errors and commit again.
Warning By default Autofix feature is turned ON. Once you try to commit, linters will automatically fix some errors. Double check changes after.
When fixing errors, to see predicted linters output you can instead of trying to commit again just run manually from console:
make precommit
Run vendor/bin/grumphp git:init
to add githook
Grumphp will sniff your code on any git commit
in the linters output you will see hints with rule names being violated. If for some reason you can not fix violated rule feel free to ignore it using Suppress Warning comment corresponding concrete linter type (see hints in output or google).
IMPORTANT! When ignoring a rule in the code always add a comment with the reason of why you had ignored it instead of fixing.
Rules can be tuned with parameters, excluded completely or rewritten on a Project Level
using the ruleset.xml, phpmd.xml, .eslintrc, .stylelint
files in the project's root folder and committing them to project's repo.
If you think everyone can benefit from your rules changes - feel free to create a PR.
To add Code Quality to Bitbucket pipelines as a mandatory step do following.
Add new command to makefile:
analyse-ci:
git fetch --shallow-since=01/09/2021
git diff 111999..HEAD | vendor/phpro/grumphp/bin/grumphp run
'111999' - is your starting commit hash
Add new step to your build like this:
- step: &code-quality
name: "Code Quality"
script:
- if [ ! -f grumphp.yml ] || [ ! -d vendor/space48/magento2-code-quality ]; then printf 'No Space48 Code quality module found'; exit; fi
- /bin/bash -c "[ $(grep '^[ ]*eslint:' grumphp.yml) ] || [ $(grep '^[ ]*stylelint:' grumphp.yml) ] && source vendor/space48/magento2-code-quality/script/npm-install.sh"
- make analyse-ci
To run linters as it would run on CI (from starting commit till HEAD):
make analyse
Use any of this options:
Option 1: Set fixer/enabled
and fixer/fix_by_default
to true in grumphp.yml file
Option 2: Run command vendor/phpro/grumphp/bin/grumphp run
with '--fix' option
vendor/phpro/grumphp/bin/grumphp run --fix
Add Code Quality tool to the Magento Project:
Eslisnt and Stylelint requires NodeJs v10 or higher.
On Magento versions earlier than 2.4 add following to 'require' section of project's composer.json
:
"require": {
...
"symfony/options-resolver": "v2.8.52 as 4.4"
}
Add the module
warden env exec php-fpm composer require --dev space48/magento2-code-quality
When it will ask for 'grumphp.yml' creation - answer no
:
Do you want to create a grumphp.yml file? [Yes]: no
Copy files and install npm packages:
warden env exec php-fpm chmod +x vendor/space48/magento2-code-quality/script/install.sh
warden env exec php-fpm ./vendor/space48/magento2-code-quality/script/install.sh
Add git precommit hook:
chmod +x vendor/space48/magento2-code-quality/script/add-hook.sh
vendor/space48/magento2-code-quality/script/add-hook.sh
Create .git
folder in warden:
(You can mount .git volume from host to inside container instead, but grumphp
only requires empty .git folder,
no much sense in syncronizing all .git/* files adding even more overhead for mutagen.)
warden env exec php-fpm /bin/bash -c '[ -d .git ] || mkdir .git'
Add configuration files to git:
git add ruleset.xml phpmd.xml .eslintrc .stylelintrc grumphp.yml
### Code Quality section
CQ_STARTING_COMMIT_HASH='a000z999'
CQ_STARTING_COMMIT_DATE='01/01/2021'
-include 'vendor/space48/magento2-code-quality/code-quality.mk'
It contains following commands:
linters-init
- init linters on local machineanalyse
- analyses all code from starting commit hash to HEADanalyse-fix
- analyses all code from starting commit hash to HEAD and fixes autofixable errorsprecommit
- analyses code staged for commitprecommit-fix
- analyses code staged for commit and fixes autofixable errorsanalyse-ci
- Same as 'analyse' but modified to be called during build on CI env
Update CQ_STARTING_COMMIT_HASH
variable. Replace the sample a000z999
commit hash with the hash from the project where you want to start linting from.
Files modified after the starting commit hash will be linted during project build and will fail the build on linter violations.
Update CQ_STARTING_COMMIT_DATE
variable. Replace sample 01/01/2021
date with the date of the Starting Commit
(specified at CQ_STARTING_COMMIT_HASH
variable). This is required because CI uses shallow git clone.
Note:
If using warden, commit still fails with SplFileInfo::openFile(/var/www/html/.git/COMMIT_EDITMSG): failed to open st ream: No such file or directory
error: rename or revert to original git 'commit-msg' hook.
Commit updated composer files, vendor folder, code-quality config files from the root and 'makefile' changes
- add module
space48/code-quality
via Composer - run
vendor/space48/code-quality/script/install.sh
script to copy necessary files and install npm packages - in
grumphp.yml
remove configs marked as(remove on non warden environment)
- run
vendor/bin/grumphp git:init
to update precommit hooks
Whitelist/exclude folders can be configured at {project_root}/grumphp.yml
:
phpmd:
whitelist_patterns:
- /^app/
triggered_by: [ 'php', 'phtml' ]
exclude: [ ]
phpcs:
whitelist_patterns:
- /^app/
triggered_by: [ 'php', 'phtml' ]
ignore_patterns: [ ]
eslint:
triggered_by: [ js, jsx, ts, tsx, vue ]
whitelist_patterns: [ /^app/ ]
To turn off whole linter type (for example 'eslint') - remove or comment out corresponding 'task' section.
Linter rules can be finetuned on a project level by editing ruleset.xml, phpmd.xml, .eslintrc, .stylelint
files.
See Space48/code-quality/rulesets/
for examples.
Some rules can be overwritten on a class level. See rulesets/PhpMd/extra.xml
for examples.
For more info and for Configuration help refer to grumphp repo docs.