Part of #2571965: [meta] Fix PHP coding standards in core.
Approach
We are testing coding standards with PHP CodeSniffer, using the Drupal coding standards from the Coder module. Both of these packages are not installed in Drupal core. We need to do a couple of steps in order to download and configure them so we can run a coding standards check.
Step 1: Add the coding standard to the whitelist
Every coding standard is identified by a "sniff". For example, an imaginary coding standard that would require all llamas to be placed inside a square bracket fence would be called the "Drupal.AnimalControlStructure.BracketedFence
sniff". There are dozens of such coding standards, and to make the work easier we have started by only whitelisting the sniffs that pass. For the moment all coding standards that are not yet fixed are simply skipped during the test.
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 PHP CodeSniffer and the ruleset from the Coder module
Both of these packages are not installed by default in Drupal core, so we need to download them. This can be done with Composer, from the root folder of your Drupal installation:
$ composer require drupal/coder squizlabs/php_codesniffer
$ ./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.Commenting.DocComment.ParamGroup"/>
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 |
---|---|---|---|
#15 | 3123058-15.patch | 5.91 KB | longwave |
Comments
Comment #2
jungleCopy and paste from another issue, but I think
+ should be -
If so, all IS of commenting related child issues need updating.
Comment #3
jungleComment #5
longwave#2060925: False-positives for @code/@endcode by Drupal.Commenting.DocCommentSniff and Drupal.Commenting.DocCommentAlignment sniff is fixed so we can remove a redundant comment as well.
Comment #6
jungleThanks @longwave! Attaching a test only patch to prove that the rule enabled can detected violations as expected.
Comment #7
jungle12 to fix in total, 11 of them are fixed by simply removing an empty line (literally, non-empty lines, as they contain whitespaces and a *). the special one gets adjusted. So #5 is RTBC to me.
Comment #8
jungleSorry, the number does not match. it's 14. reviewing again.
Comment #9
jungleRemove the comment is good, as #2060925 was in
The adjustment here is good, no lines exceed 80 chars, and no word(s) should move to the previous/next line.
The rest are removing unnecessary "empty" lines.
Comment #10
xjmSo, hm, this rule seems to be wrong. These are legitmate newlines, to create new paragraphs for readability. I guess the false positives are the combination of the
@code
and blank lines?If we have a look at UiHelperTrait::drupalPostForm(), the blank lines there help with readability. The code groups seem to add whitespace before but not after. I'd also argue the source is hard to read without symmetrical blank lines around the paragraph.
I think we might need to make this sniff smarter before we enable it. Leaving RTBC for the moment but wanted to note the concern.
Comment #11
longwaveIs this whole paragraph with the example too much to stuff into an @param, it could just be in the main body of the docblock instead I think.
Comment #12
xjm@longwave That'd be a simple workaround, but I still think the sniff itself is wrong here. I can't remember whether multi-paragraph
@param
works on api.d.o, but I quickly found an example of a multi-paragraph return formatted correctly on api.d.do:hook_menu_links_discovered_alter()
The sniff also is only flagging multiple paragraphs with
@code
blocks inside them, so it's a false positive. You can test this by:Since it only flags one of the changes and not both, I think this means the sniff needs work. So, I think we should file an issue in the coder queue, and then postpone this issue on fixing the sniff. Setting NR to look into that. Not so much as "Needs followup" as "Needs blocker" but you get the idea. :)
Comment #13
daffie CreditAttribution: daffie commentedThe testbot returns with the following coding standard messages:
Comment #15
longwaveThe @code issue appears to be fixed upstream in Coder, there are not many fixes needed in order to enable this sniff now.
Comment #16
SpokjeRTBC for me.
Comment #17
alexpottCommitted 93084ba and pushed to 9.2.x. Thanks!
Committed 0d2a8ca and pushed to 9.1.x. Thanks!
Backported everything apart from the phpcs.xml.dist changes to 9.1.x to keep the code aligned.