ExtDN PHP_CodeSniffer rules for Magento 2
Introduction
There are already many PHP CodeSniffer rules out there to aid in Magento 2 development:
- Magento core ruleset (in folder
dev/tests/static/framework/Magento
) - Magento Extension Quality Program (in short: MEQP)
- Magento Expert Consultancy Group (in short: ECG)
- PSR-1, PSR-2, possibly PSR-12
However, some best practices still need to be integrated and/or some rules do need to be improved. This repository forms an effort to come up with more advanced rulesets than there currently are. Additionally, one of the underlying goals is to create rules that fit Magento core, Magento third party extensions and Magento implements, while they all have different needs.
Usage
To install this package, go to your Magento 2 root and use the following:
composer require extdn/phpcs:dev-master
If this fails because the dependency with magento/marketplace-eqp
fails to load, first add the EQP repo to your configuration and then repeat:
composer config repositories.magento-marketplace-eqp vcs https://github.com/magento/marketplace-eqp
composer require magento/marketplace-eqp:dev-master
composer require extdn/phpcs:dev-master
Once installed, you can run PHPCS from the command-line to analyse your code XYZ
:
vendor/bin/phpcs --standard=./vendor/extdn/phpcs/Extdn app/code/XYZ
vendor/bin/phpcs --standard=./vendor/extdn/phpcs/Extdn vendor/XYZ
If you have a Composer Installer Plugin for PHPCS coding standards (such as https://github.com/Dealerdirect/phpcodesniffer-composer-installer) configured in the project, you can refer to this standard simply by its name:
vendor/bin/phpcs --standard=Extdn app/code/XYZ
vendor/bin/phpcs --standard=Extdn vendor/XYZ
Where to contribute
We need help in the following areas:
- Documentation of existing EQP rules (where each EQP rule could be included in this repository its
ruleset.xml
) - Creation of new PHPCS rules (see below How to contribute)
- Braindumps on where PHPCS lacks and other tools might come in more handy (PhpStan, Phan)
- Discussions on new rules (through periodic hangouts or discussions per GitHub Issue)
Please note that you are also welcome to contribute to the Magento rulesets directly (core, MEQP, ECG - see links above). Likewise, we will try to get ExtDN rules into Magento rulesets as well, which is part of this ExtDN project.
How to contribute
Any contribution is welcome. However, don't start coding just yet. Make sure first that the work is worth the effort.
-
Add a new issue under Issues to address new rulesets that are needed or report other issues.
-
Once the creation of the new rule has been accepted by adding a label
Accepted
under Issues, we're good to go. -
If a similar rule already exists in the core or MEQP or ECG, simply try to include this rule within the ExtDN ruleset.
-
If no rule exists yet, let's create it. As an example, you can use the
SetTemplateInBlockSniff
within the folderExtdn/Sniffs/Blocks
. It can be tested upon a sample file underExtdn/Samples/Blocks
:
vendor/bin/phpcs --standard=./vendor/extdn/phpcs/Extdn vendor/extdn/phpcs/Extdn/Samples
- Once this all works, feel free to create a Pull Request (PR) including the addition of this rule to the
ruleset.xml
file.
Using labels with GitHub issues
Some important labels, used for Github issues:
accepted
: The rule is accepted by extdn. If nobody claimed it yet, you may start working on itexperimental
: The rule can be implemented as well, but we will try it out with a low severity first before integrating it into the official rulesetnon-PHPCS
: The rule is not feasibly implementable with phpcs, will need additional tools. We keep it for later.organizational
: Non-code related issueson agenda of hangout
: The rule/issue will be discussed in the next community hangout
How to create a Sniffer Rule
We recommend to get started by creating a couple of sniffs for your own. The official PHPCS wiki already gives good information. Likewise, the other sniffs in our repos (and the repos of Magento) will give lots of samples anyway.
Testing
All rules should be accompanied with tests.
Within a Magento installation
To run the sniff unit tests from a main repository, where the rules are installed via composer
, first configure phpcs
to find the rules:
vendor/bin/phpcs --config-set installed_paths vendor/extdn/phpcs/Extdn,vendor/magento/marketplace-eqp/MEQP2
Then tests can be run like this:
phpunit -c vendor/extdn/phpcs/phpunit-vendor.xml vendor/extdn/phpcs/Extdn/Tests
In a standalone installation
If you have cloned this GitHub repository on its own for development, use composer
to install things and run the tests:
composer install
composer test
Each Test.php
class should be accompanied by a Test.inc
file to allow for unit testing based upon the PHPCS parent class AbstractSniffUnitTest
. Make sure to include a Test.md
Markdown description which addresses the issue at hand, explains what the rule check for and then also suggests the improvement to be made.