Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify and document running phpcs locally #986

Merged
merged 5 commits into from
Jun 5, 2017
+48 −7
Merged

Simplify and document running phpcs locally #986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
842c85f
Add a script to run `phpcs` locally
nylen Jun 1, 2017
4f98731
Remove the need for a separate script to run phpcs
nylen Jun 2, 2017
7db42e4
Add documentation for running phpcs locally
nylen Jun 2, 2017
f071756
Add default command line args to rulset for -s and --extensions=php
westonruter Jun 2, 2017
977dcc7
Remove '-s' argument
nylen Jun 5, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,7 @@ script:
fi
- |
if [[ "$TRAVISCI" == "phpcs" ]] ; then
find . \
-not \( -path './node_modules' \) \
-not \( -path './vendor' \) \
-name '*.php' \
| xargs -d'\n' phpcs --standard=phpcs.ruleset.xml -s
phpcs
fi
- |
if [[ "$TRAVISCI" == "js" ]] ; then
Expand Down
39 changes: 39 additions & 0 deletions docs/coding-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,3 +78,42 @@ Example:
*/
import VisualEditor from '../visual-editor';
```

## PHP

We use
[`phpcs` (PHP\_CodeSniffer)](https://github.com/squizlabs/PHP_CodeSniffer)
with the
[WordPress Coding Standards ruleset](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards)
to run a lot of automated checks against all PHP code in this project. This
ensures that we are consistent with WordPress PHP coding standards.

When making any changes to the PHP code in this project, it's recommended to
install and run `phpcs` on your computer. This is a step in our Travis CI
build as well, but it is better to catch errors locally.

You will need to install `phpcs` version 2.9.x, because the 3.x versions are
not yet compatible with the WordPress coding standards. For more information see
[this issue](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/718).

The easiest way to get `phpcs` is to download the .phar archive from the latest
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if it would be easier to make phpcs 2.9.x a Composer dependency instead? If we add a composer.json which has wp-coding-standards/wpcs among its dev-requirements then all a contributor (and Travis CI alike) would need to do is composer install and then do ./vendor/bin/phpcs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried this out, and am getting the following error:

PHP Fatal error:  Uncaught exception 'PHP_CodeSniffer_Exception' with message 'Referenced sniff "WordPress-Core" does not exist'

Is it expected that we need to call vendor/bin/phpcs --config-set?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nylen yes, that's right.

2.9.x release on GitHub:
[PHP\_CodeSniffer releases](https://github.com/squizlabs/PHP_CodeSniffer/releases).

For example:

```sh
wget \
https://github.com/squizlabs/PHP_CodeSniffer/releases/download/2.9.1/phpcs.phar \
-O ~/bin/phpcs
chmod +x ~/bin/phpcs
```

(If `~/bin` is not in your `$PATH`, pick another directory that is.)

Then you must install the `WordPress-Coding-Standards` repository and tell
`phpcs` where it lives. See instructions here:

https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#standalone

You should now be able to run `phpcs` from the root directory of this project.
10 changes: 8 additions & 2 deletions phpcs.ruleset.xml → phpcs.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,16 @@
<?xml version="1.0"?>
<ruleset name="WordPress Coding Standards for Plugins">
<description>Generally-applicable sniffs for WordPress plugins</description>
<ruleset name="WordPress Coding Standards for Gutenberg Plugin">
<description>Sniffs for WordPress plugins, with minor modifications for Gutenberg</description>

<rule ref="WordPress-Core" />
<rule ref="WordPress-Docs" />

<arg value="s"/>
<arg name="extensions" value="php"/>

<file>gutenberg.php</file>
<file>./phpunit</file>

<!-- The plugin entry point already has a file comment, I promise -->
<rule ref="Squiz.Commenting.FileComment.Missing">
<exclude-pattern>gutenberg.php</exclude-pattern>
Expand Down