WordPress Coding Standards for PHP_CodeSniffer

This project is a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official WordPress Coding Standards.

Project history

• In April 2009 original project from Urban Giraffe was published.
• In May 2011 the project was forked on GitHub by Chris Adams.
• In April 2012 XWP started to dedicate resources to the development and currently maintains the project, along with J.D. Grimes and Gary Jones.

Installation

Composer

Standards can be installed with Composer dependency manager:

composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Running this command will:

1. Install WordPress standards into wpcs directory.
2. Install PHP_CodeSniffer.
3. Register WordPress standards in PHP_CodeSniffer configuration.
4. Make phpcs command available from wpcs/vendor/bin.

For convenience of using phpcs as global command you might want to add path to wpcs/vendor/bin directory to a PATH environment of your operating system.

Standalone

1. Install PHP_CodeSniffer by following its installation instructions (via Composer, PEAR, or Git checkout).

Do ensure, if for example you're using VVV, that PHP_CodeSniffer's version matches our requirements (you can check the required version in composer.json).

2. Clone WordPress standards repository:

    git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs
   

3. Add its path to PHP_CodeSniffer configuration:

    phpcs --config-set installed_paths /path/to/wpcs
   

To summarize:

cd ~/projects
git clone https://github.com/squizlabs/PHP_CodeSniffer.git phpcs
git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs
cd phpcs
./scripts/phpcs --config-set installed_paths ../wpcs

And then add the ~/projects/phpcs/scripts directory to your PATH environment variable via your .bashrc.

You should then see WordPress-Core et al listed when you run phpcs -i.

How to use

Command line

Run the phpcs command line tool on a given file or directory, for example:

phpcs --standard=WordPress wp-load.php

Will result in following output:

--------------------------------------------------------------------------------
FOUND 8 ERRORS AND 2 WARNINGS AFFECTING 7 LINES
--------------------------------------------------------------------------------
  1 | ERROR   | [x] End of line character is invalid; expected "\n" but found "\r\n"
 36 | ERROR   | [x] Expected 1 spaces before closing bracket; 0 found
 41 | WARNING | [ ] Silencing errors is discouraged
 41 | WARNING | [ ] Silencing errors is discouraged
 48 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
    |         |     question marks
 48 | ERROR   | [x] There must be no blank line following an inline comment
 76 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
    |         |     question marks
 92 | ERROR   | [x] String "Create a Configuration File" does not require double
    |         |     quotes; use single quotes instead
 94 | ERROR   | [ ] Expected next thing to be an escaping function (see Codex for
    |         |     'Data Validation'), not '$die'
 94 | ERROR   | [ ] Expected next thing to be an escaping function (see Codex for
    |         |     'Data Validation'), not '__'
--------------------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
--------------------------------------------------------------------------------

PhpStorm

Please see “PHP Code Sniffer with WordPress Coding Standards Integration” in PhpStorm documentation.

Sublime Text

sublime-phpcs package

Install the sublime-phpcs package, then use the "Switch coding standard" command in the Command Palette to switch between coding standards.

SublimeLinter-phpcs

sublime-phpcs is insanely powerful, but if you'd prefer automatic linting, SublimeLinter-phpcs can do that.

• Install PHP Sniffer and WordPress Coding Standards per above.
• Use Package Control to search for and install SublimeLinter then SublimeLinter-phpcs.
• From the command palette, select Preferences: SublimeLinter Settings - User and change user.linters.phpcs.standard to the phpcs standard of your choice (e.g. WordPress, WordPress-VIP, etc.).

• You may need to restart Sublime for these settings to take effect. Error messages appear in the bottom of the editor.

Atom

• Install PHP Sniffer and WordPress Coding Standards per above.
• Install linter-phpcs via Atom's package manager.
• Run which phpcs to get your phpcs executable path.
• Enter your phpcs executable path and one of the coding standards specified above (e.g. WordPress, WordPress-VIP, etc.).

Standards subsets

The project encompasses a super–set of the sniffs that the WordPress community may need. If you use the WordPress standard you will get all the checks. Some of them might be unnecessary for your environment, for example those specific to WordPress VIP coding requirements.

You can use the following as standard names when invoking phpcs to select sniffs, fitting your needs:

• WordPress — complete set with all of the sniffs in the project
• WordPress-Core — main ruleset for WordPress core coding standards
• WordPress-Docs — additional ruleset for inline documentation
• WordPress-Extra — extended ruleset for optional best practices sniffs
  • includes WordPress-Core
• WordPress-VIP — extended ruleset for WordPress VIP coding requirements
  • includes WordPress-Core

Using a custom ruleset

If you need to further customize selection of sniffs for your project — you can create custom ruleset.xml standard. See provided project.ruleset.xml.example file and fully annotated example in PHP_CodeSniffer documentation.

Recommended additional rulesets

The PHPCompatibility ruleset comes highly recommended. The PHPCompatibility sniffs are designed to analyse your code for cross-PHP version compatibility. Install it as a separate ruleset and either run it separately against your code or add it to your custom ruleset.

Fixing errors or whitelisting them

You can find information on how to deal with some of the more frequent issues in the wiki.

Contributing

See CONTRIBUTING, including information about unit testing.

License

See LICENSE (MIT).