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

Neither of these packages is 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.Semantics.FunctionAlias"/>

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 -s

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. The -s flag displays the sniff name in the error report for convenience.

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 some of the errors in place.

You can then make a diff of the changes using git. This will show you what phpcbf did. It might have done the wrong thing, so you must review the changes.

You must also re-run the test with phpcs and determine whether all the errors were actually fixed.

If not, go through again and make appropriate changes.

Then upload your patch with the changes to code and your change to core/phpcs.xml.dist.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Mile23 created an issue. See original summary.

Mile23’s picture

Status: Active » Needs review
FileSize
13.92 KB

This patch adds the new rule and makes all the changes, except for two.

The rule says to replace dir() with getdir(), which doesn't exist. This error is thrown for core/includes/file.inc and core/lib/Drupal/Core/Composer/Composer.php

Filed this issue on Coder: #2764451: Check validity of Drupal.Semantics.FunctionAlias.FunctionAlias replacements

dawehner’s picture

The rule says to replace dir() with getdir(), which doesn't exist. This error is thrown for core/includes/file.inc and core/lib/Drupal/Core/Composer/Composer.php

Should we put a coding standards ignore for now or fix coder itself first?

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

klausi’s picture

Status: Needs review » Needs work

Patch looks good, but I think we should exclude the 2 files in phpcs.xml.dist for this sniff while there is no new release of Coder. Then people can still run phpcs with Coder 8.2.9 without getting errors for those files.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

mfernea’s picture

Status: Needs work » Needs review
FileSize
14.93 KB

Here is the patch.

Status: Needs review » Needs work

The last submitted patch, 8: drupal-coding-standards-2759789-8.patch, failed testing. View results

Mile23’s picture

Status: Needs work » Reviewed & tested by the community

The patch applies to both 8.5.x and 8.4.x.

Locally gives me no PHPCS errors remaining.

The coder issue is fixed: #2764451: Check validity of Drupal.Semantics.FunctionAlias.FunctionAlias replacements

Drupal 8.5.x is using the fixed version:

$ composer show *coder
drupal/coder 8.2.12 Coder is a library to review Drupal code.

Not sure about the failing test, since the patch doesn't touch outside_in. It appears to be a random fail test: #2829040: [meta] Known intermittent, random, and environment-specific test failures #2901626: CSS animations cause \Drupal\Tests\outside_in\FunctionalJavascript\OutsideInBlockFormTest random fails

I'm calling this RTBC despite the fail.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 8: drupal-coding-standards-2759789-8.patch, failed testing. View results

mfernea’s picture

Status: Needs work » Needs review
FileSize
14.85 KB

Here is the updated patch.

mfernea’s picture

@Mile23: Are you available for a review? :)

borisson_’s picture

Status: Needs review » Reviewed & tested by the community

Looks solid.

xjm’s picture

Status: Reviewed & tested by the community » Needs work

We've added a rule to ignore the Diff component, so hunks changing it should be removed from the patch. Also, the patch no longer applies.

Thanks!

mfernea’s picture

Status: Needs work » Needs review
FileSize
9.16 KB

Updated patch excluding modifications to Diff component.

andriyun’s picture

Status: Needs review » Reviewed & tested by the community

Look good to me
* the Diff component changes are no longer present in the patch
* phpcs has no fails after patch applying
* patch contains changes related only to issue sniff
* phpcs.dist.xml changes has been added added

andriyun’s picture

  • xjm committed 465348f on 8.5.x
    Issue #2759789 by mfernea, Mile23, andriyun, dawehner, klausi: Fix '...

  • xjm committed 384ebfb on 8.4.x
    Issue #2759789 by mfernea, Mile23, andriyun, dawehner, klausi: Fix '...
xjm’s picture

Version: 8.5.x-dev » 8.4.x-dev
Status: Reviewed & tested by the community » Fixed
+++ b/core/modules/simpletest/simpletest.module
@@ -363,7 +363,7 @@ function simpletest_phpunit_run_command(array $unescaped_test_classnames, $phpun
-  $ret = exec(join($command, " "), $output, $status);
+  $ret = exec(implode(" ", $command), $output, $status);

This one made me do a double-take; I forgot that old chestnut about how implode() accepts arguments in either order. I guess the coder rule enforces $glue, array $pieces.

Committed and pushed to 8.5.x, and backported to 8.4.x as a coding standards cleanup during RC. Thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.