edlp_d8/sites/all/modules/examples/examples/STANDARDS.md

Developing with Coding Standards for Examples for Developers

Examples uses mostly the same coding standards as Drupal core.

If you see a discrepancy between the coding standards tools used by core and those used by Examples, please file an issue so that Examples can follow core.

Examples uses the phpcs tool to allow for checking PHP coding standards. We use the drupal/coder project for Drupal-specific coding standards.

We also use eslint for JavaScript coding standards, and csslint for CSS.

Examples has a phpcs.xml.dist file at the root of the project. phpcs uses this file to specify the current coding standards 'sniffs' which code in the project must pass.

Contributors should install phpcs in their local Drupal installation, and then use that to run phpcs against Examples as part of their development and review process. (See details below on how to install and run this tool.)

Contributors can also patch the phpcs.xml.dist file itself, in order to fix the codebase to pass a given rule or sniff. Patches which do this should be limited to a single rule or sniff, in order make the patch easier to review.

Examples also uses the Coder project (drupal/coder), which adds additional Drupal-specific coding standards. We're currently locked to Coder version 8.2.8, but this should change to reflect the state of core's coding standards.

Installing phpcs

Current versions of Drupal 8 core require phpcs and Coder as dev dependencies. That means they're already probably installed in your core vendor/ directory.

We need to tell phpcs to use the Drupal coding standard provided by Coder, because it isn't configured that way by default.

Like this:

$ cd my/drupal/root/
$ ./vendor/bin/phpcs --config-set installed_paths /full/path/to/drupal/vendor/drupal/coder/coder_sniffer/
// phpcs now knows how to find the Drupal standard. You can test it:
$ cd core
$ ../vendor/bin/phpcs -e --standard=Drupal
// Shows you a bunch of Drupal-related sniffs.

Running phpcs

Now you can run phpcs:

$ cd modules/examples
$ ../../vendor/bin/phpcs -ps
// phpcs uses Examples' phpcs.xml.dist to verify coding standards.
// -p shows you progress dots.
// -s shows you sniff errors in the report.

If there are errors, they can sometimes be fixed with phpcbf, which is part of the phpcs package.

$ ../../vendor/bin/phpcbf
// phpcbf now performs automated fixes.

Always look at the changes to see what phpcbf did.

And always re-run phpcs in order to discover whether phpcbf handled all the errors.

Installing eslint

eslint is a node.js tool. You can and probably should install it globally, since installing it locally would add files to the examples project. Instructions available here: https://www.npmjs.com/package/eslint

Examples has an .eslintrc file which defines the JavaScript coding standard. This file should be identical to the current Drupal core standard.

Running eslint

You can run eslint this way:

$ cd /path/to/examples
$ eslint .