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="PSR2.Classes.PropertyDeclaration.Underscore"/>

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.

CommentFileSizeAuthor
#12 3123070-12.patch861 bytesSpokje
#3 phpcs.txt1.41 KBmsuthars

Issue fork drupal-3123070

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jungle created an issue. See original summary.

msuthars’s picture

msuthars
Location Pune
CreditAttribution: msuthars at QED42 for Drupal India Association commented
Assigned: Unassigned » msuthars
msuthars’s picture

msuthars
Location Pune
CreditAttribution: msuthars at QED42 for Drupal India Association commented
Assigned: msuthars » Unassigned
FileSize
phpcs.txt1.41 KB

@jungle I followed all the steps that you mentioned. When I run ../vendor/bin/phpcs -p command it shows me warnings related to yml files.
Like: No PHP code was found in this file and short open tags are not allowed by this install of PHP. This file may be using short open tags but PHP does not allow them.

Then I run the ../vendor/bin/phpcbf command and found there is no fixable errors.

msuthar@Drupal9-web:/var/www/html/core$ ../vendor/bin/phpcbf

No fixable errors were found

Time: 16 mins, 47.84 secs; Memory: 42MB

Please check my attached phpcs.xml (uploaded as text file) file. Is there something that I missed.

Version: 9.0.x-dev » 9.1.x-dev

Drupal 9.0.10 was released on December 3, 2020 and is the final full bugfix release for the Drupal 9.0.x series. Drupal 9.0.x will not receive any further development aside from security fixes. Sites should update to Drupal 9.1.0 to continue receiving regular bugfixes.

Drupal-9-only bug reports should be targeted for the 9.1.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.2.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented

Turns out this sniff (PSR2.Classes.PropertyDeclaration.Underscore) flags exactly the same as the sniff `Drupal.Classes.PropertyDeclaration` (#2937882: Fix 'Drupal.Classes.PropertyDeclaration' coding standard).

So basically we only have to add a comment to `core/phpcs.xml.dist` stating the above.

Spokje opened merge request !541

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Status: Active » Needs review
quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented

@quietone Can you have another look?

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Issue tags: +Coding standards
quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented

@Spokje, Sorry trouble on my end. Gitlab is showing only one change to the file, the removal of the out of scope line. What happened to the other lines? Not trusting Gitlab I went to apply the diff but it doesn't apply. This will have to wait for another day. I am off to bed and I may not be on line tomorrow.

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
FileSize
3123070-12.patch861 bytes

@quietone:

So basically there are 2 changes:

- The out-of-scope line deletion
- A comment addition explaining why sniff PSR2.Classes.PropertyDeclaration.Underscore is ignored. (this to prevent future attempts to maybe "fix" this by enabling it.)

There is a known issue about the creation of patch files from an MR (See: #3204538: GitLab Merge Requests Unable to Generate Incremental Patch Files) which might have bitten you.

I've attached a patch file that applies, also this URL: https://git.drupalcode.org/project/drupal/-/merge_requests/541/diffs works for me, 2 changes in 1 file visible.

Your original comment on the comment addition seems to have left the building, no clue why...

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented

@Spokje, thanks for making the patch.

I applied the patch and then browsed the file. On reading, 

    <!-- Silence method name underscore warning which is covered already in
      Drupal.Methods.MethodDeclaration.Underscore. -->

I searched for Drupal.Methods.MethodDeclaration.Underscore and found that it is excluded on line 113 of the file. 

  <rule ref="Drupal.Methods.MethodDeclaration">
    <!-- Silence method name underscore warning which is covered already in
      Drupal.NamingConventions.ValidFunctionName.ScopeNotCamelCaps. -->
    <exclude name="Drupal.Methods.MethodDeclaration.Underscore"/>
  </rule>

So, if that sniff is excluded it can't be covering anything. I then searched for Drupal.NamingConventions.ValidFunctionName.ScopeNotCamelCaps and didn't find it, nor did I find Drupal.NamingConventions.ValidFunctionName.

I am a bit baffled by these comments. And to add to that the title here is PropertyDeclaration not Method Declaration.

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Assigned: Unassigned » Spokje
Status: Needs review » Needs work

@quietone:

Hmmm, seem to have made a mess by doing things to quickly.

So I _am_ sure this sniff can be excluded, but seem to have forgotten the sniff that covers this one in a frenzy of copy-pasting and doing 23 things at the some time. :/

Luckily, you are here to prevent me from doing some actually damage...

Not sure if I have time today (22 things left to do... ;) but I'll get back to this and find the correct sniff and this time actually _think and check_ the comment...

Thanks for staying sharp and keeping me in check!

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Version: 9.1.x-dev » 9.3.x-dev

Spokje closed merge request !541

Spokje opened merge request !639

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented

Running ../vendor/bin/phpcs -s with only these sniffs enabled:

  <rule ref="PSR2.Classes.PropertyDeclaration.Underscore"/>

  <!-- Internal sniffs -->
  <rule ref="Internal.NoCodeFound">
    <!-- No PHP code in *.yml -->
    <exclude-pattern>*.yml</exclude-pattern>
  </rule>

returns:

FILE: core\lib\Drupal\Core\Config\Entity\ConfigEntityBase.php
------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
------------------------------------------------------------------------------------------------------------------------------------------------------
 94 | WARNING | Property name "$_core" should not be prefixed with an underscore to indicate visibility
    |         | (PSR2.Classes.PropertyDeclaration.Underscore)
------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: core\lib\Drupal\Core\DependencyInjection\DependencySerializationTrait.php
----------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 2 WARNINGS AFFECTING 2 LINES
----------------------------------------------------------------------------------------------------------------------------------------------------------------
 18 | WARNING | Property name "$_serviceIds" should not be prefixed with an underscore to indicate visibility (PSR2.Classes.PropertyDeclaration.Underscore)
 25 | WARNING | Property name "$_entityStorages" should not be prefixed with an underscore to indicate visibility
    |         | (PSR2.Classes.PropertyDeclaration.Underscore)
----------------------------------------------------------------------------------------------------------------------------------------------------------------


FILE: core\modules\views\src\ResultRow.php
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 2 WARNINGS AFFECTING 2 LINES
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
 15 | WARNING | Property name "$_entity" should not be prefixed with an underscore to indicate visibility (PSR2.Classes.PropertyDeclaration.Underscore)
 22 | WARNING | Property name "$_relationship_entities" should not be prefixed with an underscore to indicate visibility
    |         | (PSR2.Classes.PropertyDeclaration.Underscore)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------

Time: 3 mins, 27.46 secs; Memory: 44MB

This is exactly the same output as was produced #2937882-16: Fix 'Drupal.Classes.PropertyDeclaration' coding standard.

We decided to phpcs:ignore those, because the refactoring would be almost impossible without breaking BC.
This was committed to 9.2.x.

So by adding this sniff (PSR2.Classes.PropertyDeclaration.Underscore), we would have to ignore those again for this sniff.

Since I see no added value and that, and being convinced that basically PSR2.Classes.PropertyDeclaration.Underscore does the same as the already used sniff Drupal.Classes.PropertyDeclaration I propose the following:

We don't enable this sniff, but keep excluding it as we already do.

But to prevent people from wondering why it's excluded or trying to include it again, we add a remark with a explanation why it's excluded.

The MR tries to do just that.

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Status: Needs work » Needs review
Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Assigned: Spokje » Unassigned
longwave’s picture

longwave
he/him
Primary language English
Location UK
CreditAttribution: longwave at Full Fat Things commented
Status: Needs review » Needs work

I'm not sure the comment is actually correct.

Also hiding the patch as this issue is using the merge request workflow now.

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented

Thanks @longwave, you're absolutely right (as usual).

This was supposed to be the simplest patch ever, but it seems to have some kind of vengeance against me...

Let's see if I got the comment right this time :sigh:...

Spokje’s picture

Spokje
Primary language Dutch
CreditAttribution: Spokje commented
Status: Needs work » Needs review
longwave’s picture

longwave
he/him
Primary language English
Location UK
CreditAttribution: longwave at Full Fat Things commented
Status: Needs review » Reviewed & tested by the community

We'll get there in the end!

  • catch committed f5d9fec on 9.3.x 
    Issue #3123070 by Spokje, msuthars, quietone, longwave, jungle: Fix '...

  • catch committed 271bc1c on 9.2.x 
    Issue #3123070 by Spokje, msuthars, quietone, longwave, jungle: Fix '...
catch’s picture

catch
he/him
Primary language English
CreditAttribution: catch at Third and Grove commented
Status: Reviewed & tested by the community » Fixed

Committed/pushed to 9.3.x and cherry-picked to 9.2.x, thanks!

Spokje closed merge request !639

Status: Fixed » Closed (fixed)

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