search

squizlabs / PHP_CodeSniffer

PHP_CodeSniffer tokenizes PHP files and detects violations of a defined set of coding standards.
BSD 3-Clause "New" or "Revised" License
10.67k stars 1.48k forks source link

Use of `phpcs.xml` should really be documented #1482

Closed prometheas closed 7 years ago

prometheas commented 7 years ago

Per discussion at the end of #465, the tool has apparently automatically looked for phpcs.xml files (since 2015, no less), but this never appears anywhere in the documentation. In the age of CI, this is an especially relevant.

Please document how this mechanism works.

gsherwood commented 7 years ago

It's documented here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file

It's been there since Jan 2016 according to the history.

prometheas commented 7 years ago

Three other folks and I were at a loss for whether the tool even supported this mode, and we were actively looking for it (and the people with whom I was researching this capability use the tool so much, they've even got their own sniffs) 😉

Now maybe that just says more about us (or perhaps the kind of day we were having), but I humbly (if emphatically) suggest updating the docs to frame use of configuration file as the primary means of configuring the tool for a project. This would be inline with what I would argue is the dominant convention for most project-oriented developer tools, from other linters (ESLint, sass-lint, jshint, editorconfig, and etc) to scm tools like git, mercurial, and others.

Anyway, I certainly won't pretend like updating docs to reframe primary use-case is ever a trivial bit of work, but I believe it'd be super valuable.

Thoughts?

gsherwood commented 7 years ago

If I ever get time to overhaul the docs and turn them from a reference manual into more of an instruction manual, I'll certainly promote the phpcs.xml file more heavily.

But I'm going to close this issue, because if I'm being honest, I can't see this happening. I've got so little time to work on PHPCS as it is that I spend it working on the product itself and don't have time for more than documenting the features in a list. A proper manual needs to be something I write and commit the content to accuracy, so it's also not the sort of thing I'd accept a PR for.

This doesn't mean someone can't write an unofficial guide to PHPCS (or small parts of it), which several people have done via their blogs. Those are very helpful as they provide more search results when people go looking for how to get started, but they aren't normally as comprehensive as I imagine you (and I) are thinking.

Thanks for the feedback, even though I haven't made any changes. But I've heard you.

prometheas commented 7 years ago

Totally get that it's a spare-time project—I've got a couple on the burner myself, and finding time to tend to them is pretty tough when it's not one's primary livelihood.

That said, I'll make one last press for even a directly-linked mention of this from early on in the copy the main configuration section in the docs. I know you discouraged a PR (and, come to think of it, I don't even seem to know how to fork a wiki properly on GitHub), but it could wind up being as small a change as this:

diff --git a/Configuration-Options.md b/Configuration-Options.md
index 5819233..fff2041 100644
--- a/Configuration-Options.md
+++ b/Configuration-Options.md
@@ -1,4 +1,5 @@
 ## Table of contents
+* [Project Configuration](#project-configuration)
 * [Setting the default coding standard](#setting-the-default-coding-standard)
 * [Setting the default report format](#setting-the-default-report-format)
 * [Hiding warnings by default](#hiding-warnings-by-default)
@@ -23,6 +24,9 @@

 ***

+## Project Configuration
+If you're using PHP_CodeSniffer as part of a team, or you're running it on a [CI](https://en.wikipedia.org/wiki/Continuous_integration) server, you'll want to configure your project's settings [using a configuration file](./Advanced-Usage.md#using-a-default-configuration-file).
+

😃

glensc commented 5 years ago

yes please! i would contribute myself, but the wiki is not editable:

carcinocron commented 5 years ago

When specifically googling for a phpcs.xml file, this is the most relevant result. A quick skim of https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options makes it appear like config files aren't supported...

prometheas commented 5 years ago

Perhaps something along the lines of that super small wiki update I'd proposed back in May 2017, @gsherwood…? 😅

glensc commented 5 years ago

@prometheas but the chunk was merged to readme:

and I checked, it's still there:

prometheas commented 5 years ago

Oh, snap—totally missed that, @glensc.

image

(Edit: Homer is supposed to be disappearing into the bushes like so.)

jigarius commented 3 years ago

First of all, PHPCS is cool. Thanks for it.

I see that the issue is closed, but this morning, while trying to setup PHPCS for a 2 file project (Fizz Buzz), I realized that things can get difficult with the XML config file. Specifically, it's hard to find an exhaustive list of all the rules with documentation.

Thinking aloud

It'd be great if the following info were available for each error that phpcs reports:

I've been using PHPCS for years with Drupal, but that was very easy because all I had to do is use an existing --standard=Drupal. However, trying to use it for a quick, mini-project, I realized that it could use some easily-accessible documentation for the XML file. I'm not sure if .xml.dist comes from a PHP standard of some sort, but maybe a YML file would be easier to manage?

jrfnl commented 3 years ago

Which rule caused the error to exist

If you run phpcs with the -s option, it will show you exactly that.

For each possible rule, there should be a way of seeing the possible configurations.

For the PHPCS rules, have a look here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties