WPTT / WPThemeReview

PHP_CodeSniffer rules (sniffs) to enforce WordPress theme review coding conventions
MIT License
207 stars 38 forks source link

Add sniff documentation #226

Open dingo-d opened 5 years ago

dingo-d commented 5 years ago

Like in the WPCS a documentation should be added for every sniff, so that the --generator can be used to generate documentation.

The TRT can benefit from this as well, because we can use this in our handbook as well (the examples).

The documentation looks something like this.

You can test what it looks like in the terminal by running

vendor/squizlabs/php_codesniffer/bin/phpcs --generator=Text

In the terminal.


-------------------------------------------------------------
| WORDPRESS CODING STANDARDS CODING STANDARD: SAFE REDIRECT |
-------------------------------------------------------------

wp_safe_redirect() should be used whenever possible to prevent open redirect vulnerabilities. One of
the main uses of an open redirect vulnerability is to make phishing attacks more credible. In this
case the user sees your (trusted) domain and might get redirected to an attacker controlled website
aimed at stealing private information.

----------------------------------------- CODE COMPARISON ------------------------------------------
| Valid: Redirect can only go to allowed         | Invalid: Unsafe redirect, can be abused.        |
| domains.                                       |                                                 |
----------------------------------------------------------------------------------------------------
| wp_safe_redirect( $location );                 | wp_redirect( $location );                       |
----------------------------------------------------------------------------------------------------
jrfnl commented 4 years ago

For anyone who wants to contribute to this, but isn't that familiar with the tooling: For in-depth step-by-step instructions on how to get started creating these docs, have a look at the sister-issue in WPCS for this: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1722