Boolean sniff rules missing from the wiki?

[JakeQZ]

Customizable rules (with properties) are documented here: https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties

But I can't find any documentation for Boolean rules (which are simply enabled or disabled, with no customizable properties).

E.g. Squiz.PHP.Heredoc (which I eventually found with a hit on the code-base via a search engine). It's not covered in the annotated ruleset. It appears to have some documentation for auto-generation, but I can't find that in the wiki.

Am I missing something, or is something missing?

[jrfnl]

@JakeQZ The lists of sniffs available in each standard are not in the wiki, but at your fingertips on the command-line:

phpcs -e --standard=Generic

... will show you a list of all Generic sniffs.

phpcs -e --standard=PSR12

... will show you a list of all sniffs included in the PSR12 standard, both PSR12 specific sniffs, as well as sniffs from other standards included in the PSR12 standard.

If you want more information about each rule (in so far as available), the following command will get you documentation for each sniff in a standard:

phpcs --generator=Text --standard=PSR12

Also see #148 for which sniffs are still missing documentation.

Hope this helps. Oh, and the above is all documented in the wiki...

[JakeQZ]

The lists of sniffs available in each standard are not in the wiki, but at your fingertips on the command-line:

Thanks. It would be nice to have them in the wiki, but if there are no plans to include them there then this can probably be closed.

[jrfnl]

@JakeQZ There is no intention for the wiki to hold that information. However, there are loose plans to eventually have a website with a searchable database of sniffs.

Not making any promises, the "if" and "when" is up in the air and will depends on availability and people's willingness to contribute to getting such a project up & running.

Here are some links to existing tickets related to those plans in case you want to follow them:

• Auto-generate sniff documentation of various standards to display online PHP_CodeSniffer-documentation#1
• Docs: add missing XML documentation for sniffs #148
• Make sniff documentation more useful and more discoverable #317

[JakeQZ]

Thanks for taking the time to provide detailed replies <3.

The lists of sniffs available in each standard are not in the wiki, but at your fingertips on the command-line:

phpcs -e --standard=Generic

It's not in my PATH, as it's installed as a dependency via Composer, so I have to do

vendor\squizlabs\php_codesniffer\bin\phpcs -e --standard=Squiz

It does list all the sniffs, including the Heredoc one I mentioned in the OP. But I can't see how to then get the detail about it. phpcs -h doesn't help.

There is no intention for the wiki to hold that information. However, there are loose plans to eventually have a website with a searchable database of sniffs.

I think it would be better to have the information in the wiki. I find search functions within websites (including the BBC) to be of poor quality and less useful than using a general search engine with a term that includes the website and the desired content, e.g. "bbc iplayer last tango in halifax".

The wiki is indexed by the major search engines. They provide the search functionality. Why reinvent the wheel? :))

[jrfnl]

It's not in my PATH, as it's installed as a dependency via Composer, so I have to do

vendor\squizlabs\php_codesniffer\bin\phpcs -e --standard=Squiz

You should be able to use vendor/bin/phpcs ... instead of the long path. Might be worth a try ?
Then again, looking at the command, you appear to be using backslashes, so I suspect you may be on Windows, in which case you would need to quote the command to get that working on the normal Windows command line, i.e.: "vendor/bin/phpcs" -e --standard=Squiz.

It does list all the sniffs, including the Heredoc one I mentioned in the OP. But I can't see how to then get the detail about it. phpcs -h doesn't help.

That's where that second command I posted above comes in:

phpcs --generator=Text --standard=Squiz

You can also get the documentation of just one individual sniff by combining the above with the --sniffs flag, so try running:

"vendor/bin/phpcs" --generator=Text --standard=Squiz --sniffs=Squiz.PHP.Heredoc

Does that help ?

There is no intention for the wiki to hold that information. However, there are loose plans to eventually have a website with a searchable database of sniffs.

I think it would be better to have the information in the wiki. I find search functions within websites (including the BBC) to be of poor quality and less useful than using a general search engine with a term that includes the website and the desired content, e.g. "bbc iplayer last tango in halifax".

The wiki is indexed by the major search engines. They provide the search functionality. Why reinvent the wheel? :))

Either way, my experience with major engines indexing the GitHub wiki pages has very much been hit and miss and the search engines will often prioritize random blog posts over the official documentation in the wiki.

And then there's the fact that search engines tend to prioritize the outdated Wiki in the Squizlabs organisation over the new one in this repo, same with info on the PEAR website and even the Linux man pages. And I've even seen search engines show the CS Fixer docs instead of the PHPCS docs, even though the search query would be something like "phpcs documentation".

I'll take your opinion under advisement though and appreciate you taking the time to share your thoughts on this.

[JakeQZ]

Thanks again <3.

You should be able to use vendor/bin/phpcs ... instead of the long path.

Yes, that works.

you would need to quote the command to get that working on the normal Windows command line, i.e.: "vendor/bin/phpcs" -e --standard=Squiz.

If it's part of a (Composer) script, the quoted path-to-executable with forward-slashes ensures it's compatible with both Windows and Linux. If just typing it out on Windows, it's easier to just use backslashes without the quotes :).

That's where that second command I posted above comes in:

phpcs --generator=Text --standard=Squiz

Ah, yes, I see. This produces all the documentation, which I could put into a file for searching through. That's very useful.

search engines will often prioritize random blog posts

Yeah, the ones stuffed with meaningless drivel that Google considers to be "quality content" :/.

I was also looking for a sniff to disallow multiline strings that are not indented more than the code. A search engine did turn up squizlabs/PHP_CodeSniffer#1557, from which I conclude there isn't one for that.

The transcript here will hopefully help others facing similar issues and has enough "quality content" to be found :).

Closing, as there's nothing more to be done at this time.

[jrfnl]

If it's part of a (Composer) script, the quoted path-to-executable with forward-slashes ensures it's compatible with both Windows and Linux. If just typing it out on Windows, it's easier to just use backslashes without the quotes :).

Indeed, I figured that was were it was coming from as I've fixed that in lots of scripts over the years ;-)

Ah, yes, I see. This produces all the documentation, which I could put into a file for searching through. That's very useful.

If you prefer another format for the file, try --generator=HTML or --generator=Markdown and pipe the output to a file ;-)

I was also looking for a sniff to disallow multiline strings that are not indented more than the code. A search engine did turn up squizlabs/PHP_CodeSniffer#1557, from which I conclude there isn't one for that.

I think Greg's response in that ticket is still very valid - if the "fix" would change the value of the text, it is not a fix which PHPCS should be allowed to make.

For multi-line string concatenation or PHP 7.3+ flexible heredoc/nowdocs, checking the indentation would be possible as changing it does not change the value of the text string.

But that's a topic for another discussion. Let's not muddy the (search engine) waters in this ticket with unrelated discussions. ;-)

[JakeQZ]

I think Greg's response in that ticket is still very valid - if the "fix" would change the value of the text, it is not a fix which PHPCS should be allowed to make.

Could there not be a sniff that reports the issue, without fixing it?

[jrfnl]

Could there not be a sniff that reports the issue, without fixing it?

There could, but I have a feeling that the results would be seen as false positives in most cases, so this is not a sniff PHPCS will accept, though you could, of course, write it and include it in a custom standard.