Repository files navigation

Human Made Coding Standards WordPress coding standards, enhanced for modern development.
AHuman Made project.

This is a codified version ofthe Human Made style guide. We include phpcs, ESLint, and stylelint rules.

We welcome contributions to these standards and want to make the experience as seamless as possible. To learn more about contributing, please reference theCONTRIBUTING.md file.

Each ruleset is available individually via Composer or NPM. To install the needed ruleset, use one of the following commands:

• PHPCS:composer require --dev humanmade/coding-standards
• ESLint:npx install-peerdeps --dev @humanmade/eslint-config@latest
• stylelint:npm install --save-dev stylelint @humanmade/stylelint-config

Run the following command to run the standards checks:

vendor/bin/phpcs --standard=vendor/humanmade/coding-standards .

We use theDealerDirect phpcodesniffer-composer-installer package to handleinstalled_paths for PHPCS when first installing the HM ruleset. If you an error such asERROR: Referenced sniff "WordPress-Core" does not exist, delete thecomposer.lock file andvendor directories and re-install Composer dependencies.

The final. here specifies the files you want to test; this is typically the current directory (.), but you can also selectively check files or directories by specifying them instead.

You can add this to your Travis YAML file as a test:

script:  -phpunit  -vendor/bin/phpcs --standard=vendor/humanmade/coding-standards .

This standard includes special support for a.phpcsignore file (in the future, this should bebuilt into phpcs itself). Simply place a.phpcsignore file in your root directory (wherever you're going to runphpcs from).

The format of this file is similar to.gitignore and similar files: one pattern per line, comment lines should start with a#, and whitespace-only lines are ignored:

# Exclude our tests directory.tests/# Exclude any file ending with ".inc"*\.inc

Note that the patterns should matchthe PHP_CodeSniffer style:* is translated to.* for convenience, but all other characters work like a regular expression.

Patterns are relative to the directory that the.phpcsignore file lives in. On load, they are translated to absolute patterns: e.g.*/tests/* in/your/dir/.phpcsignore will become/your/dir/.*/tests/.* as a regular expression.This differs from the regular PHP_CodeSniffer practice.

If you want to add further rules (such as WordPress.com VIP-specific rules) or customize PHPCS defaults, you can create your own custom standard file (e.g.phpcs.ruleset.xml):

<?xml version="1.0"?><ruleset><!-- Files or directories to check--><file>.</file><!-- Path to strip from the front of file paths inside reports (displays shorter paths)--><argname="basepath"value="." /><!-- Set a minimum PHP version for PHPCompatibility--><configname="testVersion"value="7.2-" /><!-- Use HM Coding Standards--><ruleref="vendor/humanmade/coding-standards" /><!-- Add VIP-specific rules--><ruleref="WordPress-VIP" /></ruleset>

You can then reference this file when running phpcs:

vendor/bin/phpcs --standard=phpcs.ruleset.xml .

You can also customise the rule to exclude elements if they aren't applicable to the project:

<ruleref="vendor/humanmade/coding-standards"><!-- Disable short array syntax--><excludename="HM.Debug.ForceShortArray" /></rule>

Rules can also be disabled inline.phpcs rules can be disabled with a// @codingStandardsIgnoreLine comment, andESLint rules can be disabled with a/* eslint disable ... */ comment.

To find out what these codes are, specify-s when runningphpcs, and the code will be output as well. You can specify a full code, or a partial one to disable groups of errors.

The phpcs standard is based upon theWordPress-VIP standard fromWordPress Coding Standards, withcustomisation and additions to match our style guide.

The ESLint package contains anESLint configuration which you can use to validate your JavaScript code style. While it is possible to run ESLint via phpcs, we recommend you install and use eslint via npm directly or uselinter-bot. Seethe@humanmade/eslint-config package README for more information on configuring ESLint to use the Human Made coding standards.

Once you have installed the@humanmade/eslint-config npm package, you may simply specify that your own project-level ESLint file extends thehumanmade configuration. If you install this globally (npm install -g @humanmade/eslint-config) you can also reference the configuration directly from the command line viaeslint -c humanmade .

Alternatively, you can create your own configuration and extend these rules:

.eslintrc

{"extends":"@humanmade"}

The stylelint package contains astylelint configuration which you can use to validate your CSS and SCSS code style. We recommend you install and use stylelint via npm directly or uselinter-bot. Seethe@humanmade/stylelint package README for more information on configuring stylelint to use the Human Made coding standards.

To integrate the Human Made rules into your project, add a.stylelintrc file and extend these rules. You can also add your own rules and overrides for further customization.

{"extends":"@humanmade/stylelint-config","rules": {...  }}