Part of meta-issue #2571965: [meta] Fix PHP coding standards in core
There are sniffs in Drupal CS that the core passes but not present in phpcs.xml.dist:
- Drupal.Array.DisallowLongArraySyntax
- Drupal.Commenting.FunctionComment.MissingFile
- Drupal.Files.FileEncoding
- Drupal.WhiteSpace.Namespace
- Generic.Files.ByteOrderMark
- MySource.Debug.DebugCode
- PEAR.Files.IncludingFile
- Squiz.PHP.LowercasePHPFunctions
- Zend.Files.ClosingTag
Also phpcs.xml.dist includes Generic.Arrays.DisallowLongArraySyntax #2776975: March 3, 2017: Convert core to array syntax coding standards for Drupal 8.3.x RC phase, but Drupal CS doesn't include it. Instead it uses Drupal.Array.DisallowLongArraySyntax.
Step 1: Preparation
Open the file core/phpcs.xml.dist
and add a line for the sniff of this ticket. The sniff name is in the issue title. Make sure your patch will include the addition of this line.
Step 2: Install & configure PHPCS
Install PHP CodeSniffer and the ruleset from the Coder module:
$ composer install
$ ./vendor/bin/phpcs --config-set installed_paths ../../drupal/coder/coder_sniffer
Once you have installed the phpcs package, you can list all the sniffs available to you like this:
$ ./vendor/bin/phpcs --standard=Drupal -e
This will give you a big list of sniffs, and the Drupal-based ones should be present.
Step 3: Prepare the phpcs.xml file
To speed up the testing you should make a copy of the file phpcs.xml.dist
(in the core/
folder) and save it as phpcs.xml
. This is the configuration file for PHP CodeSniffer.
We only want this phpcs.xml file to specify the sniff we're interested in. So we need to remove all the rule items, and add only our own sniff's rule. Rule items look like this:
<rule ref="Drupal.Classes.UnusedUseStatement"/>
Remove all of them, and add only the sniff from this issue title. This will make sure that our tests run quickly, and are not going to contain any output from unrelated sniffs.
Step 4: Run the test
Now you are ready to run the test! From within the core/
folder, run the following command to launch the test:
$ cd core/
$ ../vendor/bin/phpcs -p
This takes a couple of minutes. The -p
flag shows the progress, so you have a bunch of nice dots to look at while it is running.
Step 5: Fix the failures
When the test is complete it will present you a list of all the files that contain violations of your sniff, and the line numbers where the violations occur. You could fix all of these manually, but thankfully phpcbf
can fix many of them. You can call phpcbf like this:
$ ../vendor/bin/phpcbf
This will fix the errors in place. You can then make a diff of the changes using git. You can also re-run the test with phpcs and determine if that fixed all of them.
Comment | File | Size | Author |
---|---|---|---|
#9 | drupal-coding-standards-2902396-9.patch | 4.42 KB | mfernea |
Comments
Comment #2
mfernea CreditAttribution: mfernea at AmeXio commentedHere is the patch.
Comment #3
mfernea CreditAttribution: mfernea at AmeXio commentedComment #4
mfernea CreditAttribution: mfernea at AmeXio commentedHere is the updated patch.
Comment #5
ccjjmartin CreditAttribution: ccjjmartin as a volunteer commentedThe testing instructions here for reviewers should say to apply the patch and copy the phpcs.xml.dist to phpcs.xml and then run phpcs. I had no errors before the patch and no errors after the patch. In regards to the Drupal specific DisallowLongArraySyntaxSniff that change seems reasonable. In regards to the other Drupal specific standards that also seems like a reasonable change to make.
On the other coding standards I am tempted to say that they might not make it into core. If you want to split those out into a separate issue (that someone with more familiarity on them can review) I will RTBC this one with just the Drupal coding standards (since they are clearly supported by the community). Otherwise we can wait for someone with familiarity on the others to give their two cents.
Comment #6
ccjjmartin CreditAttribution: ccjjmartin as a volunteer commentedNevermind, looked around for where you might have got the other coding standards from and found this spreadsheet in this comment (https://www.drupal.org/node/2571965#comment-11093175) that appears to be a summary of the standards we are pushing for:
https://docs.google.com/spreadsheets/d/1CtpbUdx8F0rGLuVcOOup--pWAhmQz-fL...
Marking this as RTBC.
Comment #7
mfernea CreditAttribution: mfernea at AmeXio commentedFor the sniffs not defined in Drupal CS, I'm looking in the vendor/drupal/coder/coder_sniffer/Drupal/ruleset.xml.
Since we are aiming for full compliance with Drupal CS the phpcs.xml.dist should contain all sniffs inside ruleset.xml (list & configuration).
Comment #9
mfernea CreditAttribution: mfernea at AmeXio commentedHere is the updated patch.
Comment #10
Mile23It'd be cool to have a way to verify that we're really adding all the sniffs are passing. But the patch applies, does proper things like turn off some of the PEAR sub-sniffs like the Drupal standard does, and phpcs reports no errors.
Comment #14
catchCommitted/pushed to 8.5.x and cherry-picked to 8.4.x. Thanks!