Drupal Coding Standards

This project follows Drupal Coding Standards and uses the PHP Code Sniffer tool to help ensure that our own code conforms to those standards. Here are the instructions for hooking up two of the popular PHP IDEs to the tool, which is installed by composer install when you set up your development environment. These instructions assume you have cloned the repository, run composer install, and installed Visual Studio Code or PhpStorm.

(N.B.: The code sniffer is looking at the code in the file system, not at what you have staged for commit. So if you do the following:

1. edit your code in your IDE
2. see that the IDE is reporting violations of the coding standards in your code
3. stage the changes anyway (git add ...)
4. fix the coding standard violation but do not stage those fixes
5. commit what you staged in step 3

... the pre-commit hook will not be able to prevent the commit from proceeding. Later on the pipeline will catch the problems and fail the build. You can avoid this annoyance by making sure you only commit code which your IDE determines is clean. If you do not use an IDE capable of checking for coding standards violations, you probably shouldn't commit staged code which differs from unstaged versions of that code in the file system.

Visual Studio Code

1. From the menu, select View > Extensions
2. Type phpcs
3. Click Install
4. Click Reload to Activate

VS Code takes care of the rest.

PhpStorm

1. From the menu, select File > Settings (on Mac, PhpStorm > Preferences)
2. In the Preferences dialog window, select Languages & Frameworks > PHP > Code Sniffer
3. Set the Configuration dropdown field to Local
4. Click the ellipsis next to the Configuration field and enter the full path to vendor/bin/phpcs (vendor\squizlabs\php_codesniffer\bin\phpcs.bat in Windows) in the repository
5. Click Validate to verify that the code sniffer script is found correctly
6. Click OK
7. Return to the Preferences dialog window (see earlier steps), select Editor > Inspections
8. In the right panel, expand PHP
9. Under PHP, expand Quality Tools
10. Under Quality Tools, select PHP Code Sniffer Validation
11. Click the checkbox next to this selection to turn on the use of the coding standards checking tool
12. Optionally turn on Show sniff name
13. Click the circular arrows icon next to the Coding standard field to refresh the list of available standards
14. Select Drupal from the field's dropdown list
15. Click OK
16. Exit from PhpStorm
17. Open <repository-root>/.idea/inspectionProfiles/Project_Default.xml in an editor
18. Replace "Drupal" with "Drupal,DrupalPractice" in the value attribute of the CODING_STANDARD option element
19. Save the file
20. Launch the PhpStorm program again
21. Return to PHP > Quality Tools > PHP Code Sniffer Validation in the Editor > Inspections panel of the Preferences dialog window, following the navigation steps provided above
22. Verify that the Coding standard field now shows Drupal,DrupalPractice
23. Click OK to close the Preferences dialog window

Test

To verify that your IDE is correctly configured, add a new file test.php in the blt/src directory of the repository, with the following content:

<?php
/**
 * @file
 * @author Klem Kadiddlehopper
 */

Hover your mouse over the @author tag. If your editing environment is correctly configured, you should see a popup which says @author tags are not usually used in Drupal, because over time multiple contributors will touch the code anyway.